Summary of Contents

The following list provides links to the main topics in the Database
Administrator's Guide:

Preface
Introducing Hyperion Essbase
Understanding Multidimensional Databases
Quick Start for Implementing Analytic Services
Basic Architectural Elements
Case Study: Designing a?Single-Server, Multidimensional Database
About Essbase XTD Administration Services
Creating Applications and Databases
Creating and Changing Database Outlines
Setting Dimension and Member Properties
Working with Attributes
Linking Objects to Analytic Services Data
Designing and Building Currency Conversion Applications
Designing Partitioned Applications
Creating and Maintaining Partitions
Accessing Relational Data with Hybrid Analysis
Understanding Data Loading and Dimension Building
Creating Rules Files
Using a Rules File to Perform Operations on Records, Fields, and Data
Performing and Debugging Data Loads or Dimension Builds
Understanding Advanced Dimension Building Concepts
Calculating Analytic Services Databases
Developing Formulas
Reviewing Examples of Formulas
Defining Calculation Order
Dynamically Calculating Data Values
Calculating Time Series Data
Developing Calculation Scripts
Reviewing Examples of Calculation Scripts
Developing Custom-Defined Calculation Macros
Developing Custom-Defined Calculation Functions
Understanding Report Script Basics
Developing Report Scripts
Mining an Analytic Services Database
Copying Data Subsets and Exporting Data to Other Programs
Learning to Write Queries With MaxL Data Manipulation Language
Managing Security for Users and Applications
Controlling Access to Database Cells
Security Examples
The Analytic Services Implementation of Unicode
Working With Unicode-Mode Applications
Running Analytic Servers, Applications, and Databases
Managing Applications and Databases
Using Analytic Services Logs
Managing Database Settings
Allocating Storage and Compressing Data
Ensuring Data Integrity
Backing Up and Restoring Data
Using MaxL Data Definition Language
Monitoring Performance
Improving Analytic Services Performance
Optimizing Analytic Services Caches
Optimizing Database Restructuring
Optimizing Data Loads
Optimizing Calculations
Optimizing with Intelligent Calculation
Optimizing Reports and Other Types of Retrieval
Limits
Handling Errors and Troubleshooting Analytic Services
Estimating Disk and Memory Requirements
Using ESSCMD
Glossary

Preface
Welcome to the Essbase XTD Analytic Services Database
Administrator's Guide. This preface discusses the following topics:

• Purpose
• Audience
• Document Structure
• Where to Find Documentation
• Conventions
• Additional Support

Purpose
This guide provides you with all the information that you need to
implement, design, and maintain an optimized Essbase XTD Analytic
Services multidimensional database. It explains the Analytic Services
features and options, and contains the concepts, processes, and
examples that you need to use the software.

Audience
This guide is for database administrators or system administrators who
are responsible for designing, creating, and maintaining applications,
databases, and database objects (for example, data load rules, and
calculation scripts).
Document Structure
This document contains the following information:

Chapters 1-14 contain information on designing and creating Analytic

Services databases, including information on converting currencies,
partitioning applications, and accessing relational data using the hybrid
analysis feature.

Chapters 15-34 contain information on building dimensions and

loading data, calculating data, and retrieving data.

Chapters 35-52 contain information on designing and managing a

security system, maintaining, backing up, and optimizing Analytic
Services databases, and includes a glossary of key terms and their
definitions.

Where to Find
Documentation
All Analytic Services documentation is accessible from the following
locations:

• The HTML Information Map is located at

installation_directory\docs\esb_infomap.htm, where
installation_directory is the directory in which you have
installed the Analytic Services documentation.
• The Hyperion Solutions Web site is located at
http://www.hyperion.com.
• Access to the Hyperion Download Center is through
http://hyperion.subscribenet.com.
To access documentation from the Hyperion Solutions Web site:
1. Log on to http://www.hyperion.com.
2. Select the Support link and type your username and
password to log on.

Note: New users must register to receive a username and

password.
 3. Follow the on-screen instructions.
To access documentation from the Hyperion Download Center:
1. Log on to http://hyperion.subscribenet.com.
2. In the Login ID and Password text boxes, enter your
assigned login ID name and password. Then click Login.
3. If you are a member on multiple Hyperion Download Center
accounts, select the account that you want to use for the
current session.
4. Follow the on-screen instructions.
To order printed documentation:
• Visit the Hyperion Solutions Web site at
http://www.hyperion.com.
• In the United States, call Hyperion Solutions Customer
Support at 877-901-4975.
• From outside the United States, including Canada, call
Hyperion Solutions Customer Support at 203-703-3600.
Clients who are not serviced by support from North America
should call their local support centers.

Conventions
The following table shows the conventions that are used in this
document:

Table i: Conventions Used in This Document ?

Item Meaning

Arrows indicate the beginning of procedures

consisting of sequential steps or one-step
procedures.

Brackets [] In examples, brackets indicate that the enclosed

elements are optional.

Bold Bold in procedural steps highlights major interface

elements.
CAPITAL Capital letters denote commands and various IDs.
LETTERS (Example: CLEARBLOCK command)

Ctrl + 0 Keystroke combinations shown with the plus sign

(+) indicate that you should press the first key
and hold it while you press the next key. Do not
type the plus sign.

Example  Courier font indicates that the example text is

text code or syntax.

Courier  Courier italic text indicates a variable field in

italics command syntax. Substitute a value in place of
the variable shown in Courier italics.

ARBORPATH When you see the environment variable ARBORPATH 

in italics, substitute the value of ARBORPATH from
your site.

n, x Italic n stands for a variable number; italic x can

stand for a variable number or an alphabet. These
variables are sometimes found in formulas.

Ellipses (...) Ellipsis points indicate that text has been omitted
from an example.

Mouse This document provides examples and procedures

orientation using a?right-handed mouse. If you use a left-
handed mouse, adjust the procedures accordingly.

Menu Options in menus are shown in the following

options format. Substitute the appropriate option names in
the placeholders, as indicated.
Menu name > Menu command > Extended
menu command
For example: 1. Select File > Desktop >
Accounts.
Additional Support
In addition to providing documentation and online help, Hyperion
offers the following product information and support. For details on
education, consulting, or support options, visit Hyperion's Web site at
http://www.hyperion.com.

Education Services
Hyperion offers instructor-led training, custom training, and eTraining
covering all Hyperion applications and technologies. Training is geared
to administrators, end users, and information systems (IS)
professionals.

Consulting Services
Experienced Hyperion consultants and partners implement software
solutions tailored to clients' particular reporting, analysis, modeling,
and planning requirements. Hyperion also offers specialized consulting
packages, technical assessments, and integration solutions.

Technical Support
Hyperion provides enhanced electronic-based and telephone support to
clients to resolve product issues quickly and accurately. This support is
available for all Hyperion products at no additional cost to clients with
current maintenance agreements.

Documentation
Feedback
Hyperion strives to provide complete and accurate documentation. We
value your opinions on this documentation and want to hear from you.
Send us your comments by clicking the link for the Documentation
Survey, which is located on the Information Map for your product.
Introducing Hyperion
Essbase
This chapter provides an architectural overview of the product
components and introduces the key features of Essbase products,
including:

• Essbase Analytic Services

• Essbase Deployment Services
• Essbase Administration Services
• Essbase Spreadsheet Services
• Essbase Integration Services

Essbase products provide companies with the ability to deliver critical

business information to the right people when they need it. With
Essbase, companies quickly leverage and integrate data from multiple
existing data sources and distribute filtered information to end-user
communities in the format that best meets the users' needs. Users
interact and intuitively explore data in real-time and along familiar
business dimensions, enabling them to perform speed-of-thought
analytics.

This chapter contains the following sections:

• Key Features
• Essbase Product Components

Key Features
Essbase products provide the analytic solution that integrates data
from multiple sources and meets the needs of users across an
enterprise. Essbase products enable the quick and easy
implementation of solutions, add value to previously inaccessible data,
and transform data into actionable information.
Integration with Existing Infrastructure
Essbase products integrate with your existing business intelligence
infrastructure. Essbase products meet the enterprise analytic demands
of users for critical business information with a minimum of
information technology (IT) overhead and thus enable organizations to
realize maximum return on their existing IT investments:

• Provides an extensible architecture

• Supports a comprehensive range of data sources, hardware
and operating system platforms, access interfaces, and
development languages
• Enables analytic applications to be deployed across a local or
wide area network and across an intranet or Internet

Data Integration
Essbase products allow organizations to leverage data in their data
warehouses, legacy systems, online transaction processing (OLTP)
systems, enterprise resource planning (ERP) systems, e-business
systems, customer relationship management (CRM) applications, Web
log files and other external data. For relational database integration,
Essbase XTD Integration Services provide a suite of graphical tools,
data integration services, and a metadata catalog that tie into a data
warehouse environment.

Ease of Server and Database Administration

Essbase products provide a cross-platform administration console. The
console gives you detailed control over the Essbase environment:

• You can manage multiple servers and databases.

• You can use MaxL, a syntactical language command shell with
a PERL extension module, to automate batch maintenance.

Mission Critical Applications in Web-based Environments

A middle-tier framework extends the power of Essbase products by
creating a Web-enabled, distributed platform for Essbase applications
hence serving the analysis needs of large numbers of users in Web-
based environments. Essbase XTD Deployment Services provide
connection pooling, clustering, and failover support, which extend the
scalability and reliability of the platform and support mission-critical
applications in a 24 x 7 environment.

Powerful Querying
Large communities of business users can interact with data in real
time, analyzing business performance at the speed of thought. Using
Essbase products you can organize and present data along familiar
business dimensions, thus enabling users to view and explore the data
intuitively and to turn the data into actionable information.

Complex Calculations
Essbase XTD Analytic Services 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. Analytic Services 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 database administrator can
configure a single calculation request to use multiple threads to
accomplish the calculation, providing enhanced calculation speed.

Robust Write-Back and Security

Analytic Services provides unique multi-user read and write
capabilities, including data update and multi-user recalculation.
Business users with front-end tools can write data back to a server and
recalculate the data on a server using calculation scripts - key
functionality to support sophisticated modeling and planning
applications.

The robust, multi-level security model provides server-, database-,

and cell-level security. Full control of data access, views, and write
capabilities are managed through administration. Integration with
external authentication systems, such as Lightweight Directory Access
Protocol (LDAP), allows the quick creation of security models and
reduces the time and the cost of application development and
maintenance.
Ease of Development
Analytic Services offers many key advantages to help users develop
effective multi-dimensional applications. Users can:

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

For information about supported applications, operating systems, and

networking protocols, see the Essbase XTD Analytic Services
Installation Guide.

Essbase Product
Components
Essbase products incorporate powerful architectural features to handle
a wide range of analytic applications across large multi-user
environments. This section provides information on the main product
components and the information flow from the source data to the end
user. Figure?1 provides a high-level view of the information flow
between the source data and the product components.

Analytic Services
Analytic Services-a multi-threaded OLAP database software that takes
advantage of symmetric multi processing hardware platforms-is based
upon Web-deployable, thin-client architecture. The server acts as a
shared resource, handling all data storage, caching, calculations, and
data security. The Analytic Server client needs only to retrieve and
view data that resides on a server.
All Analytic Services application components, including database
outlines and calculation scripts, application control, and multi-
dimensional database information, reside on a server. With Analytic
Services you can configure server disk storage to span multiple disk
drives, enabling you to store large databases. Analytic Services
requires a server to run a multi-threaded operating system so a server
can efficiently manage multiple, simultaneous requests. A server also
runs a server agent process that acts as a traffic coordinator for all
user requests to applications.

MaxL-a multidimensional database access language that is part of

Analytic Server-provides a flexible way to automate Analytic Services
administration and maintenance tasks.

See dev.hyperion.com or the Essbase XTD Analytic Services

Installation Guide for information on the supported operating systems,
and for specific information about server configuration requirements.

Administration Services
Administration Services-the database and system administrators'
interface to Analytic Services-provides a single-point-of-access console
to multiple Analytic Servers. Using Administration Services you can
design, develop, maintain, and manage multiple Analytic Servers,
applications, and databases. You can also use custom Java plug-ins to
leverage and extend key functionality.

Deployment Services
Deployment Services allows multiple instances of Analytic Server to
run on multiple machines, while serving the user as one logical unit
and removing and single point of failure. Deployment Services enables
database clustering with load balancing and fail-over capabilities.

Spreadsheet Products and Hyperion Analyzer

Hyperion Analyzer, Spreadsheet Services, and Spreadsheet Add-in-the
business users' interface to Analytic Services-provide interactive
analysis and delivery of corporate information to diverse user
communities. Hyperion Analyzer, Spreadsheet Services, and
Spreadsheet Add-in provide out-of-the-box solutions and easy-to-use
personalization and visualization tools allow you to create intuitive,
Web-based analysis and reporting from ERP systems, relational,
multidimensional and other data sources.

Integration Services

Integration Services-an optional product component-provides a

metadata-driven environment to bridge the gap between data stored
in Analytic Services databases and detailed data stored in relational
databases. The Hybrid Analysis feature gives business users more
detail for decision-making and IT managers more modularity in
designing and maintaining large-scale analytic applications. Hybrid
Analysis allows portions of Analytic Services databases to be stored in
a relational database. This relational stored data is mapped to the
appropriate Analytic Services hierarchies. HAL (Hyperion Application
Link) is an application integration and business process automation
tool that allows bi-directional information exchange between
transaction processing applications, desktop applications, and Hyperion
Business Performance Management applications. Figure 1: High-level
Information Flow from the Source Data to the End User
Note: For information on Hyperion Objects, Hyperion Analyzer, and
Hyperion Application Link (HAL) visit our website at
www.hyperion.com.

Application Programming Interface (API)

Analytic Services API-the developers' interface to Analytic Services-
allows you to create customized applications. The API Reference
provides a complete listing of API functions, platforms, and supported
compilers.

Developer Products
Essbase developer products enable the rapid creation, management
and deployment of tailored enterprise analytic applications-with or
without programming knowledge.

The products (for example, Application Builder, and Hyperion Objects)

provide a comprehensive set of application programming interfaces,
drag and drop components and services.

Data Mining
Data Mining-an optional product component of Analytic Services-shows
you hidden relationships and patterns in your data, enabling you to
make better business decsions. Using Data Mining you can plug in
various data mining algorithms, build models, and then apply them to
existing Analytic Services applications and databases.

Understanding
Multidimensional
Databases
Essbase XTD Analytic Services contains multidimensional databases
that support analysis and management reporting applications. This
chapter discusses multidimensional concepts and terminology. This
chapter contains the following topics:

• OLAP and Multidimensional Databases

• Dimensions and Members
• Data Storage

OLAP and
Multidimensional
Databases
Online analytical processing (OLAP) is a multidimensional, multi-user,
client-server computing environment for users who need to analyze
enterprise data. OLAP applications span a variety of organizational
functions. Finance departments use OLAP for applications such as
budgeting, activity-based costing (allocations), financial performance
analysis, and financial modeling. Sales departmentsuse OLAP for sales
analysis and forecasting. Among other applications, marketing
departments use OLAP for market research analysis, sales forecasting,
promotions analysis, customer analysis, and market/customer
segmentation. Typical manufacturing OLAP applications include
production planning and defect analysis.

Important to all of the applications mentioned in the previous

paragraph is the ability to provide managers with the information they
need to make effective decisions about an organization's strategic
directions. A successful OLAP application provides information as
needed, that is, it provides "just-in-time" information for effective
decision-making.

Providing "just-in-time" information requires more than a base level of

detailed data. "Just-in-time" information is computed data that usually
reflects complex relationships and is often calculated on the fly.
Analyzing and modeling complex relationships are practical only if
response times are consistently short. In addition, because the nature
of data relationships may not be known in advance, the data model
must be flexible. A truly flexible data model ensures that OLAP
systems can respond to changing business requirements as needed for
effective decision making.

Although OLAP applications are found in widely divergent functional

areas, they all require the following key features:

• Multidimensional views of data

• Calculation-intensive capabilities
• Time intelligence

Key to OLAP systems are multidimensional databases.

Multidimensional databases not only consolidate and calculate data;
they 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 want answers to the following
questions:

• 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 particular salespeople do a better job of selling
the product?

With a multidimensional database, 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.

Dimensions and
Members
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?2, Time is a dimension and Qtr1 is a member.

Analytic Services has two types of dimensions: standard dimensions

and attribute dimensions.

Standard dimensions represent the core components of a business

plan and often relate to departmental functions. Typical standard
dimensions are Time, Accounts, Product Line, Market, and Division.
Dimensions change less frequently than members.

Attribute dimensions are a special type of dimension that 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 non-caffeinated products that are packaged in glass
to the profitability of non-caffeinated products that are packaged in
cans.

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. A dimension can contain
an unlimited number of members. Analytic Services 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 Analytic Services database development begins with creating a
database outline. A database outline accomplishes the following:

• Defines the structural relationships between members in an

Analytic Services database
• Organizes all the data in the database
• Defines the consolidations and mathematical relationships
between items
Analytic Services 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 Analytic Services 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, roll up

the monthly data to obtain quarterly figures, and roll up the quarterly
data to obtain annual figures. Businesses may also summarize data by
zip code, by city, state, and country. Any dimension can be used to
consolidate data for reporting purposes.

In the Sample Basic database included with Analytic Server, for

example, the Year dimension consists of five?members: Qtr1, Qtr2,
Qtr3, and Qtr4, each storing data for an individual quarter, plus Year,
storing summary data for the entire year. Qtr1 consists of four
members: Jan, Feb, and Mar, each storing data for an individual
month, plus Qtr1, storing summary data for the entire quarter.
Likewise, Qtr2, Qtr3, and Qtr4 consist of the members that represent
the individual months plus the member that stores the quarterly totals.

The database outline in Figure?2 uses a hierarchical structure to

represent the data consolidations and relationships in Qtr1.

Figure 2: Hierarchical Structure

Some dimensions consist of relatively few members, while others may

have hundreds or even thousands of members. Analytic Services does
not limit the number of members within a dimension and enables the
addition of new members as needed.

Dimension and Member Relationships

Analytic Services uses the terms defined in the following sections to
describe a database outline. These terms are used throughout Analytic
Services documentation.
Analytic Services uses hierarchical and family history terms to describe
the roles and relationships of the members in an outline. You can
describe the position of the members of the branches in Figure?3 in
several ways.

Figure 3: Member Generation and Level Numbers

Parents, Children, and Siblings

Figure?3 illustrates the following parent, child, and sibling
relationships:

• 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.
Descendants and Ancestors
Figure?3 illustrates the following descendant and ancestral
relationships:

• Descendants are all 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 all members in branches above a member. For
example, Margin, Profit, and Measures are ancestors of Sales.

Roots and Leaves

Figure?3 illustrates the following root and leaf member relationships:

• 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
detail members, level 0 members, and leaf nodes. For
example, Opening Inventory, Additions, and Ending Inventory
are leaf members.

Generations and Levels

Figure?3 illustrates the following generations levels:

• 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?3, 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?4 shows part of the Product dimension with its
generations numbered.

Figure 4: Generations
 • Level also refers to a branch within a dimension; however,
levels reverse the numerical ordering that Analytic Services
uses for generations. The levels count up from the leaf
member toward the root. The root level number varies
depending on the depth of the branch. In the example in
Figure?3, 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?5 shows part of the Product dimension with its levels
numbered.

Figure 5: Levels

Generation and Level Names

To make your reports easier to maintain, you can assign a name to a
generation or level and then use the name as a shorthand for all
members in that generation or level. Because changes to an outline
are automatically reflected in a report, when you use generation and
level names, you do not need to change the report if a member name
is changed or deleted from the database outline.

Standard Dimensions and Attribute Dimensions

Analytic Services has two types of dimensions: standard dimensions
and attribute dimensions. This chapter primarily considers standard
dimensions because Analytic Services does not allocate storage for
attribute dimension members. Instead it dynamically calculates the
members when the user requests data associated with them.

An attribute dimension is a special type of dimension that is associated

with a standard dimension. For comprehensive discussion of attribute
dimensions, see Working with Attributes.

Sparse and Dense Dimensions

Most data sets of multidimensional applications have two
characteristics:

• Data is not smoothly and uniformly distributed.

• Data does not exist for the majority of member combinations.
For example, all products may not be sold in all areas of the
country.

Analytic Services maximizes performance by dividing the standard

dimensions of an application into two types: dense dimensions and
sparse dimensions. This division allows Analytic Services to cope with
data that is not smoothly distributed. Analytic Services speeds up data
retrieval while minimizing the memory and disk requirements.

Most multidimensional databases are inherently sparse: they lack data

values for the majority of member combinations. A sparse dimension is
a dimension with a low percentage of available data positions filled.

For example, the Sample Basic database shown in Figure?6 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 is a dimension with a high probability that one or
more data points 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.

In Sample Basic Database Outline, Caffeinated, Intro Date, Ounces,

and Pkg Type are attribute dimensions that are associated with the
Product dimension. Population is an attribute dimension that is
associated with the Market dimension. Members of attribute
dimensions describe characteristics of the members of the dimensions
with which they are associated. For example, each product has a size
in ounces. Attribute dimensions are always sparse dimensions and
must be associated with a sparse standard dimension. Analytic
Services does not store the data for attribute dimensions, Analytic
Services dynamically calculates the data when a user retrieves it. For a
comprehensive discussion about attribute dimensions, see Working
with Attributes.

Figure 6: Sample Basic Database Outline

Selection of Dense and Sparse Dimensions

In most data sets, existing data tends to follow predictable patterns of
density and?sparsity. If you match patterns correctly, you can store
the existing data in a reasonable number of fairly dense data blocks,
rather than in many highly sparse data blocks.

Analytic Services can make recommendations for the sparse-dense

configuration of dimensions based on the following factors:
 • The time and accounts tags on dimensions
• The probable size of the data blocks
• Characteristics that you attribute to the dimensions in this
dialog box

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 you will load into your database or multiple user
considerations.

Dense-Sparse Configuration for Sample Basic

Consider the Sample Basic database that is provided with Analytic
Services. The Sample Basic database represents data for The Beverage
Company (TBC).

TBC does not sell every product in every market; therefore, the data
set is reasonably sparse. Data values do not exist for many
combinations of members in the Product and Market dimensions. For
example, if Caffeine Free Cola is not sold in Florida, then data values
do not exist for the combination Caffeine Free Cola (100-30)->Florida.

However, consider combinations of members in the Year, Measures,

and Scenario dimensions. Data values almost always exist for some
member combinations on these dimensions. For example, data values
exist for the member combination Sales->January->Actual because at
least some products are sold in January.

The sparse-dense configuration of the standard dimensions in the

Sample Basic database may be summarized as follows:

• The sparse standard dimension are Product and Market.

• The dense standard dimensions are Year, Measures, and
Scenario.

Analytic Services creates a data block for each unique combination of

members in the Product and Market dimensions (for more information
on data blocks, see Data Storage). Each data block represents data
from the dense dimensions. The data blocks are likely to have few
empty cells.

For example, consider the sparse member combination Caffeine Free

Cola (100-30), New York, illustrated by Figure?7:

• 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, then it is likely that other accounts data values
exist for other members in the Measures dimension.
• If Actual accounts data values exist, then it is likely that
Budget accounts data values exist.

Figure 7: Dense Data Block for Sample Basic Database

Dense and Sparse Selection Scenario

Consider a database with four standard dimensions: Time, Accounts,
Region, and Product. In the following example, Time and Accounts are
dense dimensions, and Region and Product are sparse dimensions.

The two-dimensional data blocks shown in Figure?8 represent data

values from the dense dimensions: Time and Accounts. The members
in the Time dimension are J, F, M?and Q1. The members in the
Accounts dimension are Rev, Exp, and Net.
Figure 8: Two-dimensional Data Block for Time and Accounts

Analytic Services creates data blocks for combinations of members in

the sparse standard dimensions (providing 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?9 shows 11 data blocks. No data values exist for Product A in

the West?and South, for Product B in the East and West, and for
Product C in the East.?Therefore, Analytic Services has not created
data blocks for these member combinations. The data blocks that
Analytic Services has created have very few empty cells.

Figure 9: Data Blocks Created for Sparse Members on Region and

Product

This example effectively concentrates all the sparseness into the index
and concentrates all the data into fully utilized blocks. This
configuration provides efficient data storage and retrieval.
Now 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.

As shown in Figure?10, the two-dimensional data blocks represent

data values from the dense dimensions: Region and Product.

Figure 10: Two-Dimensional Data Block for Region and Product

Analytic Services creates data blocks for combinations of members in

the sparse standard dimensions (providing at least one data value
exists for the member combination). The sparse standard dimensions
are Time and Accounts.

Figure?11 shows 12 data blocks. Data values exist for all combinations
of members in the Time and Accounts dimensions; therefore, Analytic
Services creates data blocks for all the 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 11: Data Blocks Created for Sparse Members on Time and
Accounts
Data Storage
This topic describes how data is stored in a multidimensional database.
Each data value is stored in a single cell in the database. You refer to a
particular data value by specifying its coordinates along each standard
dimension.

Note: Analytic Services does not store data for attribute

dimensions. Analytic Services dynamically calculates attirbute
dimension data when a user retrieves the data.

Consider the simplified database shown in Figure?12.

Figure 12: A Multidimensional Database Outline

This database has three dimensions: Accounts, Time, and Scenario:

• The Accounts dimension has four members: Sales, COGS,

Margin, and Margin%.
• The Time dimension has four quarter members, and Qtr1 has
three month members

Note: Figure?13 shows only Qtr1 and its members.

• The Scenario dimension has two child members: Budget for

budget values and Actual for actual values.
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?13 has three dimensions; thus, the dimensions and
data values in the database can be represented in a cube.

Figure 13: Three-Dimensional Database

The shaded cells in Figure?14 illustrate that when you specify Sales,
you are specifying the portion of the database containing eight Sales
values.

Figure 14: Sales Slice of the Database

Slicing a database amounts to fixing one or more dimensions at a

constant value while allowing the other dimensions to vary.

When you specify Actual Sales, you are specifying the four Sales
values where Actual and Sales intersect as shown by the shaded area
in Figure?15.

Figure 15: Actual, Sales Slice of the Database

A data value is stored in a single cell in the database. To refer to a
specific data value in?a multidimensional database, you specify its
member on each dimension. In Figure?16, 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 16: Sales?->? Jan?->? Actual Slice of the Database

Data Blocks and the Index System

Analytic Services uses two types of internal structures to store and
access data: data blocks and the index system.

Analytic Services creates a data block for each unique combination of

sparse standard dimension members (providing that at least one data
value exists for the sparse dimension member combination). The data
block represents all the dense dimension members for its combination
of sparse dimension members.

Analytic Services creates an index entry for each data block. The index
represents the combinations of sparse standard dimension members.
It contains an entry for each unique combination of sparse standard
dimension members for which at least one data value exists.

For example, in the Sample Basic database outline shown in Figure?17,

Product and Market are sparse dimensions.

Figure 17: Product and Market Dimensions from the Sample Basic
Database

If data exists for Caffeine Free Cola in New York, then Analytic
Services 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, then Analytic Services does
not create a data block or an index entry for the sparse member
combination of 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 Analytic Services 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?18 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 18: Part of a Data Block for the Sample Basic Database

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.

Analytic Services orders the cells in a data block according to the order
of the members in the dense dimensions of the database outline.

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?19 represents the three dense dimensions from

within the combination of the sparse members d22 and e3 in the
preceding database outline. In Analytic Services, member
combinations are denoted by the cross-dimensional operator. The
symbol for the cross-dimensional operator is ->. So d22, e3 is written
d22?->?e3. A, b21, c3 is written A?->?b21?->?c3.

Figure 19: Data Block Representing Dense Dimensions for d22?->?e3

Analytic Services 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 shown in Figure?19, may include cells
that do not contain data values. A data block is created if at least one
data value exists in the block. Analytic Services 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. For more information, see Data Compression.

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.

Multiple Data Views

A multidimensional database supports multiple views of data sets for
users who need to analyze the relationships between data categories.
Slicing the database in different ways gives you different perspectives
of the data. The slice of January in Figure?20, for example, examines
all data values for which the Year dimension is fixed at Jan.

Figure 20: Data for January

The slice in Figure?21 shows data for the month of February:

Figure 21: Data for February

The slice in Figure?22 shows data for profit margin:

Figure 22: Data for Profit Margin

Quick Start for

Implementing Analytic
Services
The table in this chapter provides process steps to help you get get up
and running with Analytic Services. The table also tells you where you
can find more information about each step. Unless otherwise specified,
the chapters refer to the Essbase XTD Analytic Services Database
Administrator's Guide.

Note: This chapter assumes that you are a new Analytic Services
user. If you are migrating from a previous version of Analytic
Services, see the Essbase XTD Analytic Services Installation Guide
for important migration information.

Table 1: A Process Map ?

Process Step Reference

Learn the fundamentals of • Introducing Hyperion

Analytic Services and distributed Essbase
OLAP. • Understanding
Multidimensional
Databases
• Basic Architectural
Elements
• Creating Applications
and Databases
• Working with
Attributes
• Designing Partitioned
Applications
• Attend an Analytic
Services training
class; contact your
software provider for
details.

Assess your needs and Your budget, forecasting, and

requirements. other financial reports with
notes on how you want to
Have a clear idea of your data
analysis needs and of what types improve them
of calculations and reports you
want to run.

Analyze your data from a • Understanding

multidimensional perspective. Multidimensional
Consider the following: Databases
• Essbase XTD Analytic
• Where are your data
Services SQL
sources? Interface Guide
• What type is the data? • ODBC drivers
Is it detailed, relational documentation
data or is it higher- • Essbase XTD
level, hierarchical data
Integration Services
that can be used for
 analysis? documentation
• In what format is the
data?
• How will you access the
data? If you need to
access relational data,
you may need SQL
Interface or Integration
Services (a separately
purchasable product).

Install Analytic Services. Essbase XTD Analytic Services

Installation Guide
Decide what components you
want to install. Be aware that
the license your company
purchased might not include all
options.

Design your application and Case Study: Designing

database. a?Single-Server,
Multidimensional Database
• Identify business and
user requirements,
including security.
• Identify source data
and determine the
scope of the Analytic
Services database.
• Choose whether to
leave lowest-level
member data in a
relational database and
access with Hybrid
Analysis, or to load all
data.
• Define standard
dimensions and
designate sparse and
dense storage.
• Identify any need for
attribute dimensions.
• Identify any need for
currency conversion
 applications that track
data in different
currencies.
• Define calculations
needed for outline
dimensions and
members.
• Identify any need to
monitor data changes in
the database. You
monitor data changes
using the Analytic
Services triggers
feature (licensed
separately).

Estimate the size of your Estimating Disk and Memory

database, check disk space, and Requirements
ensure that the sizes of the
index, data files, and data
caches in memory are adequate.

Create an application and a Creating Applications and

database. Databases

Design a currency application. Designing and Building

Currency Conversion
Applications

Build an outline for your Creating and Changing

database. Database Outlines

Assign alias names to your Setting Dimension and

members. Member Properties

Build the dimensions. Decide • Understanding Data

whether your data loads will Loading and
introduce new members into the Dimension Building
outline. If so, consider • Creating Rules Files
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 • Understanding Data
data these ways: Loading and
Dimension Building
• Free-form • Creating Rules Files
• With a rules file • Using a Rules File to
• With Hybrid Analysis Perform Operations
on Records, Fields,
and Data
• Performing and
Debugging Data
Loads or Dimension
Builds
• Understanding
Advanced Dimension
Building Concepts

Calculate your database. • Calculating Analytic

Services Databases
• Decide on a type of • Developing Formulas
calculation: outline or • Reviewing Examples
calculation script, or a
of Formulas
combination of both.
• Defining Calculation
• Ensure that
Order
relationships between
• Dynamically
members and member
Calculating Data
consolidations in the
Values
database outline are
• Calculating Time
correct.
Series Data
• Consider whether
• Developing
tagging some members
Calculation Scripts
as Dynamic Calc or
• Reviewing Examples
whether using
of Calculation Scripts
Intelligent Calculation
• Developing Custom-
will improve calculation
Defined Calculation
efficiency.
Macros
• Consider which
• Developing Custom-
members you need to
Defined Calculation
tag as two-pass
Functions
calculation to ensure
correct calculation
results.

Learn about dynamic Dynamically Calculating Data

calculations and how they can Values
greatly improve performance.

View data with Spreadsheet • For Spreadsheet Add-

Add-in, other Hyperion tools, or in, see the Essbase
third-party tools. XTD Spreadsheet
Add-in User's Guide
• For other tools, see
the documentation for
that particular tool
• For a list of tools, visit
the Hyperion site:
http://www.hyperion.
com

Learn about Partitioning. Think • Designing Partitioned

about whether your data can Applications
benefit from being decentralized • Creating and
into connected databases. Maintaining Partitions

Link files or cell notes to data Linking Objects to Analytic

cells. Services Data

Copy or export data subsets. Copying Data Subsets and

Exporting Data to Other
Programs

Back up and restore your data. Backing Up and Restoring Data

Allocate storage and specify • Managing Database

Analytic Services kernel settings Settings
for your database. • Allocating Storage
and Compressing
• Data compression:
Data
Specify data
compression on disk
and the compression
scheme.
• Cache sizes: You can
specify the index, data
file, and data cache
sizes. To prevent a
slow-down 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 system's
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 Analytic
Services index files and
data files, specify the
appropriate disk volume
names and
configuration
parameters.
• Isolation level: Specify
either committed access
or uncommitted access.

Generate a report. • Understanding Report

Script Basics
• Choose a type of • Developing Report
report: structured or Scripts
free-form. • Copying Data Subsets
• Plan the elements of
and Exporting Data to
the report, such as Other Programs
page layout, number of • Mining an Analytic
columns, identity of
Services Database
members, format of
data values, and
content of titles.
• For a structured report,
create page, column,
and row headings
(unnecessary for a free-
form report).
• Create and test a report
 script, use
Administration Services'
Report Script Editor or
any other text editor.
• Save the report on
OLAP Server or on a
client computer.

Fine-tune your database • Managing Database

performance and storage Settings
settings. • Allocating Storage
and Compressing
Data
• Monitoring
Performance

Automate routine operations by • Using MaxL Data

using MaxL or ESSCMD. Definition Language
• Using ESSCMD

Design security for your • Managing Security for

database. Users and
Applications
• Create a security plan • Controlling Access to
for your environment Database Cells
based on database • Security Examples
security needs.
• Create users and
groups and assign them
administrative or data-
access permissions, if
necessary.
• Define common data
access permissions at
the scope of the server,
applications, databases,
or data-cell levels.
• To define global
application or database
permissions, select the
relevant application or
application and
database and adjust the
settings.
Maintain your applications. • Running Analytic
Servers, Applications,
and Databases
• Managing
Applications and
Databases
• Using Analytic
Services Logs
• Managing Database
Settings
• Allocating Storage
and Compressing
Data
• Ensuring Data
Integrity
• Backing Up and
Restoring Data

Analyze and improve • Monitoring

performance and troubleshoot Performance
errors if they occur. • Improving Analytic
Services Performance
• Ensure that block size is
• Optimizing Analytic
not excessively large.
Services Caches
• Set the correct size for
• Optimizing Database
the index, data file,
Restructuring
data, and calculator
• Optimizing Data
caches.
Loads
• Validate the database to
• Optimizing
ensure data integrity.
Calculations
• Consider using
• Optimizing with
partitioning to distribute
Intelligent Calculation
data across multiple
• Optimizing Reports
cubes for better
and Other Types of
scalability and
Retrieval
performance.
• Ensure that disk space
is adequate to allow the
application to grow over
time.
• Archive data from OLAP
Server on a regular
basis.
• Enable logging for
 spreadsheet update to
ensure that log files are
updated after archiving.
• If sorting on retrievals,
increase the size of the
retrieval sort buffer.

Basic Architectural
Elements
In this chapter, you will learn how Essbase XTD Analytic Services
improves performance by reducing storage space and speeding up
data retrieval for multidimensional databases. This chapter contains
the following sections:

• Attribute Dimensions and Standard Dimensions

• Sparse and Dense Dimensions
• Data Blocks and the Index System
• Selection of Sparse and Dense Dimensions
• Dense and Sparse Selection Scenarios
• The Analytic Services Solution

Attribute Dimensions
and Standard
Dimensions
Analytic Services has two types of dimensions: attribute dimensions
and standard dimensions (non-attribute dimensions). This chapter
primarily considers standard dimensions because Analytic Services
does not allocate storage for attribute dimension members. Instead it
dynamically calculates the members when the user requests data
associated with them.
An attribute dimension is a special type of dimension that is associated
with a standard dimension. For comprehensive discussion of attribute
dimensions, see Working with Attributes.

Sparse and Dense

Dimensions
Most data sets of multidimensional applications have two
characteristics:

• Data is not smoothly and uniformly distributed.

• Data does not exist for the majority of member combinations.
For example, all products may not be sold in all areas of the
country.

Analytic Services maximizes performance by dividing the standard

dimensions of an application into two types: dense dimensions and
sparse dimensions. This division allows Analytic Services to cope with
data that is not smoothly distributed, without losing the advantages of
matrix-style access to the data. Analytic Services speeds up data
retrieval while minimizing the memory and disk requirements.

Most multidimensional databases are inherently sparse: they lack data

values for the majority of member combinations. A sparse dimension is
a dimension with a low percentage of available data positions filled.

For example, the Sample Basic database shown in Figure?23 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 is a dimension with a high probability that one or
more data points 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.
Note: Caffeinated, Intro Date, Ounces, and Pkg Type are attribute
dimensions that are associated with the Product dimension.
Population is an attribute dimension that is associated with the
Market dimension. Members of attribute dimensions describe
characteristics of the members of the dimensions with which they
are associated. For example, each product has a size in ounces.
Attribute dimensions are always sparse dimensions and must be
associated with a sparse standard dimension. Analytic Services
does not store the data for attribute dimensions, Analytic Services
dynamically calculates the data when a user retrieves it. For a
comprehensive discussion about attribute dimensions, see Working
with Attributes.

Figure 23: Sample Basic Database Outline

Data Blocks and the

Index System
Analytic Services uses two types of internal structures to store and
access data: data blocks and the index system.

Analytic Services creates a data block for each unique combination of

sparse standard dimension members (providing that at least one data
value exists for the sparse dimension member combination). The data
block represents all the dense dimension members for its combination
of sparse dimension members.

Analytic Services creates an index entry for each data block. The index
represents the combinations of sparse standard dimension members.
It contains an entry for each unique combination of sparse standard
dimension members for which at least one data value exists.

For example, in the Sample Basic database outline shown in Figure?24,

Product and Market are sparse dimensions.

Figure 24: Product and Market Dimensions from the Sample Basic
Database

If data exists for Caffeine Free Cola in New York, then Analytic
Services 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, then Analytic Services does
not create a data block or an index entry for the sparse member
combination of 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 Analytic Services searches for a data value, it uses the
index to locate the appropriate data block asd shown in Figure?25.
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 25: Simplified Index and Data Blocks

Figure?26 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 26: Part of a Data Block for the Sample Basic Database
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.

Analytic Services orders the cells in a data block according to the order
of the members in the dense dimensions of the database outline.

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?27 represents the three dense dimensions from
within the combination of the sparse members d22 and e3 in the
preceding database outline. In Analytic Services, member
combinations are denoted by the cross-dimensional operator. The
symbol for the cross-dimensional operator is ->. So d22, e3 is written
d22?->?e3. A, b21, c3 is written A?->?b21?->?c3.

Figure 27: Data Block Representing Dense Dimensions for d22?->?e3

Analytic Services 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 shown in Figure?27, may include cells
that do not contain data values. A data block is created if at least one
data value exists in the block. Analytic Services 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. For more information, see Data Compression.

By carefully selecting dense and sparse standard dimensions, you can

ensure that data blocks do not contain many empty cells. In Analytic
Services, empty cells are known as missing or #MISSING data. You
can also minimize disk storage requirements and maximize
performance.
Selection of Sparse and
Dense Dimensions
In most data sets, existing data tends to follow predictable patterns of
density and?sparsity. If you match patterns correctly, you can store
the existing data in a reasonable number of fairly dense data blocks,
rather than in many highly sparse data blocks.

Changing the Sparse-Dense Configuration

When you add a dimension to an outline in Outline Editor, Analytic
Services automatically sets the dimension as sparse.

To help you determine whether dimensions should be sparse or dense,

Analytic Services provides data storage information in the Data
Storage dialog box in Application Manager.

To open the dialog box shown in Figure?28, open the database

outline and choose Settings > Data Storage.

Figure 28: Data Storage Dialog Box

Analytic Services can make recommendations for the sparse-dense
configuration of dimensions based on the following factors:

• The time and accounts tags on dimensions

• The probable size of the data blocks
• Characteristics that you attribute to the dimensions in this
dialog box

Click the Recommend button to open the recommendations portion of

the dialog box.

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 you will load into your database or multiple user
considerations.

Determining the Sparse-Dense Configuration for Sample Basic

Consider the Sample Basic database that is shipped with Analytic
Services. The Sample Basic database represents data for The Beverage
Company (TBC).

TBC does not sell every product in every market; therefore, the data
set is reasonably sparse. Data values do not exist for many
combinations of members in the Product and Market dimensions. For
example, if Caffeine Free Cola is not sold in Florida, then data values
do not exist for the combination Caffeine Free Cola (100-30)->Florida.
So, Product and Market are sparse dimensions. Therefore, if no?data
values exist for a specific combination of members in these
dimensions, Analytic Services does not create a data block for the
combination.

However, consider combinations of members in the Year, Measures,

and Scenario dimensions. Data values almost always exist for some
member combinations on these dimensions. For example, data values
exist for the member combination Sales->January->Actual because at
least some products are sold in January. Thus, Year and, similarly,
Measures and Scenario are dense dimensions.
The sparse-dense configuration of the standard dimensions in the
Sample Basic database may be summarized as follows:

• The sparse standard dimension are Product and Market.

• The dense standard dimensions are Year, Measures, and
Scenario.

Analytic Services creates a data block for each unique combination of

members in the Product and Market dimensions. Each data block
represents data from the dense dimensions. The data blocks are likely
to have few empty cells.

For example, consider the sparse member combination Caffeine Free

Cola (100-30), New York, illustrated by Figure?29:

• 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, then it is likely that other accounts data values
exist for other members in the Measures dimension.
• If Actual accounts data values exist, then it is likely that
Budget accounts data values exist.

Figure 29: Dense Data Block for Sample Basic Database

Dense and Sparse
Selection Scenarios
The following scenarios show how a database is affected when you
select different dense and sparse standard dimensions. Assume that
these scenarios are based on typical databases with at least seven
dimensions and several hundred members:

• Scenario 1: All Sparse Standard Dimensions

• Scenario 2: All Dense Standard Dimensions
• Scenario 3: Dense and Sparse Standard Dimensions
• Scenario 4: A Typical Multidimensional Problem

Scenario 1: All Sparse Standard Dimensions

If you make all dimensions sparse, Analytic Services creates data
blocks that consist of single data cells that contain single data values.
An index entry is created for each data block and, therefore, in this
scenario, for each existing data value.

This configuration produces a huge index that requires a large amount

of memory. The more index entries, the longer Analytic Services
searches to find a specific block.

Figure 30: Database with All Sparse Standard Dimensions

Scenario 2: All Dense Standard Dimensions
If you make all dimensions dense, as shown in Figure?31, Analytic
Services creates one index entry and one very large, very sparse
block. In most applications, this configuration requires thousands of
times more storage than other configurations. Analytic Services needs
to load the entire block into memory when it searches for a data value,
which requires enormous amounts of memory.

Figure 31: Database with All Dense Standard Dimensions

Scenario 3: Dense and Sparse Standard Dimensions

Based upon your knowledge of your company's data, you have
identified all your?sparse and dense standard dimensions. Ideally, you
have approximately equal?numbers of sparse and dense standard
dimensions. If not, you are probably working with a non-typical data
set and you need to do more tuning to define the dimensions.

Analytic Services creates dense blocks that can fit into memory easily
and creates a relatively small index as shown in Figure?32. Your
database runs efficiently using minimal resources.

Figure 32: An Ideal Configuration with Combination of Dense and

Sparse Dimensions
Scenario 4: A Typical Multidimensional Problem
Consider a database with four standard dimensions: Time, Accounts,
Region, and Product. In the following example, Time and Accounts are
dense dimensions, and Region and Product are sparse dimensions.

The two-dimensional data blocks shown in Figure?33 represent data

values from the dense dimensions: Time and Accounts. The members
in the Time dimension are J, F, M, and Q1. The members in the
Accounts dimension are Rev, Exp, and Net.

Figure 33: Two-dimensional Data Block for Time and Accounts

Analytic Services creates data blocks for combinations of members in

the sparse standard dimensions (providing 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?34 shows 11 data blocks. No data values exist for Product A in
the West?and South, for Product B in the East and West, and for
Product C in the East. Therefore, Analytic Services has not created
data blocks for these member combinations. The data blocks that
Analytic Services has created have very few empty cells.

Figure 34: Data Blocks Created for Sparse Members on Region and
Product

This example effectively concentrates all the sparseness into the index
and concentrates all the data into fully utilized blocks. This
configuration provides efficient data storage and retrieval.

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

As shown in Figure?35, the two-dimensional data blocks represent

data values from the dense dimensions: Region and Product.

Figure 35: Two-Dimensional Data Block for Region and Product

Analytic Services creates data blocks for combinations of members in
the sparse standard dimensions (providing at least one data value
exists for the member combination). The sparse standard dimensions
are Time and Accounts.

Figure?36 shows 12 data blocks. Data values exist for all combinations
of members in the Time and Accounts dimensions; therefore, Analytic
Services creates data blocks for all the 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 36: Data Blocks Created for Sparse Members on Time and
Accounts

The Analytic Services

Solution
When you create an optimized Analytic Services database, you need to
consider carefully the following questions:

• How does your company use the data?

• How do you plan to build and order the dimensions?
• Which data compression scheme will you use?
• How do you want to create and order calculations?
For more information on:

• Planning the development of your multidimensional database,

see Case Study: Designing a?Single-Server, Multidimensional
Database.
• Selecting dense and sparse dimensions, see Sparse and
Dense Dimensions.
• Loading data, see Understanding Data Loading and Dimension
Building.
• Compressing data and optimizing your database, see Data
Compression.
• Calculating your database, see Calculating Analytic Services
Databases.

Case Study: Designing a?Single-Server,

Multidimensional Database
To implement a multidimensional database, first you install Essbase
XTD Analytic Services, and then you design and create an application
and databases. You analyze data sources and define requirements very
carefully and then decide whether a single-server approach or a
partitioned, distributed approach best serves your needs. For criteria
that you can review to decide whether to partition an application, see
Deciding Whether to Partition a Database.

Using a case study, this chapter provides an overview of the database

planning process and discusses working rules that you can follow to
design a single-server, multidimensional database solution for your
organization. For detailed information about building applications and
databases, see Creating Applications and Databases.

This chapter includes the following topics:

• Process for Designing a Database

• Case Study: The Beverage Company
• Analyzing and Planning
• Drafting Outlines
• Checking System Requirements
• Loading Test Data
• Defining Calculations
• Defining Reports
• Verifying the Design
Process for Designing a
Database
As illustrated in Figure?37, designing an application is a cyclic process
that moves from a planning stage to a verification stage.

Figure 37: The Database Design Cycle

The database design process includes the following basic steps:

1. Analyze business needs and design a plan.

The application and database that you create must satisfy the
information needs of your users adn your organization.
Therefore, you identify source data, define user information
access needs, review security considerations, and design a
database model. See Analyzing and Planning.
2. Draft a database outline.
The outline determines the structure of the database-what
information is stored and how different pieces of information
relate to one another. See Drafting Outlines.
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.
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.
5. Define calculations.
You test outline consolidations and write and test formulas and
calculation scripts for specialized calculations. See Defining
Calculations.
6. Define reports.
Users access data through print and online reports and
spreadsheets or on the World Wide Web. If you plan to provide
predefined reports to users, you design report layouts and run
reports. See Defining Reports.
7. Verify with users.
You want to ensure that the database satisfies your user goals.
You must solicit and carefully consider the opinions of users. See
Verifying the Design.
8. Repeat the process.
To fine-tune the design, you repeat steps 1 through 7.

Case Study: The

Beverage Company
This chapter bases the database planning process on the needs of a
fictitious company called The Beverage Company (TBC) and uses TBC
as an example to demonstrate how to build an Analytic Services
database. The examples follow a variation of the Sample Basic
application that is included with the Analytic Services installation.

TBC manufactures, markets, and distributes soft drink products

internationally. Analysts at TBC prepare budget forecasts and compare
performance to budget forecasts on a monthly basis. 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 Analytic Services 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 will have access to the server and will be able to
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.

Analyzing and Planning

The design and operation of an Analytic Services multidimensional
database plays a key role in achieving a well-tuned system that
enables you to analyze business information efficiently. Given the size
and performance volatility of multidimensional databases, developing
an optimized database is critical. A?detailed plan that outlines data
sources, user needs, and prospective database elements can save you
development and implementation time.

The planning and analysis phase involves three tasks:

• Analyzing Source Data

• Identifying User Requirements
• Planning for Security in a Multiple User Environment
• Creating Database Models

When designing a multidimensional application, consider these factors:

• How information flows within the company-who uses what

data for what purposes
• The types of reporting the company does-what types of data
must be included in the outline to serve user reporting needs

Note: The best practices recommendation is to define only one

database per application. There are several reasons for this
recommendation, including enhanced memory usage and ease of
database administration. Applications that use the optional Analytic
Services currency conversion module are an exception to this
recommendation. Currency conversion applications generally
consist of a main database and a separate currency database (see
Designing and Building Currency Conversion Applications).

Analyzing Source Data

First, you need to evaluate the source data that you want to include in
the database. Think about where the data resides and how often you
plan to update the database with the data. This up-front research
saves time when you create the database outline and load data into
the Analytic Services database.

Determine the scope of the database. If an organization has thousands

of product families containing hundreds of thousands of products, you
may want to store data values only for product families. Interview
members from each user department to find out what data they
process, how they process data today, and how they want to process
data in the future.

Carefully define reporting and analysis needs.

• How do users want to view and analyze data?

• How much detail should the database contain?
• Does the data support the desired analysis and reporting
goals?
• If not, what additional data do you need and where can you
find the needed data?

Determine the location of the current data.

• Where does each department currently store data?

• Is data in a form that Analytic Services can use?
• Do departments store data in a DB2 database on an IBM
mainframe, in a relational database on a UNIX-based server,
or in a PC-based database or spreadsheet?
• Who updates the database and how frequently?
• Do the individuals who need to update data have access to
the data?

Make sure that the data is ready to load into Analytic Services.
 • Does data come from a single source or from multiple
sources?
• Is data in a format that Analytic Services can import? For a
list of valid data sources that you can import into Analytic
Services, see Data Sources.
• Is all data that you want to use readily available?

Identifying User Requirements

Be sure to discuss information needs with users. Review the
information they use and the reports they must generate for review by
others. Determine the following requirements.

• What types of analysis do users require?

• What summary and detail levels of information do users
need?
• Do some users require access to information that other users
should not see?

Planning for Security in a Multiple User Environment

The time to think about the type of security permissions you plan to
issue for an Analytic Services database is when you consider user
information needs. End your analysis with a list of users and
permissions.

Use this checklist to plan for security:

• Who are the users and what permissions should they have?
• Who should have load data permissions?
• Which users can be grouped, and as a group, given similar
permissions?

See Managing Security for Users and Applications for information

about assigning user permissions.

Creating Database Models

You are now ready to 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 choose to analyze the following areas:

• Time periods
• Accounting measures
• Scenarios
• Products
• Distribution channels
• Geographical regions
• Business units

Use the following topics to help you gather information and make
decisions:

• Identifying Analysis Objectives

• Determining Dimensions and Members
• Analyzing Database Design

Identifying Analysis Objectives

After you identify the major areas of information in a business, the
next step in designing an Analytic Services database is deciding how
the database enables data analysis:

• If analyzing by time, which time periods are needed? Does

the analysis need to include only the current year or multiple
years? Does the analysis need to include quarterly and
monthly data? Does the analysis need to include data by
season?
• 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, do you need to review data for
each specific product? Can you summarize data into product
classes?

Regardless of the business area, you need to determine the

perspective and detail needed in the analysis. Each business area that
you analyze provides a different view of the data.
Determining Dimensions and Members
You can represent each of the business views as a separate standard
dimension in the database. If you need to analyze a business area by
classification or attribute, such as by the size or color of products, you
can use attribute dimensions to represent the classification views.

The dimensions that you choose determine what types of analysis you
can perform on the data. With Analytic Services, you can use as many
dimensions as you need for analysis. A typical Analytic Services
database contains at least seven standard dimensions (non-attribute
dimensions) and many more attribute dimensions.

When you have an idea of what dimensions and members you need,
review the following topics and develop a tentative database design:

• Relationships Among Dimensions

• Example Dimension-Member Structure
• Checklist for Determining Dimensions and Members

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.

Relationships Among Dimensions

Next, consider the relationships among the business areas. The
structure of an Analytic Services database makes it easy for users to
analyze information from many different perspectives. A financial
analyst, for example, may ask the following questions:

• What are sales for a particular month? How does this figure
compare to sales in the same month over the last five years?
• By what percentage is profit margin increasing?
• How close are actual values to budgeted values?

In other words, the analyst may want to examine information from

three different perspectives-time, account, and scenario. The sample
database shown in Figure?38 represents these three perspectives as
three dimensions, with one dimension represented along each of the
three axes:

• A time dimension, which consists of the individual months

Jan, Feb, and Mar and the total for Qtr1, is 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 38: Cube Representing Three Database Dimensions

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.

Example Dimension-Member Structure

Table?2 shows a summary of the TBC business areas that the planner
determined would be dimensions. The dimensions represent the major
business areas to be analyzed. The planner created three columns,
with the dimensions in the left column and members in the two right
columns. The members in column 3 are subcategories of the members
in column 2. In some cases, members in column 3 are divided into
another level of subcategories; for example, the Margin of the
Measures dimension is divided into Sales and COGS.

Table 2: TBC Sample Dimensions ?

Dimensions Members Child Members
Year Qtr1 Jan, Feb, Mar

Qtr2 Apr, May, Jun

Qtr3 Jul, Aug, Sep

Qtr4 Oct, Nov, Dec

Measures Profit Margin: Sales, COGS

Total Expenses: Marketing, Payroll,
Miscellaneous

Inventory Opening Inventory, Additions,

Ending Inventory

Ratios Margin %, Profit %, Profit per Ounce

Product Colas (100) Cola (100-10), Diet Cola (100-20),

Caffeine Free Cola (100-30)

Root Beer Old Fashioned (200-10), Diet Root

(200) Beer (200-20), Sarsaparilla (200-
30), Birch Beer (200-40)

Cream Soda Dark Cream (300-10), Vanilla Cream

(300) (300-20), Diet?Cream Soda (300-
30)

Fruit Soda Grape (400-10), Orange (400-20),

(400) Strawberry (400-30)
Market East Connecticut, Florida, Massachusetts,
New Hampshire, New York

West California, Nevada, Oregon, Utah,

Washington

South Louisiana, New Mexico, Oklahoma,

Texas

Central Colorado, Illinois, Iowa, Missouri,

Ohio, Wisconsin

Scenario Actual

Budget

Variance

Variance %

In addition the planner added two attribute dimensions to enable

product analysis based on size and packaging:

Table 3: TBC Sample Attribute Dimensions

Dimensions Members Child Members

Ounces Large 64, 32, 20

Small 16, 12

Pkg Type Bottle

Can

Checklist for Determining Dimensions and Members

Use the following checklist when determining the dimensions and
members of your model database:

• What are the candidates for dimensions?

 • Do any of the dimensions classify or describe other
dimensions? These dimensions are candidates for attribute
dimensions.
• Do users want to qualify their view of a dimension? The
categories by which they qualify a dimension are candidates
for attribute dimensions.
• What are the candidates for members?
• How many levels does the data require?
• How does the data consolidate?

Analyzing Database Design

While the initial dimension design is still on paper, you should review
the design according to a set of guidelines. The guidelines help you to
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.

Keep in mind that the number of members needed to describe a

potential data point should determine the number of dimensions. As
you analyze the design, if you are not sure that 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, as needed,

to improve your database design:

• Dense and Sparse Dimensions

• Standard and Attribute Dimensions
• Dimension Combinations
• Repetition in Outlines
• Interdimensional Irrelevance
• Reasons to Split Databases
• Checklist to Analyze the Database Design

Dense and Sparse Dimensions

You need to decide which dimensions are sparse and which dense.
These decisions affect performance. For a basic introduction, see
Sparse and Dense Dimensions. For a comprehensive discussion of
storage and performance, see Designing an Outline to Optimize
Performance.
Standard and Attribute Dimensions
For simplicity, the examples in this topic show alternative
arrangements for what was initially designed as two dimensions. You
can apply the same logic to all?combinations of dimensions.

Consider the design for a company that sells products to multiple

customers over multiple markets; the markets are unique to each
customer:

             Cust A  Cust B  Cust C

New York     100     N/A     N/A
Illinois     N/A     150     N/A
California   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
       Illinois
             Cust B
       California
             Cust C 
 

However, if you look at a larger sampling of data, you may see that
there can be many customers 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. This time, the company can
ship to a customer that has locations in different markets:

             Cust A  Cust B  Cust C

New York     100      75     N/A
Illinois     N/A     150     N/A
California   150     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 more than one
attribute member. 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) include the following combinations:

• Year across Measures

• Year across Product
• Year across Market
• Year across Scenario
• Measures across Product
• Measures across Market
• Measures across Scenario
• Market across Product
• Market across Scenario
• Scenario across Product
• Ounces across Pkg Type

As attribute dimensions associated with the Product dimension, Ounces

and Pkg Type can be considered with the Product dimension.

To help visualize each dimension, you can draw a matrix and include a
few of the first generation members. Figure?39 shows a simplified set
of matrixes for three dimensions.

Figure 39: Analyzing Dimensional Relationships

For each combination of dimensions, ask three questions:

• Does it add analytic value?

• Does it add utility for reporting?
• Does it avoid an excess of unused combinations
combinations?

For each combination, the answers to the questions help determine if

the combination is valid for the database. Ideally, the answers to all
questions should be yes. If all answers are not yes, you should
consider rearranging the data into dimensions that are more
meaningful. As you work through this process, be sure to discuss
information needs with users.

Repetition in Outlines
The repetition of elements in an outline often indicates a need to split
dimensions. Here is an example of repetition and a solution:

Repetition No Repetition
Accounts Accounts
???Budget ???Profit
?????Profit ??????Margin
????????Margin ?????????Sales
???????????Sales ?????????COGS
???????????COGS ??????Expenses
????????Expenses Scenario
???Actual ????Budget
?????Profit ????Actual
????????Margin
???????????Sales
???????????COGS
????????Expenses

Separating Budget and Actual and placing them into another

dimension simplifies the outline and provides a simpler view of the
budget and actual figures of the other dimensions in the database.

The left column of this table uses shared members in the Diet
dimension to analyze diet beverages. You can avoid the repetition of
the left column and simplify the design of the outline by creating a Diet
attribute dimension, as shown in the second example.

Repetition No Repetition
Product Product (Diet)
????100 (Alias: Colas) ????100 (Alias: Colas)
??????????100-10 (Alias: ??????????100-10 (Alias: Cola)
Cola) (Diet: False)
??????????100-20 (Alias: Diet ??????????100-20 (Alias: Diet
Cola) Cola) (Diet: True)
????200 (Alias: Root Beer) ????200 (Alias: Root Beer)
??????????200-20 (Alias: Diet ??????????200-20 (Alias: Diet
Root Beer) Root Beer) (Diet: True)
??????????200-30 (Alias: ??????????200-30 (Alias: Birch
Birch Beer) Beer) (Diet: False)
????300 (Alias Cream Soda) ????300 (Alias Cream Soda)
??????????300-10 (Alias: Dark ??????????300-10 (Alias: Dark
Cream) Cream) (Diet: False)
??????????300-20 (Alias: Diet ??????????300-20 (Alias: Diet
Cream) Cream) (Diet: True)
????Diet (Alias: Diet Drinks) Diet Attribute (Type: Boolean)
??????????100-20 (Alias: Diet ?????True
Cola) ?????False
??????????200-20 (Alias: Diet
Root Beer)??????
??????????300-20 (Alias: Diet
Cream)
Attribute dimensions also provide additional analytic capabilities. For a
review of the advantages of using attribute dimensions, see Designing
Attribute Dimensions.

Interdimensional Irrelevance
Interdimensional irrelevance occurs when many members of a
dimension are irrelevant across other dimensions. Analytic Services
defines irrelevant data as data that Analytic Services 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 to be
irrelevant in the context of?a?corporate database. Most salaries are
confidential and apply to specific 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 are compared with members of the
Measures dimension. Only the Salary measure is relevant to individual
employees.

Table 4: Interdimensional Irrelevance Example ?

Joe Mary Mike All
Smith Jones Garcia Employees

Revenue x

Variable x
Costs

COGS x

Advertising x

Salaries x x x x

Fixed Costs x
Expenses x

Profit x

Reasons to Split Databases

As discussed in the previous topic, Interdimensional Irrelevance, TBC
agreed that, in context with other dimensions, individual employees
were irrelevant. They also agreed that adding an Employee dimension
substantially increased database storage needs. Consequently, they
decided to create a separate Human Resources (HR) database. The
new HR database contains a group of related dimensions and includes
salaries, benefits, insurance, and 401(k) plans.

There are many reasons for splitting a database; for example, suppose
that a company maintains an organizational database that contains
several international subsidiaries located in several time zones. Each
subsidiary relies on time-sensitive financial calculations. You may want
to split the database for groups of subsidiaries in the same time zone
to ensure that financial calculations are timely. You can also use a
partitioned application to separate information by subsidiary.

Checklist to Analyze the Database Design

Use the following checklist to analyze the database design:

• Have you minimized the number of dimensions?

• For each dimensional combination, did you ask:
o Does it add analytic value?
o Does it add utility for reporting?
o Does it avoid an excess of unused combinations?
• Did you avoid repetition in the outline?
• Did you avoid interdimensional irrelevance?
• Did you split the databases as necessary?

Drafting Outlines
At this point, you can create the application and database and build
the first draft of the outline in Analytic Services. 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, you must
create an Analytic Services application to contain it.

The TBC planners issued the following draft for a database outline. In
this plan, the bold words are the dimensions-Year, Measures, Product,
Market, Scenario, Pkg Type, and Ounces. Observe how TBC anticipated
consolidations, calculations and formulas, and reporting requirements.
The planners also used product codes rather than product names to
describe products.

• 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. Analytic Services 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, and 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 respective region-
East, West, South, or Central. Each region consolidates into
Market.
 • Scenario. TBC derives and tracks budget data 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 market areas. Establishing the Ounces attribute
dimension helps users to 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 and Member Properties

• Dimension Types
• Member Storage Properties
• Checklist for Dimension and Member Properties
• Designing an Outline to Optimize Performance

Dimension and Member Properties

An outline is comprised of dimensions and members. Dimensions and
members have specific properties that provide access to built-in
functionality. The properties of dimensions and members define the
roles of the dimensions and members in the design of the
multidimensional structure. These properties include the following:

• Dimension types and attribute associations. See Dimension

Types.
• Data storage properties. See Member Storage Properties.
• Consolidation operators. See Consolidation of Dimensions and
Members.
• Formulas. See Formulas and Functions.

For a complete list of dimension and member properties, see Setting

Dimension and Member Properties.
Dimension Types
A dimension type is a property that Analytic Services provides that
adds special functionality to a dimension. The most commonly used
dimension types are time, accounts, and attribute. This topic uses
dimensions of the TBC database to illustrate dimension types.

Figure 40: TBC Dimensions and Related Properties

Database:Design
???Year (Type: time)
???Measures (Type: accounts)
???Product
???Market
???Scenario
???Pkg Type (Type: attribute)
???Ounces (Type: attribute) 
 

Table?5 defines each Analytic Services dimension type.

Table 5: Dimension Types ?

Dimension
Description
Types

None Specifies no particular dimension type.

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 Analytic Services
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.
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
type of currency used in each member.
For example, Canada has three markets-
Vancouver, Toronto, and Montreal. They use the
same currency type, Canadian dollars.

Currency Separates local currency members from the base

partition 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 US dollars, and the
local currency members may contain values that
are based on the currency type of their region.

Member Storage Properties

With Analytic Services, you can specify data storage properties for
members; data storage properties define where and when
consolidations are stored. For example, by default, members are
tagged as store data. Analytic Services sums the values of store data
members and stores the result at the parent level.

You can change the default logic for each member by changing the
data storage property tag for the member. For example, you can
cahnge a store data member to label only member. Members with the
label only tag, for example, do not have data associated with them.

Table?6 describes Analytic Services data storage properties.

Table 6: Analytic Services Data Storage Properties ?

Storage Effects on Members
Properties

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.

Dynamic Calc The data associated with the member is not

and Store calculated until it is requested by a user. The
calculated data is then stored.

Shared The data associated with the member comes from

member another member with the same name.

Never share The data associated with the member is

duplicated with its parent or child if an implied
shared relationship exists.

Label only Although a label only member has no data

associated with it, it can still 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.

Checklist for Dimension and Member Properties

• Can you identify a time dimension?
• Can you identify an accounts dimension?
• 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?
• What members require special data storage properties?

Designing an Outline to Optimize Performance

When you design an outline, you must position attribute dimensions at
the end of the outline. You should position dense dimensions before
sparse dimensions.

The position of dimensions in an outline and the storage properties of

dimensions can affect two areas of performance-how quickly
calculations are run and how long it takes users to retrieve
information.

Use the following topics to understand performance optimization

basics:

• Optimizing Query Performance

• Optimizing Calculation Performance
• Meeting the Needs of Both Calculation and Retrieval

Optimizing Query Performance

To optimize query performance, use the following guidelines when you
design an outline:

• If the outline contains attribute dimensions, make sure that

the attribute dimensions are the only sparse Dynamic Calc
dimensions in the outline.
• In the outline, place the most queried sparse dimensions
before the less queried sparse dimensions.

The outline shown in Figure?41 is designed for optimum query

performance:

Figure 41: Designing an Outline for Optimized Query Times

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

Optimizing Calculation Performance

To optimize calculation performance, order the sparse dimensions in
the outline by their number of members, starting with the dimension
that contains the fewest members.

For information about factors that affect calculation performance, see

Designing for Calculation Performance.

The outline shown in Figure?42 is designed for optimum calculation

performance:

Figure 42: Designing an Outline for Optimized Calculation Times

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

Meeting the Needs of Both Calculation and Retrieval

Even though they contain the same dimensions, the example outlines
of Figure?41 and Figure?42 are different. To determine the best outline
sequence for a situation, you must prioritize the data retrieval
requirements of the users against the time needed to run calculations
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, remember to resequence the dimensions in the outline to
optimize calculation.

Checking System
Requirements
After you determine the approximate number of dimensions and
members in your Analytic Services database, you are ready to
determine the system requirements for the database.

• Make sure that you have enough disk space. See Determining
Disk Space Requirements.
• Make sure that you have enough memory. See Estimating
Memory Requirements.
• Make sure that your caches are set correctly. See Optimizing
Analytic Services Caches..
Loading Test Data
Before you can test calculations, consolidations, and reports, you need
data in the database. During the design process, loading mocked-up
data or a subset of real data provides flexibility and shortens the time
required to test and analyze results.

Detailed instructions for loading data are in the following chapters:

• Understanding Data Loading and Dimension Building

• Creating Rules Files
• Using a Rules File to Perform Operations on Records, Fields,
and Data
• Performing and Debugging Data Loads or Dimension Builds
• Understanding Advanced Dimension Building Concepts

After you run your preliminary test, if you are satisfied with your
database design, test the loading of the complete set of real data with
which you will populate the final database, using the test rules files if
possible. This final test may reveal problems with the source data that
you did not anticipate during earlier phases of the database design
process.

Defining Calculations
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 Analytic Services databases:

• Consolidation of Dimensions and Members

• Tags and Operators on Example Measures Dimension
• Accounts Dimension Calculations
• Formulas and Functions
• Dynamic Calculations
• Two-Pass Calculations
For details on Analytic Services calculations, see the following
chapters:

• Calculating Analytic Services Databases

• Developing Custom-Defined Calculation Functions
• Optimizing with Intelligent Calculation

Consolidation of Dimensions and Members

When you define members of standard dimensions, Analytic Services
automatically tags the members with the addition (+) consolidator,
meaning that during consolidation members are added. As
appropriate, you can change a member consolidation property to one
of the following operators: -, *, /, %, and ~ (no consolidation).

Consolidation is the most frequently used calculation in Analytic

Services. This topic uses the Product dimension to illustrate
consolidations.

The TBC application has several consolidation paths:

• 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.
• States roll up to regions, and regions consolidate into Market.
• Months roll up into quarters, and quarters consolidate into
Year.

The following topics discuss consolidation in greater detail:

• Effect of Position and OPerator on Consolidation

• Consolidation of Shared Members
• Checklist for Consolidation

Consolidation operators define how Analytic Services rolls up data for

each member in a?branch to the parent. For example, using the
default operator (+), Analytic Services adds 100-10, 100-20, and 100-
30 and stores the result in their parent, 100, as shown in Figure?43.

Figure 43: TBC Product Dimension

The Product dimension contains mostly (+), operators, which indicate
that each group of members is added and rolled up to the parent. Diet
has a tilde (~), which indicates that Analytic Services does not include
the Diet member in the consolidation to the parent, Product. The Diet
member consists entirely of members that are shared or duplicated.
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.

The following topics discuss consolidation in more detail:

• Effect of Position and OPerator on Consolidation

• Consolidation of Shared Members
• Checklist for Consolidation

Effect of Position and OPerator on Consolidation

Analytic Services calculates the data of a branch in top-down order. For
example, if you have, in order, two members tagged with an addition
symbol?(+) and a third member tagged with a multiplication symbol
(*). Analytic Services adds the first two and multiplies the sum by the
third.

Be aware that Analytic Services always begins with the top member
when it consolidates, so the order and the labels of the members is
very important. For an example of how Analytic Services applies
operators, see Calculating Members with Different Operators.
Table?7 shows the Analytic Services consolidation operators.

Table 7: Consolidation Operations ?

Operator Description

+ The default operator. When a member has the +

operator, Analytic Services adds the member to the
result of previous calculations performed on
members of the branch.

- When a member has the - operator, Analytic Services

multiplies the member by -1 and then adds the
product to the result of previous calculations
performed on members of the branch.

* When a member has the * operator, Analytic Services

multiplies the member by the result of previous
calculations performed on members of the branch.

/ When a member has the / operator, Analytic Services

divides the member into the result of previous
calculations performed on members of the branch.

% When a member has the % operator, Analytic

Services divides the member into the sum of
previous calculations performed on members of the
branch. The result is multiplied by 100.

~ When a member has the ~ operator, Analytic

Services does not use it in the consolidation to its
parent.

Consolidation of Shared Members

Shared members also affect consolidation paths. The shared member
concept enables two members with the same name to share the same
data. The shared member stores a pointer to data contained in the
other member, so Analytic Services stores the data only once. Shared
members must be in the same dimension. Data can be shared by two
or more members.
Checklist for Consolidation
Use the following checklist to help define consolidation:

• Have you identified the consolidations in the outline?

• Did you tag each member with the proper consolidation
operator?
• Did you specify a shared member tag for designated
members?
• Would shared members be more efficient if designed within
an attribute dimension (other than shared)?

Tags and Operators on Example Measures Dimension

The Measures dimension is the most complex dimension in the TBC
outline because it uses both time and accounts data. It also contains
formulas and special tags to help Analytic Services calculate the
outline. This topic discusses the formulas and tags that TBC included in
the Measures dimension (the dimension tagged as accounts).

Take a moment to look closely at the Measures dimension tags defined

by TBC (in?Figure?44). Many of the properties of the Measures
dimension are discussed in previous topics of this chapter: positive
(+), negative (-), and tilde (~) consolidation operators as well as
accounts and label only tags:

Figure 44: TBC Measures Dimension

 • The Inventory and Ratios member names assist the user in
data navigation and 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.
• Some members of Measures have a time balance tag (TB First
or TB Last). Time balance tags are discussed in Setting Time
Balance Properties.

Accounts Dimension Calculations

This topic discusses two forms of calculations for a dimension tagged
as accounts:

• Time Balance Properties

• Variance Reporting

Time Balance Properties

Note the two tags in the Measures dimension of Table?9-TB first and
TB last. These tags, called time balance tags or properties, provide
instructions to Analytic Services about how to calculate the data in a
dimension tagged as accounts. To use the tags, you must have a
dimension tagged as accounts and a dimension tagged as time. The
first, last, average, and expense tags are available exclusively for use
with accounts dimension members.

In the TBC Measures dimension, Opening Inventory data represents

the inventory that TBC carries at the beginning of each month. The
quarterly value for Opening Inventory is equal to the Opening value for
the quarter. Opening Inventory requires the time balance tag, TB first.

Ending Inventory data represents the inventory that TBC carries at the
end of each month. The quarterly value for Ending Inventory is equal
to the ending value for the quarter. Ending Inventory requires the time
balance tag, TB last. Table?8 shows the time balance tags for the
accounts dimension.

Table 8: Accounts Member Tags ?

Tags Description
Time The value for the last child member is carried to
Balance Last the parent. For example, March is carried to Qtr1.

Time The value for the first child is carried to the parent.
Balance First For?example, Jan is carried to Qtr1.

Table?9 shows how consolidation in the time dimension is affected by

time balance properties in the accounts dimension; details are shown
only for first quarter:

Table 9: TBC Consolidations Affected by Time Balance Properties

Accounts ->
Jan Feb Mar Qtr1 Year
Time

Accounts 11 12 13 36 Qtr1 + Qtr2 + Qtr3 +

Member1 Qtr4

Accounts 20 25 21 20 20
Member2
(TB First)

Accounts 25 21 30 30 Value of Qtr4

Member3
(TB Last)

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, then any parent
in the time dimension matches the member marked as TB First.

For examples of the use of time balance tags, see Setting Time
Balance Properties.

Variance Reporting
One of the TBC Analytic Services requirements 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.

Analytic Services provides two variance reporting properties-expense

and non-expense. The default is non-expense. Variance reporting
properties define how Analytic Services 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.

Formulas and Functions

You can define formulas to calculate relationships between members in
the database outline. You can either apply the formulas to members in
the outline, or you can place the formulas in a calculation script. This
topic explains how TBC optimized the performance of its database by
using formulas.

Functions are predefined routines that perform specialized calculations

and return sets of members or sets of data values. Formulas are
composed of operators and functions, as well as dimension names,
member names, and numeric constants.

Analytic Services supports the following operators:

• Mathematical operators that perform arithmetic operations

• Conditional operators that build logical conditions into
calculations
• Cross-dimensional operators that point to data values of
specific database member combinations

The Analytic Services functions include over 100 predefined routines to

extend the calculation capabilities of Analytic Services. Analytic
Services supports the following functions:

• Boolean functions, which provide a conditional test by

returning a TRUE or FALSE value
 • Mathematical functions, which perform specialized
mathematical calculations
• 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 whihc 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
• Statistical functions, which calculate advanced statistics
• Date and time functions, which use date and time
characteristics in calculation formulas
• Calculation mode functions, which specify the calculation
mode that Analytic Services uses to calculate a formula

The Measures dimension uses the following formulas:

• Margin = Sales - COGS

• Total Expenses = Marketing + Payroll + Miscellaneous
• Profit = Margin - Total Expenses
• Profit % = Profit % Sales
• Margin % = Margin % Sales
• Profit per Ounce = Profit / @ATTRIBUTEVAL(Ounces)

Analytic Services uses consolidation operators to calculate the Margin,

Total Expenses, and Profit members. The Margin% formula uses a %
operator, which means "express Margin as a 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.

For a complete list of operators, functions, and syntax, see the

Technical Reference. For a comprehensive discussion of how to use
formulas, see Developing Formulas.
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, Analytic Services calculates the combinations of that
member when you retrieve the data, instead of pre-calculating 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.

As shown in Figure?45, the TBC Measures dimension contains several

members that are tagged as Dynamic Calc-Profit, Margin, Total
Expenses, Margin %, and Profit?%.

Figure 45: TBC Measures Dimension, Dynamic Calc Tags

When an overall database calculation is performed, the Dynamic Calc

members and their corresponding formulas are not calculated. Rather,
the members are calculated when a user requests them, for example,
from Spreadsheet Add-in. Analytic Services 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:

• Optimum regular calculation time (batch calculation)

• Low disk space usage
• Reduced database restructure time
• Speedy data retrieval for users
 • Reduced backup time

For a comprehensive discussion of dynamic calculation, see

Dynamically Calculating Data Values.

Two-Pass Calculations
In the TBC database, both Margin % and Profit % contain the label
two-pass. This default label indicates that some member formulas
need to 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 examples illustrate why Profit % (based on the formula
Profit%Sales) has a two-pass tag.

Analytic Services loads data into the system as follows:

Measures -> Year Jan Feb Mar Qtr1

.
Profit 100 100 100

.
Sales 1000 1000 1000

. . . .
Profit %

Analytic Services calculates Measures first. The data then looks as

follows:

Measures -> Year Jan Feb Mar Qtr1

.
Profit 100 100 100

.
Sales 1000 1000 1000

Profit % 10% 10% 10%

Next, Analytic Services calculates the Year dimension. The data rolls
up across the dimension.
Measures -> Year Jan Feb Mar Qtr1

Profit 100 100 100 300

Sales 1000 1000 1000 3000

Profit % 10% 10% 10% 30%

The result in Profit % -> Qtr1 of 30% is not correct. However, because
TBC tagged Profit% as two-pass calculation, Analytic Services
recalculates profit percent at each occurrence of the member Profit %.
The data is then correct and is displayed as follows:

Measures -> Year Jan Feb Mar Qtr1

Profit 100 100 100 300

Sales 1000 1000 1000 3000

Profit % 10% 10% 10% 10%

Checklist for Calculations

Use the following checklist when you define a calculation:

• Does the default calculation logic achieve accurate results?

• Which members require formulas?
• Which members require time balance tags?
• Which members require variance reporting?
• Which members require two-pass calculation?
• Which members can be tagged as Dynamic Calc?

Note: The triggers feature provided by Analytic Services enables

efficient monitoring of data changes in a database. For moare
information, see Understanding Triggers definitions. Triggers is
licensed separately from Analytic Services.
Defining Reports
To be sure the design meets user information requirements, you need
to view data as users view it. Users typically view data through
spreadsheets, printed reports, or reports published on the Web. There
are many tools available through Hyperion and Hyperion partners for
producing the reporting systems that users use.

Analytic Services provides several tools that can help you during the
design process to display and format data quickly and to test whether
the database design meets user needs. You can use Administration
Services Console Report Script Editor to write report scripts quickly.
Those familiar with spreadsheets can use the Spreadsheet Add-in or
Spreadsheet Services (Spreadsheet Services requires Deployment
Services).

During the design phase, check for the following things:

• 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 Spreadsheet Add-in 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?

If you provide predesigned reports for users, now is the time to use
the appropriate tool to create those 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. They should
provide the right combinations of data and the right amount of data.
Reports with too many columns and rows are very hard to use. It may
be better to create a number of different reports instead of one or two
all-inclusive reports.

Verifying the Design

After you analyze the data and create a preliminary design, you need
to check all aspects of the design with the users. You should have
already checked to see if the database satisfies the users' analysis and
reporting needs. Make sure that you check with the users to ensure
that the database satisfies all of their goals.

Do the calculations give them the information they need? Are they
able to generate reports quickly? Are they satisfied with consolidation
times? In short, ask users if the database works for them.

Near the end of the design cycle, you need to test with real data. Does
the outline build correctly? Does all data load? If the database fails in
any area, repeat the steps of the design cycle to identify the cause of
the problem.

Analytic Services provides several sources of information to help you

isolate problems. Sources include application and Analytic Server logs,
exception logs, and database information accessible from
Administration Services. Look at documentation topics relevant to your
problem; for example, topics about security, calculations, reports, or
general error messages. You can also use the index of this guide to
find help for solving problems. Look up such terms as troubleshooting,
logs, optimizing, performance, recovery, resources, errors, and
warnings.

Most likely, you will need to repeat one or more steps of the design
process to arrive at the ideal database solution.

About Essbase XTD

Administration Services
Essbase XTD Administration Services is the new cross-platform
administration tool for Essbase XTD Analytic Services, replacing
Application Manager. Administration Services consists of a Java middle-
tier server, called Administration Server, and a Java client console,
called Administration Services Console. The console is the graphical
user interface that enables administrators to manage the Analytic
Services environment from a single navigation tree, called Enterprise
View. The console provides wizards, editors, and other tools to help
administrators view, manage, and maintain multiple Essbase XTD
Analytic Servers.

For more information about Administration Server, see About

Administration Server. For more information about Administration
Services Console, see "Features of the Administration Services
Console" in Essbase XTD Administration Services Online Help.

For information about which Analytic Server releases work with

Administration Services, see Essbase XTD Administration Services
Installation Guide.

Administration Services
Architecture
Administration Services works with Analytic Servers in a three-tiered
system that consists of a client user interface, a middle-tier server, and
one or more Analytic Servers. The middle tier coordinates interactions
and resources between the user interface and Analytic Servers. The
three tiers may or may not be on the same computer or platform. The
three tiers include the following components, as illustrated below:

Figure 46: Administration Services Architecture

• Client tier (Administration Services Console): A Java-based

client console provides a user interface to manage the
 Analytic Services environment. The console can run on any
platform supported by Analytic Services.
• Middle tier (Administration Server): A Java-based server
maintains communication, session, and security information
for connections to Analytic Servers. Administration Server can
run on any platform supported by Analytic Services.
• Database tier (Analytic Server): One or more Analytic Servers
store and process multidimensional database information.
Analytic Servers are installed separately from Administration
Services.

Deploying
Administration Services
Administration Services can be deployed in a variety of scenarios. For
example, you can install Analytic Server on a computer running UNIX
and install Administration Server and Administration Services Console
on a computer running Windows. You can also install Administration
Server and Administration Services Console on separate computers
and platforms.

For more information about deployment scenarios and guidelines, see

Essbase XTD Administration Services Installation Guide.

Starting and Stopping

Administration Services
Before you start Administration Services, make sure that the Analytic
Servers you want to manage are started.

To start Administration Services, first start Administration Server, and

then start Administration Services Console. For instructions, see
"Starting Administration Services" in Essbase XTD Administration
Services Installation Guide.
About Administration
Services Users
Existing Analytic Services users cannot use Administration Services
until they have also been created as Administration Services users.
You can use the User Setup Wizard to step you through the process of
creating Administration Services users and associating them with the
appropriate Analytic Servers. Administration Services users are
different from Analytic Server users; you only need to create
Administration Services users if they will be using Administration
Services Console to manage Analytic Services. You do not to create
spreadsheet users on the Administration Server.

To create Administration Services users, see "User Setup Wizard" in

Essbase XTD Administration Services Online Help.

Connecting to
Administration Services
In Administration Services, connections to individual Analytic Servers
are handled by the middle tier Administration Server. You do not need
to provide a username and password to connect to individual Analytic
Servers. For information about how Analytic Server connections are
established, see "About Analytic Services Connections and Ports" in
Essbase XTD Administration Services Online Help.

Your Administration Services username and password and your

Analytic Server username and password may be different. If you do
not know your Administration Services username and password, see
your Administration Services administrator for more information.

After you connect to Administration Services, use the User Setup

Wizard to set up Analytic Server access for Administration Services
users. For more information, see "Connecting to Administration
Services" in Essbase XTD Administration Services Online Help.
Adding Analytic Servers
to Enterprise View
After you have connected to Administration Services, the Analytic
Servers you have chosen are displayed in Enterprise View, which is the
navigation tree in the left navigation panel. You can use the User
Setup Wizard to populate Enterprise View with a specific set of Analytic
Servers. Each Administration Services user can populate Enterprise
View with a different set of Analytic Servers. You can also create
custom views of the Enterprise View tree in separate tabs in the
navigation panel. For more information, see "About Custom Views" in
Essbase XTD Administration Services Online Help.

Each time you connect to Administration Services, you are

automatically connected to each Analytic Server you have chosen to
display in Enterprise View. To operate on an Analytic Server that you
have added to Enterprise View, that server must be running.

To populate Enterprise View, see "Adding OLAP Servers to Enterprise

View" in Essbase XTD Administration Services Online Help.

About Analytic Server

Connections and Ports
The number of ports available for an Analytic Server represents the
number of licensed concurrent connections. Analytic Services provides
one reserve port for the system administrator. A system administrator
uses the reserve port to log out one or more users when all other ports
are in use. For more information about Analytic Services ports, see
Running Analytic Servers, Applications, and Databases.

In Administration Services, a port is in use only when an Analytic

Server connection is established. For information about how
connections (ports) are established and released, see "About Analytic
Services Connections and Ports" in Essbase XTD Administration
Services Online Help.
About Administration
Server
The middle tier Administration Server provides business logic to
support cross-server operations, persistence of user preferences, and
access to Analytic Servers. A system administrator creates users on
Administration Server, and then Administration Server manages their
connections to Analytic Services.

In Enterprise View, the node name for Administration Server is the

same as the server computer name.

Administration Server has several configurable communication ports.

These ports are different from Analytic Server ports. If one of the
default communication ports is in use by another application, you need
to specify another port value in order to run Administration Server.

Note: If you change the value for the Administration Server port,
you must specify the new port value when you log in to the
Administration Services Console.

To change a default port value, see "Specifying Communication Ports

for Administration Server" in Essbase XTD Administration Services
Online Help.

Creating Applications
and Databases
An Analytic Services application is a container for a database and its
related files. This chapter provides an overview of Analytic Services
applications and databases and explains how to create applications,
databases, and some Analytic Services objects, including substitution
variables and location aliases. For information on everyday
management of applications, databases, and their associated files, see
the Essbase XTD Analytic Services Optimization and Database
Administration information in this guide.
This chapter includes the following sections:

• Process for Creating Applications and Databases

• Understanding Applications and Databases
• Understanding Database Objects
• Creating Applications and Databases
• Using Substitution Variables
• Using Location Aliases

Process for Creating

Applications and
Databases
To create an application and database, follow these steps:
1. Design the application. See Quick Start for Implementing
Analytic Services,
2. Create a new application. See Creating a New Application.
3. Create a new database. See Creating a New Database.
4. If necessary, set substitution variables at the Analytic Server,
application, or database level. See Using Substitution
Variables.
5. If necessary, set a location alias for the database. See Using
Location Aliases.
6. Create the outline. See Creating and Changing Database
Outlines.

For more information about applications and database, see

Understanding Applications and Databases and Understanding
Database Objects.
Understanding
Applications and
Databases
An Analytic Services application is a management structure that
contains one or more Analytic Services databases and related files.
Analytic Services applications and databases reside on an Analytic
Server. The server machine can store multiple applications.

An Analytic Services database is a data repository that contains a

multidimensional data storage array. A multidimensional database
supports multiple views of data so that users can analyze the data and
make meaningful business decisions. For more information about
multidimensional databases, see Understanding Multidimensional
Databases. For more information about how Analytic Services stores
data, see Storage Allocation.

This diagram shows the relationships among the parts of an

application:

Figure 47: Parts of an Analytic Services Application

Understanding
Database Objects
Files that are related to databases are called objects. Database objects
perform actions against one or more Analytic Services databases, such
as defining calculations or reporting against data. By default, objects
are stored in their associated database folder on the Analytic Server.
They can also be saved to a client machine or to other available
network directories. However, you cannot load data or calculate data
on a client machine.

In Analytic Services, the common types of objects include the

following:

• A database outline (a storage structure definition)

• Data sources
• Rules for loading data and building dimensions dynamically
(rules files)
• Scripts that define how to calculate data (calculation scripts)
• Scripts that generate reports on data (report scripts)
• Security definitions
• Linked reporting objects
• Partition definitions

Some of these objects are optional, such as calculation scripts and

linked reporting objects. For a complete list of application and
database file types, see Application and Database File Types.

In Administration Services Console, database objects are displayed

under their associated applications or database in the Enterprise View
tree.

Understanding Database Outlines

Database outlines define the structure of a multidimensional database,
including all the dimensions, members, aliases, properties, types,
consolidations, and mathematical relationships. The structure defined
in the outline determines how data is stored in the database.
When a database is created, Analytic Services creates an outline for
that database automatically. The outline has the same name as the
database (dbname.otl). For example, when the Basic database is
created within the Sample application, an outline is created in the
following directory:

ARBORPATH/app/sample/basic/basic.otl 
 

For information about creating outlines, see Creating a New Database

and Creating and Changing Database Outlines.

Understanding Data Sources

A data source is external data that is loaded into an Analytic Services
database. The common types of data sources include the following:

• Text files
• Spreadsheet files
• Spreadsheet audit log files
• External databases, such as an SQL database

For a list of supported data sources, see Supported Data Sources.

Understanding Rules Files for Data Load and Dimension Build

An Analytic Services database contains no data when it is first created.
Data load rules files are sets of operations that Analytic Services
performs on data from an external data source file as the data is
loaded, or copied, into the Analytic Services database. Dimension build
rules files create or modify the dimensions and members in an outline
dynamically based on data in an external data source. Rules files are
typically associated with a particular database, but you can define
rules for use with multiple databases. A single rules file can be used
for both data loads and dimension builds. Rules files have the .RUL 
extension.

For information about creating rules files, see Rules Files and Creating
Rules Files.
Understanding Calculation Scripts
Calculation scripts are text files that contain sets of instructions telling
Analytic Services how to calculate data in the database. Calculation
scripts perform different calculations than the consolidations and
mathematical operations that are defined in the database outline.
Because calculation scripts perform specific mathematical operations
on members, they are typically associated with a particular database.
You can, however, define a calculation script for use with multiple
databases. Calculation scripts files have the .CSC extension.

For information about creating calculation scripts, see Developing

Calculation Scripts.

Understanding Report Scripts

Report scripts are text files that contain data retrieval, formatting, and
output instructions to create a report from the database. Report scripts
are typically associated with a particular database, but you can define
a report script for use with multiple databases. Report scripts have the
.REP extension.

For information about creating report scripts, see Developing Report

Scripts.

Understanding Security Definitions

Analytic Services provides a comprehensive system for managing
access to applications, databases, and other objects. Each application
and database contains its own security definitions that restrict user
access.

For information about setting up and maintaining security information,

see Managing Security for Users and Applications.

Understanding Linked Reporting Objects

A linked reporting object is an object associated with a specific data
cell in an Analytic Services database. Linked reporting objects can
enhance data analysis capabilities by providing additional information
on a data point.

A linked reporting object can be any of the following:

 • A paragraph of descriptive text (a "cell note")
• A separate file that contains text, audio, video, or graphics
• A Uniform Resource Locator (URL) for a Web site
• A link to data in another Analytic Services database

For a comprehensive discussion about using linked reporting objects,

see Linking Objects to Analytic Services Data.

Understanding Spreadsheet Queries

Within Spreadsheet Add-in, users can create and save queries using
Query Designer (EQD). The queries can be accessed at a later time by
any user with access to the query. Query files created using Query
Designer have the .EQD extension.

For more information, see the Essbase XTD Spreadsheet Add-in User's
Guide for Excel or Lotus?1-2-3.

Understanding Member Select Definitions

Within Spreadsheet Add-in, users can define and save member
retrievals with the member select feature. Member specification files
have the .SEL extension.

For more information, see the Essbase XTD Spreadsheet Add-in User's
Guide for Excel or Lotus?1-2-3.

Understanding Triggers definitions

The triggers feature provided by Analytic Services enables efficient
monitoring of data changes in a database. Triggers is licensed
separately from Analytic Services. If data breaks rules that you specify
in a trigger, Analytic Services can send an email alert (to a user or
system administrator) or log relevant information in a file. For
example, you might want to send an email to the sales manager if, in
the Western region, sales for a month fall below sales for the
equivalent month in the previous year.

To create, change, display, and delete triggers, use the following

MaxL statements:

Tool Topic Location

MaxL create or replace trigger Technical Reference
alter trigger
display trigger
drop trigger

To administer triggers, a user must have Database Designer security

privilege.

Analytic Services monitors and potentially activates triggers during the

following activities:

• Dataload
• Calculation
• Lock and send from Spreadsheet Add-in

Analytic Services does not activate triggers during a database

restructure.

You can see information on enabled and disabled triggers in the

application log file when you start Analytic Server.

Note: To enable Analytic Services to send email alerts, you must

have Java Virtual Machine (JVM) installed on your system.

Creating Applications
and Databases
Since applications contain one or more databases, first create an
application and then create databases. If desired, annotate the
databases. The following sections describe how to create applications,
databases, and database notes:

• Creating a New Application

• Creating a New Database
• Annotating a Database
• Rules for Naming Applications and Databases
Creating a New Application
When you create an application on the Analytic Server, Analytic
Services creates a subdirectory for the application on the Analytic
Server in the ARBORPATH/app directory. The new subdirectory has the
same name as the application; for example, essbase/app/app1. In
Administration Services Console, applications and databases are
displayed in a tree structure in Enterprise View.

Be sure to consult Rules for Naming Applications and Databases before

entering the application name.

You can also create a new application that is a copy of an existing

application. For more information, see Copying or Migrating
Applications.

To create a new application, use any of the following methods:

Tool Topic Location

Administration Creating Essbase XTD Administration

Services Applications Services Online Help

MaxL create Technical Reference

application

ESSCMD CREATEAPP Technical Reference

Creating a New Database

When you create a database, Analytic Services creates a subdirectory
for the database within the application directory. The new subdirectory
has the same name as the database; for example,
essbase/app/app1/db1. In Administration Services Console,
applications and databases are displayed in a tree structure in
Enterprise View.

You can create normal databases or currency databases. For more

information on currency databases, see Designing and Building
Currency Conversion Applications.
Be sure to consult Rules for Naming Applications and Databases before
entering the database name.

To create a new database, use any of the following methods:

Tool Topic Location

Administration Creating Essbase XTD Administration

Services Databases Services Online Help

MaxL create Technical Reference

database

ESSCMD CREATEDB Technical Reference

Annotating a Database
A database note can provide useful information in situations where 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
Spreadsheet Add-in. In Excel, for example, users use the Note button
in the Connect dialog box.

To annotate a database, see "Annotating Databases" in the Essbase

XTD Administration Services Online Help.

Rules for Naming Applications and Databases

When naming applications and databases, follow these rules:

• 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.
• Do not use spaces anywhere in the name.
• Do not use the following special characters anywhere in the
name:
* asterisks + plus signs
\ backslashes ? question marks
[] brackets " double quotation marks
: colons ; semicolons
, commas ' single quotation marks
 = equal signs / forward slashes
> greater than signs tabs
< less than signs | vertical bars
. periods
•

Enter the name in the case you want it to appear in. The application or
database name will be created exactly as you enter it. If you enter the
name as all capital letters (for instance, NEWAPP), Analytic Services
will not automatically convert it to upper and lower case (for instance,
Newapp).

Using Substitution
Variables
Substitution variables act as global placeholders for information that
changes regularly; each variable has a value assigned to it. The value
can be changed at any time by the database designer; thus, manual
changes are reduced.

For example, many reports depend on reporting periods; if you

generate a report based on the current month, you have to 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 in calculation scripts, report scripts,

or in Spreadsheet Add-in. You cannot use substitution variables in
formulas that you apply to the database outline. For information about
using substitution variables, refer to the following chapters:

• For calculation scripts, see Developing Calculation Scripts.

• For reports, see Developing Report Scripts.
• For Spreadsheet Add-in, see the Essbase XTD Spreadsheet
Add-in User's Guide for Excel or Lotus?1-2-3.
You can set substitution variables on the Analytic Server using
Administration Services, MaxL, or ESSCMD. Set the variable at any of
the following levels:

• Analytic Server-providing access to the variable from all

applications and databases on the Analytic Server
• Application-providing access to the variable from all
databases within the application
• Database-providing access to the variable within the specified
database

Rules for Setting Substitution Variable Names and Values

Keep in mind the following rules when setting substitution variables:

• The substitution variable name must be composed of

alphanumeric characters or underscores ( _ ) and cannot
exceed the limit specified in Limits.
• The substitution variable name cannot include non-
alphanumeric characters, such as hyphens (-), asterisks (*),
and slashes (/).
• The substitution variable value cannot exceed 256 characters.
You can use any combination of characters in the value name.
The value may contain any character except the leading
ampersand (&).
• If the substitution variable value is numeric, you must enclose
it in quotes. For example, if the variable name is Month and
its corresponding value is 01 (corresponding to January),
place quotes around 01 ("01").

Setting Substitution Variables

You can set substitution variables on the Analytic Server at the server,
application, or database level. Be sure to consult Rules for Setting
Substitution Variable Names and Values before setting a substitution
variable.

To set a substitution variable, use any of the following methods:

Tool Topic Location

Administration Managing Essbase XTD

Services Substitution Variables Administration Services
 Online Help

MaxL alter system Technical Reference

alter application
alter database

ESSCMD CREATEVARIABLE Technical Reference

Deleting Substitution Variables

You may need to delete a substitution variable that is no longer used.

To delete a substitution variable, use any of the following methods:

Tool Instructions For More Information

Administration Managing Essbase XTD

Services Substitution Variables Administration Services
Online Help

MaxL alter system Technical Reference

alter application
alter database

ESSCMD DELETEVARIABLE Technical Reference

Updating Substitution Variables

You can modify or update existing substitution variables. Be sure to
consult Rules for Setting Substitution Variable Names and Values
before updating a substitution variable.

To update a substitution variable, use any of the following methods:

Tool Instructions For More Information

Administration Managing Essbase XTD

Services Substitution Variables Administration Services
Online Help

MaxL alter system Technical Reference

alter application
alter database

ESSCMD UPDATEVARIABLE Technical Reference

Copying Substitution Variables

You can copy substitution variables to any OLAP Server, application, or
database to which you have appropriate access.

To copy a substitution variable, see "Copying Substitution Variables"

in Essbase XTD Administration Services Online Help.

Using Location Aliases

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 username, and a password. You
need database designer permissions to set location aliases.

After you create a location alias, you can use the alias to refer to that
database. If?the location of the database changes, you can edit the
location definition accordingly.

Note: You can use location aliases only with the @XREF function.
With this function, 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. For more information on @XREF, see the
Technical Reference.

• Creating Location Aliases

• Editing or Deleting Location Aliases
Creating Location Aliases
You can create a location alias for a particular database.

To create a location alias, use any of the following methods:

Tool Topic Location

Administration Creating Location Essbase XTD

Services Aliases Administration Services
Online Help

MaxL create location Technical Reference

alias

ESSCMD CREATELOCATION Technical Reference

Editing or Deleting Location Aliases

You can edit or delete location aliases that you previously created.

To edit or delete a location alias, use any of the following methods:

Tool Topic Location

Administration Editing or Deleting Essbase XTD

Services Location Aliases Administration Services
Online Help

MaxL display location Technical Reference

alias
drop location alias

ESSCMD LISTLOCATIONS Technical Reference

DELETELOCATION
Creating and Changing
Database Outlines
The database outline defines the structure of the database. Outline
Editor displays the dimension hierarchy of an outline visually. This
chapter explains how to create and manage an Analytic Services
database outline. All examples in this chapter are based on the Sample
Basic database shipped with Analytic Services.

This chapter contains the following sections:

• Process for Creating Outlines

• Creating and Editing Outlines
• Adding Dimensions and Members to an Outline
• Understanding the Rules for Naming Dimensions and
Members
• Setting Data Storage Properties
• Verifying Outlines
• Saving Outlines

You can also change outlines using data sources and rules files. For
more information, see Understanding Data Loading and Dimension
Building.

For basic information about outlines, see Understanding

Multidimensional Databases.

For information on setting properties in an outline, see Setting

Dimension and Member Properties.

Process for Creating

Outlines
This section provides an overview of creating outlines using Outline
Editor. For more information about outlines, see Dimensions and
Members. To learn how to use Outline Editor, see "About Outline
Editor" and "Customizing Outline Viewer and Outline Editor" in the
Essbase XTD Administration Services Online Help.

To create an outline, follow these steps:

1. Create a new database. The new database automatically
contains a blank outline. See Creating Applications and
Databases.
2. Open the outline. See Creating and Editing Outlines.
3. Add dimensions and members to the outline. See Adding
Dimensions and Members to an Outline.
4. Set each dimension as dense or sparse. See Setting Data
Storage Properties.
5. Position dimensions and members in the outline. See
Positioning Dimensions and Members.
6. Set dimension and member properties. See Setting
Dimension and Member Properties.
7. If necessary, create attribute dimensions and associate them
with the appropriate base dimensions. See Working with
Attributes.
8. Verify and save the outline. See Verifying Outlines and Saving
Outlines.

Creating and Editing

Outlines
When a database is created, Analytic Services creates an outline for
that database automatically. The outline has the same name as the
database (dbname.otl) and is stored in the database directory on
Analytic Server. You can create content in the new outline in the
following ways:

• Open the empty outline created by default when you create a

database and add content manually.
• Copy an existing outline to the current database and change
the existing outline.
• Create content in the outline using data sources and rules
files. For more information, see Understanding Data Loading
and Dimension Building.
In Administration Services, you can open an existing outline in edit
mode (using Outline Editor) or in read-only mode (using Outline
Viewer). Outlines opened in edit mode consume more memory on the
Administration Server than outlines opened in read-only mode. For
more information, see "Opening and Editing Outlines" in Essbase XTD
Administration Services Online Help.

When you open an outline in Outline Editor, you can view and
manipulate the dimensions and members graphically. An outline is
always locked when it is opened in edit mode. If you have Supervisor
permissions, you can unlock a locked outline. For more information,
see "Locking and Unlocking Outlines" in Essbase XTD Administration
Services Online Help.

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. Because it can be
difficult to keep track of what changes are saved or overwritten,
Hyperion does not recommend this practice.

To create a new outline or open an existing outline, use any of the

following methods:

Tool Topic Location

Administration Opening and Essbase XTD

Services Editing Outlines Administration Services
Online Help

MaxL create Technical Reference

database

ESSCMD CREATEDB Technical Reference

To copy an existing outline, use any of the following methods:

Tool Topic Location

Administration Copying Essbase XTD Administration

Services Outlines Services Online Help

MaxL create Technical Reference

 database as

ESSCMD COPYDB Technical Reference

Locking and Unlocking

Outlines
In Outline Editor, an outline is always locked when it is opened in edit
mode. Analytic Services unlocks the outline when the outline is closed.
When an outline is locked, Analytic Services does not allow other users
to save over, rename, delete, or edit the outline. When you attempt to
edit a locked outline, you are given an option to view the outline in
Outline Viewer. For more information about Outline Editor and Outline
Viewer, see Creating and Editing Outlines.

If you have Supervisor permissions, you can unlock a locked outline.

Before you forcefully unlock a locked outline, make sure that no one
else is working with it.

Note: Analytic Services uses a different process for locking and

unlocking outlines than for other database objects. For more
information about object locking, see Locking and Unlocking
Objects.

To unlock an outline, use any of the following methods:

Tool Topic Location

Administration Locking and Essbase XTD

Services Unlocking Outlines Administration Services
Online Help

MaxL create database Technical Reference

as

ESSCMD UNLOCKOBJECT Technical Reference

Adding Dimensions and
Members to an Outline
After you create an outline, you can add dimensions and member
hierarchies to the outline manually using Outline Editor or with a data
source and rules file using Data Prep Editor.

Be sure to consult Understanding the Rules for Naming Dimensions

and Members before naming dimensions and members.

To add dimensions and members to an outline using Outline Editor,

see "Adding Dimensions to Outlines" and "Adding Members to
Dimensions" in the Essbase XTD Administration Services Online Help.
To add dimensions and members to an outline using Data Prep
Editor, see "Creating a Dimension Build Rules File" in the Essbase XTD
Administration Services Online Help.

Understanding the
Rules for Naming
Dimensions and
Members
When naming dimensions, members, and aliases in the database
outline, follow these rules:

• Use no more than the maximum lengths that are specified in

Limits.
• Names are not case-sensitive unless case-sensitivity is
enabled. See "Setting Outline Properties" in the Essbase XTD
Administration Services Online Help.
• Do not use " (quotation marks) or tabs anywhere in a name.
• Do not use the following characters at the beginning of a
name:
@ at signs () parentheses
\ backslashes . periods
{ } braces + plus signs
, commas ' single quotation marks
- dashes, hyphens, or minus _ underscores
= equal signs | vertical bars
< less than signs
•

• Do not place spaces at the beginning or end of a name.

Analytic Services ignores spaces at the beginning or end of a
name.
• Do not use the following words as dimension or member
names:
o Calculation script commands, operators, and keywords.
For a list of commands, see the Technical Reference.
o Report writer commands. For a list of commands, see
the Technical Reference.
o Function names and function arguments. For a list of
functions, see the Technical Reference.
o Names of other dimensions, members (unless the
member is shared), generation names, level names,
and aliases in the database.
o Any of the following words:
ALL GENRANGE OR
AND GROUP PAREN
ASSIGN GT PARENPARM
CALC ID PERCENT
CALCMBR IDERROR PLUS
COPYFORWARD INTEGER RELOP
CROSSDIM LE SET
CURMBRNAME LEVELRANGE SKIPBOTH
DIM LOOPBLOCK SKIPMISSING
DIMNAME LOOPPARMS SKIPNONE
DIV LT SKIPZERO
DYNAMIC MBR TO
EMPTYPARM MBRNAME TOLOCALRATE
EQ MBRONLY TRAILMISSING
EQOP MINUS TRAILSUM
EXCEPT MISSING UMINUS
EXP MUL UPPER
EXPERROR MULOP VARORXMBR
 FLOAT NE XMBRONLY
FUNCTION NON $$$UNIVERSE$$$
GE NONINPUT #MISSING
GEN NOT #MI
o

o Note: If you enable Dynamic Time Series members,

do not use the associated generation names-History,
Year, Season, Period, Quarter, Month, Week, or Day.
See Applying Predefined Generation Names to
Dynamic Time Series Members.

• In calculation scripts, report scripts, filter definitions, partition

definitions, or formulas, you must enclose member names in
quotation marks (" ") in the following situations:
o The name starts with one or more numerals (for
example, 100).
o The name contains spaces or any of the following
characters:
& ampersand ! exclamation point
* asterisk > greater than sign
@ at sign < less than sign
\ backslash () parentheses
{ } braces % percent sign
[ ] brackets . period
: colon + plus sign
, comma ; semicolon
- dash, hyphen, or minus / slash
= equal sign ~ tilde
o

• In calculation scripts and formulas, you must enclose the

following member names in quotation marks (" "):
BEGIN
DOUBLE
END
MACRO
MEMBER
RANGE
STRING
THEN

Tips to make names unique:

 • Concatenate the member and alias names; for example, 100-
10_Cola and 100-10_Smith.
• Add prefixes or suffixes to member names. For example, if
the parent is the state and several states have a city called
Jackson, appending the state abbreviation creates the unique
names Jackson_CA, Jackson_IL, and Jackson_MI.

Setting Data Storage

Properties
When you create new dimensions and save an outline, Analytic
Services automatically sets the new dimensions in the outline as
sparse. You can change the dimension storage type according to the
optimal configuration for the database.

For information about choosing dense or sparse storage, see Selection

of Sparse and Dense Dimensions. You must set a standard dimension
with which you plan to associate an attribute dimension as sparse.

To set data storage properties using Outline Editor, see "Setting

Dimensions as Dense or Sparse" in the Essbase XTD Administration
Services Online Help.

Positioning Dimensions
and Members
Dimensions are the highest level of organization in an outline.
Dimensions contain members. You can nest members inside of other
members in a hierarchy. For more information on dimensions and
members, see Dimensions and Members.

The following sections describe how to position dimensions and

members in the outline:

• Moving Dimensions and Members

• Sorting Dimensions and Members
Note: The relative locations of dimensions in an outline can affect
calculation and retrieval performance times. See Designing an
Outline to Optimize Performance.

Moving Dimensions and Members

After you create dimensions and members, you can rearrange them
within the outline. Before moving members and dimensions in an
outline consider the following information:

• The positions of dimensions and members in an outline can

affect performance. See Optimizing Outline Performance.
• Moving dimensions and members can affect the performance
of calculations and retrievals. For information about
performance for calculation and retrieval, see Designing an
Outline to Optimize Performance.
• Moving members could move a shared member before the
actual member in the outline, something that Hyperion does
not recommend.
• If you add, delete, or move non-attribute dimensions or
members, Analytic Services restructures the database, and
you must recalculate the data.
• You must position attribute dimensions at the end of the
outline. If you do not position attribute dimensions at the end
of the outline, during outline verification, Analytic Services
prompts you to move them there.
To position dimensions and members using Outline Editor, see
"Manipulating Dimensions and Members in an Outline" in the Essbase
XTD Administration Services Online Help.

Sorting Dimensions and Members

You can have Analytic Services arrange dimensions within an outline or
members within a dimension in alphabetical order (A to Z) or reverse
alphabetical order (Z to A). For a list of consequences of sorting
dimensions and members, see Moving Dimensions and Members.

When you sort level 0 members of numeric attribute dimensions in

outlines, the members are sorted by their values. For example,
Figure?48 shows text and numeric versions of the Sizes attribute
dimension after sorting the members in ascending order. The members
of the numeric attribute dimension are sequenced by the numeric
values of the members; the member 8 is before the other members. In
the text attribute dimension, because the characters are sorted left to
right, the member 8 is after the member 24.

Figure 48: Sorting Numeric Versus Text Attribute Dimension in

Ascending Order

You cannot sort Boolean attribute dimensions. For more information

about attribute dimension types, see Understanding Attribute Types.

To sort members using Outline Editor, see "Sorting Members" in the

Essbase XTD Administration Services Online Help.

Verifying Outlines
You can verify an outline automatically when you save it or you can
verify the outline manually at any time. When verifying an outline,
Analytic Services checks the following items:

• All member and alias names are valid. Members and aliases
cannot have the same name as other members, aliases,
generations, or levels. See Understanding the Rules for
Naming Dimensions and Members for more information.
• Only one dimension is tagged as accounts, time, currency
type, or country.
• Shared members are valid as described in Understanding the
Rules for Shared Members.
• Level 0 members are not tagged as label only.
• Label-only members have not been assigned formulas.
• 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.
• Level 0 Dynamic Calc members of standard dimensions have
a formula.
• Formulas for members are valid.
• In a Hybrid Analysis outline, only the level 0 members of a
dimension can be Hybrid Analysis-enabled.

During outline verify, Analytic Services also performs the following

conversions to appropriate numeric attribute dimension member
names and displays them in the outline:

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

For more information about numeric attribute dimensions, see

Understanding Attribute Types.

To verify an outline, see "Verifying Outlines" in the Essbase XTD

Administration Services Online Help.

Saving Outlines
You can save outlines to the Analytic Server or to a client computer or
network. By default, Analytic Services saves outlines to the database
directory on Analytic Server. If you are saving changes to an existing
outline, Analytic Services may restructure the outline. For example, if
you change a member name from Market to Region, Analytic Services
moves data stored in reference to Market to Region. Each time that
you save an outline, Analytic Services verifies the outline to make sure
that it is correct.

To save an outline, see "Saving Outlines" in the Essbase XTD

Administration Services Online Help.

For more information about adding or deleting members before saving

an outline, see the following sections:

• Saving an Outline with Added Standard Dimensions

• Saving an Outline with One or More Deleted Standard
Dimensions
• Creating Sub-Databases Using Deleted Members

Saving an Outline with Added Standard Dimensions

If you add one or more new standard (non-attribute) dimensions, then
any data that existed previously in the database must be mapped to a
member of each new dimension. For example, adding a dimension
called Channel to the Sample Basic outline implies that all previous
data in Sample Basic is associated with a particular channel or the sum
of all channels.

If you add one or more new standard dimensions and then attempt to
save the outline, Analytic Services prompts you to associate data of
previously existing dimensions to one member of each new dimension.

Saving an Outline with One or More Deleted Standard

Dimensions
If you delete one or more standard (non-attribute) dimensions, the
data associated with only one member of each deleted dimension can
be retained. For example, removing a dimension called Market from
the outline implies that all of the data that remains in the database
after the restructure operation is associated with a single, specified
member of the Market dimension.

If you delete one or more dimensions and then attempt to save the
outline, Analytic Services prompts you to select a member of the
deleted dimension whose data values will be retained and associated
with the members of the other dimensions.

If you delete an attribute dimension, Analytic Services deletes the

associations to its base dimension. See Working with Attributes.

Creating Sub-Databases Using Deleted Members

To create a sub-database:
1. Delete a dimension from an existing outline.
2. Save the database using a different name, and specify the
member to keep. Only one member can be kept when a
dimension is deleted. For more information, see Saving an
Outline with One or More Deleted Standard Dimensions.

Setting Dimension and

Member Properties
After you create and organize the outline, as described in Creating and
Changing Database Outlines, you are ready to specify how the
dimensions and members in the outline behave. This chapter describes
dimension and member properties and how to set properties.

• Setting Dimension Types

• Setting Member Consolidation
• Calculating Members with Different Operators
• Determining How Members Store Data Values
• Setting Aliases
• Setting Two-Pass Calculations
• Creating Formulas
• Naming Generations and Levels
• Creating UDAs
• Adding Comments
Setting Dimension
Types
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. Analytic Services calculates the two
primary dimension types, time and accounts, before other dimensions
in the database. By default, all dimensions are tagged as none.

The following sections describe the different dimension types:

• Creating a Time Dimension

• Creating an Accounts Dimension
• Creating a Country Dimension
• Creating Currency Partitions
• Creating Attribute Dimensions
To set a dimension type, see "Setting the Dimension Type" in the
Essbase XTD Administration Services Online Help.

Creating a Time Dimension

Tag a dimension as time if it contains members that describe how
often you collect and update data. In the Sample Basic database, for
example, the Year dimension is tagged as time, as are its
descendants-all Qtr members and the months (such as Jan). The time
dimension also enables several accounts dimension functions, such as
first and last time balances.

Follow these rules when tagging a dimension as time:

• You can tag only one dimension in an outline as time.

• All members in the time dimension inherit the time property.
• 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.
To tag a dimension as time, see "Tagging a Time Dimension" in the
Essbase XTD Administration Services Online Help.
Creating an Accounts Dimension
Tag a dimension as accounts if it contains items that you want to
measure, such as profit or inventory.

Follow these rules when tagging a dimension as accounts:

• You can tag only one dimension in an outline as accounts.

• You can create an outline that does not have an accounts
dimension.
• All members in the accounts dimension inherit the accounts
property.
• You can specify that members of the accounts dimension are
calculated on the second pass through an outline. For more
information, see Setting Two-Pass Calculations.
To tag a dimension as accounts, see "Tagging an Accounts
Dimension" in the Essbase XTD Administration Services Online Help.

The following sections describe built-in functionality for accounts

dimensions:

• Setting Time Balance Properties

• Setting Skip Properties
• Setting Variance Reporting Properties
• Setting Analytic Services Currency Conversion Properties

Setting Time Balance Properties

If a member of the accounts dimension uses the time balance
property, it affects how Analytic Services calculates the parent of that
member in the time dimension. By default, a parent in the time
dimension is calculated based on the consolidation and formulas of its
children. For example, in the Sample Basic database, the Qtr1 member
is the sum of its children (Jan, Feb, and Mar). However, setting a time
balance property causes parents, for example Qtr1, to roll up
differently.

To set time balance properties, see "Setting Time Balance Properties"

in the Essbase XTD Administration Services Online Help.

Example of Time Balance as None

None is the default value. When you set the time balance property as
none, Analytic Services rolls up parents in the time dimension in the
usual way-the value of the parent is based on the formulas and
consolidation properties of its children.

Example of Time Balance as First

Set the time balance as first when you want the parent value to
represent the value of the first member in the branch (often at the
beginning of a time period).

For example, assume that you have a member named

OpeningInventory that represents the inventory at the beginning of
the time period. If the time period was Qtr1, then OpeningInventory
represents the inventory at the beginning of Jan; that is, the
OpeningInventory for Qtr1 is the same as the OpeningInventory for
Jan. For example, if you had 50 cases of Cola at the beginning of Jan,
you also had 50 cases of Cola at the beginning of Qtr1.

To accomplish this task, tag OpeningInventory as first. Figure?49

shows this sample consolidation.

Figure 49: Consolidation of OpeningInventory Tagged as First

OpeningInventory (TB First), Cola, East, Actual, Jan(+), 50
OpeningInventory (TB First), Cola, East, Actual, Feb(+), 60
OpeningInventory (TB First), Cola, East, Actual, Mar(+), 70
OpeningInventory (TB First), Cola, East, Actual, Qtr1(+), 50 
 

Example of Time Balance as Last

Set the time balance as last when you want the parent value to
represent the value of the last member in the branch (often at the end
of a time period).

For example, assume that you have a member named EndingInventory

that represents the inventory at the end of the time period. If the time
period was Qtr1, then EndingInventory represents the inventory at the
end of Mar; that is, the EndingInventory for Qtr1 is the same as the
EndingInventory for Mar. For example, if you had 70 cases of Cola at
the end of Mar, you also had 70 cases of Cola at the end of Qtr1.
To accomplish this task, tag EndingInventory as last. Figure?50 shows
this sample consolidation.

Figure 50: Consolidation of EndingInventory Tagged as Last

EndingInventory (TB Last), Cola, East, Actual, Jan(+), 50
EndingInventory (TB Last), Cola, East, Actual, Feb(+), 60
EndingInventory (TB Last), Cola, East, Actual, Mar(+), 70
EndingInventory (TB Last), Cola, East, Actual, Qtr1(+), 70  
 

Example of Time Balance as Average

Set the time balance as average when you want the parent value to
represent the average value of its children.

For example, assume that you have a member named

AverageInventory that represents the average of the inventory for the
time period. If the time period was Qtr1, then AverageInventory
represents the average of the inventory during Jan, Feb, and Mar.

To accomplish this task, tag AverageInventory as average. Figure?51

shows this sample consolidation.

Figure 51: Consolidation of AverageInventory Tagged as Average

AverageInventory (TB Average), Cola, East, Actual, Jan(+), 
60
AverageInventory (TB Average), Cola, East, Actual, Feb(+), 
62
AverageInventory (TB Average), Cola, East, Actual, Mar(+), 
67
AverageInventory (TB Average), Cola, East, Actual, Qtr1(+), 
63  
 
Setting Skip Properties
If you set the time balance as first, last, or average, you must set the
skip property to?tell Analytic Services what to do when it encounters
missing values or values of 0.

The following table describes how each setting determines what

Analytic Services does when it encounters a missing or zero value.

Setting Action Analytic Services Takes

None Does not skip data when calculating the parent

value.

Missing Skips #MISSING data when calculating the parent

value.

Zeros Skips data that equals zero when calculating the

parent value.

Missing and Skips both #MISSING data and data that equals
Zeros zero when calculating the parent value.

If you mark a member as last with a skip property of missing or

missing and zeros, then the parent of that time period matches the
last non-missing child. In Figure?52, for example, EndingInventory is
based on the value for Feb, because Mar does not have a value.

Figure 52: Example of Skip Property

Cola, East, Actual, Jan, EndingInventory (Last), 60
Cola, East, Actual, Feb, EndingInventory (Last), 70
Cola, East, Actual, Mar, EndingInventory (Last), #MI
Cola, East, Actual, Qtr1, EndingInventory (Last), 70  
 
Setting Variance Reporting Properties
Variance reporting properties determine how Analytic Services
calculates the difference between actual and budget data in a member
with the @VAR or @VARPER function in its member formula. Any
member that represents an expense to the company requires an
expense property.

When you are budgeting expenses for a time period, the actual
expenses should be lower than the budget. When actual expenses are
greater than budget, the variance is negative. The @VAR function
calculates Budget - Actual. For example, if budgeted expenses were
$100, and you actually spent $110, the variance is -10.

When you are budgeting non-expense items, such as sales, the actual
sales should be higher 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
actually made $110 in sales, the variance is 10.

By default, members are non-expense.

To set variance reporting properties, see "Setting Variance Reporting

Properties" in the Essbase XTD Administration Services Online Help.

Setting Analytic Services Currency Conversion

Properties
Currency conversion properties define categories of currency exchange
rates. These properties are used only in currency databases on
members of accounts dimensions. For a comprehensive discussion of
currency conversion, see Designing and Building Currency Conversion
Applications.

To set currency conversion properties, see "Assigning Currency

Categories to Accounts Members" in the Essbase XTD Administration
Services Online Help.

Creating a Country Dimension

Use country dimensions to track business activities in multiple
countries. If you track business activity in the United States and
Canada, for example, the country dimension should contain states,
provinces, and countries. If a dimension is tagged as country, you can
set the currency name property. The currency name property defines
what type of currency this market region uses.

In a country dimension, you can specify the type of currency used in

each member. For example, in the Interntl application and database
shipped with Analytic Services, Canada has three markets-Vancouver,
Toronto, and Montreal. They use the same currency, Canadian dollars.

This dimension type is used for currency conversion applications. For a

comprehensive discussion of currency conversion, see Designing and
Building Currency Conversion Applications.

To tag a dimension as country, see "Tagging a Country Dimension" in

the Essbase XTD Administration Services Online Help.

Creating Currency Partitions

Use currency partition members to separate local currency members
from a base currency defined in the application. If the base currency
for analysis is US dollars, for example, the local currency members
would contain values based on the currency type of the region, such as
Canadian dollars.

This dimension type is used for currency conversion applications. For

information about how to create and use currency partitions, see
Designing and Building Currency Conversion Applications.

For complete information about how to design and implement currency

applications, see Designing and Building Currency Conversion
Applications.

To tag a dimension as currency partition, see "Creating a Currency

Partition" in the Essbase XTD Administration Services Online Help.

Creating Attribute Dimensions

Use attribute dimensions to report and aggregate data based on
characteristics of?standard dimensions. In the Sample Basic database,
for example, the Product dimension is associated with the Ounces
attribute dimension. Members of the Ounces attribute dimension
categorize products based on their size in ounces.
Be sure to review the rules for using attribute dimensions in Working
with Attributes.

To tag a dimension as attribute, see "Tagging an Attribute

Dimension" in the Essbase XTD Administration Services Online Help.

Setting Member
Consolidation
Member consolidation properties determine how children roll up into
their parents. By default, new members are given the addition (+)
operator, meaning that members are added. For example, Jan, Feb,
and Mar figures are added and the result stored in their parent, Qtr1.

Note: Analytic Services does not use consolidation properties with

members of attribute dimensions. See Calculating Attribute Data for
an explanation of how the attribute dimensions works.

Table?10 describes each operator.

Table 10: 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 then 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 the consolidation to its

parent.

To set member consolidation properties, see "Setting Member

Consolidation Properties" in the Essbase XTD Administration Services
Online Help.

Calculating Members
with Different
Operators
When siblings have different operators, Analytic Services calculates the
data in top-down order. The following section describes how Analytic
Services calculates the members in Figure?53.

Figure 53: Sample Roll Up

Parent1
   Member1 (+)   10
   Member2 (+)   20
   Member3 (­)   25
   Member4 (*)   40
   Member5 (%)   50
   Member6 (/)   60
   Member7 (~)   70 
 

Analytic Services calculates Member1 through Member4 in Figure?53

as follows:
Figure 54: Sample Roll Up for Members 1 through 4

(((Member1 + Member2) + (­1)Member3) * Member4) = X
(((10 + 20) + (­25)) * 40) = 200 
 

If the result of Figure?54 is X, then Member5 consolidates as follows:

Figure 55: Sample Roll Up for Member 5

(X/Member5) * 100 = Y
(200/50) * 100 = 400 
 

If the result of Figure?55 is Y, then Member6 consolidates as follows:

Figure 56: Sample Roll Up for Member 6

Y/Member6 = Z
400/60 = 66.67 
 

Because it is set to No Consolidation(~), Analytic Services ignores

Member7 in the consolidation.

Determining How
Members Store Data
Values
You can determine how and when Analytic Services stores the data
values for a member. For example, you can tell Analytic Services to
only calculate the value for a member when a user requests it and
then discard the data value. Table?11 describes each storage property.

Table 11: Choosing Storage Properties ?

Storage For More
When to Use
Property Information

Store Store the data value with the Understanding

member. Stored Members

Dynamic Not calculate the data value Understanding

Calc and until a user requests it, and Dynamic
Store then store the data value. Calculation
Members

Dynamic Not calculate the data value Understanding

Calc until a user requests it, and Dynamic
then discard the data value. Calculation
Members

Never share Not allow members to be Understanding

shared implicitly. Implied Sharing
Members tagged as Never
share can only be explicitly
shared. To explicitly share a
member, create the shared
member with the same name
and tag it as shared.

Label only Create members for navigation Understanding

only, that is, members that Label Only
contain no data values. Members

Shared Share values between Understanding

member members. For example, in the Shared Members
Sample Basic database, the
100-20 member is stored
under the 100 parent and
shared under Diet parent.

To set member storage properties, see "Setting Member Storage

Properties" in the Essbase XTD Administration Services Online Help.
Understanding Stored Members
Stored members contain calculated values that are stored with the
member in the database after calculation. By default, members are set
as stored.

To define a member as stored, see "Setting Member Storage

Properties" in the Essbase XTD Administration Services Online Help.

Understanding Dynamic Calculation Members

When a member is Dynamic Calc, Analytic Services does not calculate
the value for that member until a user requests it. After the user views
it, Analytic Services does not store the value for that member. If you
tag a member as Dynamic Calc and Store, Analytic Services performs
the same operation as for a Dynamic Calc member, except that
Analytic Services stores the data value for that member after the user
views it.

For a comprehensive discussion of Dynamic Calc and Dynamic Calc and

Store members, see Dynamically Calculating Data Values.

Analytic Services automatically tags members of attribute dimensions

as Dynamic Calc. You cannot change this setting.

To tag a member as Dynamic Calc, see "Setting Member Storage

Properties" in the Essbase XTD Administration Services Online Help.

Understanding Label Only Members

Label only members have no data associated with them. Use them to
group members or to ease navigation and reporting from the
Spreadsheet Add-in. Typically, you should give label only members the
"no consolidation" property. For more information about member
consolidation, see Setting Member Consolidation.

You cannot associate attributes with label only members. If you tag as
label only a base dimension member that has attributes associated
with it, Analytic Services removes the attribute associations and
displays a warning message.

To tag a member as label only, see "Setting Member Storage

Properties" in the Essbase XTD Administration Services Online Help.
Understanding Shared Members
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 only stored once.
To define a member as shared, there must be an actual non-shared
member of the same name. 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 are typically used to calculate the same member

across multiple parents. For example, you might want to calculate a
Diet Cola member in both the 100?and Diet parents.

Using shared members lets you use members repeatedly throughout a

dimension. Analytic Services stores the data value only once, but it
displays in multiple locations. Storing the data value only once offers
considerable space saving as well as processing efficiency.

To tag a member as shared, see "Setting Member Storage

Properties" in the Essbase XTD Administration Services Online Help.

Use these sections to learn more about shared members:

• Understanding the Rules for Shared Members

• Understanding Shared Member Retrieval During Drill-Down
• Understanding Implied Sharing

Understanding the Rules for Shared Members

Follow these rules when creating shared members:

• The shared members must be in the same dimension. For

example, both 100-20 members in the Sample Basic database
are in the Product dimension.
• Shared members cannot have children.
• You can have an unlimited number of shared members with
the same name.
• You cannot assign UDAs or formulas to shared members.
• You cannot associate attributes with shared members.
• If you assign accounts properties to shared members, the
values for those accounts properties are taken from the base
member, even if you change the accounts properties on the
shared member.
 • You can assign aliases to shared members.
• You should not create an outline where shared members are
located before actual members in a dimension.
• Avoid creating complex relationships between real and shared
members that will be part of an attribute calculation, or your
calculation may return unexpected results. For details, see
Understanding Attribute Calculation and Shared Members.

Understanding Shared Member Retrieval During Drill-

Down
Analytic Services retrieves shared members during drill-down,
depending on their location in the spreadsheet. Analytic Services
follows three rules during this type of retrieval:

• Analytic Services retrieves stored members (not their shared

member counterparts) by default.
• Analytic Services retrieves from the bottom of a spreadsheet
first.
• If the parent of a shared member is a sibling of the stored
member counterpart of one of the shared members, Analytic
Services retrieves the stored member.

Example of Shared Members from a Single Dimension

If you created a test dimension with all shared members based on the
members of the dimension East from the Sample Basic outline, the
outline would be similar to the following:
If you retrieved just the children of East, all results would be from
stored members because Analytic Services retrieves stored members
by default.

If, however, you retrieved data with the children of test above it in the
spreadsheet, Analytic Services would retrieve the shared members:

New York
Massachusetts
Florida
Connecticut
New Hampshire
test

If you moved test above its last two children, Analytic Services would
retrieve the first three children as shared members, but the last two as
stored members. Similarly, if you inserted 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), then
Analytic Services would retrieve shared members only between the
non-sibling and the parent (in this case, between California and test).

Example of Retrieval with Crossed Generation Shared Members

You could modify the Sample Basic outline to create a shared member
whose stored member counterpart was a sibling to its own parent:
If you created a spreadsheet with shared members in this order,
Analytic Services would retrieve all the shared members, except it
would retrieve the stored member West, not the shared member west:

west
New York
Massachusetts
Connecticut
New Hampshire
test

Analytic Services retrieves the members in this order because test is a

parent of west and a sibling of west's stored member counterpart,
West.

Understanding Implied Sharing

The shared member property defines a shared data relationship
explicitly. Some members are shared even if you do not explicitly set
them as shared. These members are said to be implied shared
members.

Analytic Services assumes (or implies) a shared member relationship

in the following situations:

• A parent has only one child. In this situation, the parent

and the child contain the same data. Analytic Services 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 Figure?57, for example, the parent 500 has
only one child, 500-10, so the parent shares the value of that
child.

Figure 57: Implied Sharing of a Parent with One Child

500 (+)
????500­10 (+)
• A parent has only one child that consolidates to the
parent. If the parent has four?children, but three of them are
marked as no consolidation, then the parent and child that
consolidates contain the same data. Analytic Services 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 Figure?58, for 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.

Figure 58: Implied Sharing of a Parent with Multiple Children

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, and is not shared. See
Understanding Shared Members for an explanation of how shared
members work.

Setting Aliases
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. Alias are stored in alias tables.
Aliases can improve the readability of an outline or a report.

You can set more than one alias for a member using alias tables. For
example, you could use different aliases for different kinds of reports-
users may be familiar with 100-10 as Cola, but advertisers and
executives may be familiar with it as The Best Cola. This list shows
some products in the Sample Basic database that have two descriptive
alias names:

Product  Default              Long Names
100­10   Cola                 The Best Cola
100­20   Diet Cola            Diet Cola with Honey
100­30   Caffeine Free Cola   All the Cola, 
                                none of the Caffeine 
 
For a comprehensive discussion of alias tables, see Alias Tables.

The following sections describe aliases:

• Alias Tables
• Creating Aliases
• Creating and Managing Alias Tables

Analytic Services does not support aliases for Hybrid Analysis-enabled

members.

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 aliase names to member
names. When you create a database outline, Analytic Services creates
an empty alias table named Default. If you don't create any other alias
tables, the aliases that you create are stored in the Default alias table.

If you want to create more than one set of aliases for outline
members, create a new alias table for each set. 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 for further information.

For Unicode-mode applications, setting up a separate alias table for

each user language enables different users to view member names in
their own language. For additional information about the relevance of
alias tables and Unicode, see About the Analytic Services
Implementation of Unicode.

Creating Aliases
You can provide an alias for any member. Alias names must follow the
same rules as member names. See Understanding the Rules for
Naming Dimensions and Members.

You can use any of the following methods to create aliases in an

existing alias table:
 To manually assign an alias to a member while editing an outline,
see "Creating Aliases for Dimensions and Members" in the Essbase
XTD 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 Essbase XTD
Administration Services Online Help.
To import alias values from an alias table source file created in a pre-
defined format, see Importing and Exporting Alias Tables.

Creating and Managing Alias Tables

Named alias tables enable you to display different aliases in different
situations. For general information about alias tables, see Alias Tables.
While working with alias tables, you can perform the following actions:

• Creating a New Alias Table

• Setting an Alias Table as Active
• Copying an Alias Table
• Renaming an Alias Table
• Clearing and Deleting Alias Tables
• Importing and Exporting Alias Tables

Creating a New Alias Table

An alias table contains a list of aliases to use for members in the
outline.The folowing restrictions apply to alias tables:

• You can create up to 10 alias tables for an outline.

• The naming conventions for alias table names are the same
as those for dimensions. See?Understanding the Rules for
Naming Dimensions and Members.
• Name-length restrictions depend on the Unicode-related
mode of the application; see Limits.
• Once an alias table is created, you cannot change its name.
To create a new alias table, see "Creating Alias Tables" in Essbase
XTD Administration Services Online Help.

When you first create an alias table, it is empty. For information about
adding aliases to an alias table and assigning them to members, see
Creating Aliases.
Setting an Alias Table as Active
The active alias table contains the aliases that Analytic Services
currently displays in the outline.

To view a list of alias tables in the outline and to set the current alias
table, use any of the following methods:

Tool Topic Location

Administration Setting the Active Essbase XTD

Services Alias Table for Outline Administration Services
Editor Online Help

MaxL query database Technical Reference

alter database

ESSCMD LISTALIASES Technical Reference

SETALIAS

Copying an Alias Table

To copy alias tables, use any of the following methods:

Tool Topic Location

Administration Copying Alias Essbase XTD Administration

Services Tables Services Online Help

MaxL alter object Technical Reference

ESSCMD COPYOBJECT Technical Reference

Renaming an Alias Table

To rename an alias table, use any of the following methods:
Tool Topic Location

Administration Renaming Alias Essbase XTD

Services Tables Administration Services
Online Help

MaxL alter object Technical Reference

ESSCMD RENAMEOBJECT Technical Reference

Clearing and Deleting Alias Tables

You can delete an alias table from the outline or you can clear all the
aliases from an alias table without deleting the alias table itself. To
clear or delete alias tables, see "Deleting and Clearing Alias Tables" in
the Essbase XTD Administration Services Online Help.

Importing and Exporting Alias Tables

You can import a correctly formatted text file into Analytic Services as
an alias table. Alias table import files have the extension .ALT. As
shown in Figure?59, alias table import files should have the following
structure:

• 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 that are 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.

Note: Essbase Administration Services requires alias table import

files to be UTF-8 encoded for non-Unicode-mode applications and
Unicode-mode applications. For information about how to convert
non-Unicode-encoded files to UTF-8, see Analytic Services Unicode
File Utility.

Figure 59: Sample Alias Table Import File

$ALT_NAME  'Quarters'
Qtr1   Quarter1
Jan   January
Feb   February
Mar   March
$END 
 

You can also export an alias table from the Analytic Services outline to
a text file. The alias table contains all the member names with aliases
and the corresponding aliases.

To import or export alias tables, use any of the following methods:

Tool Topic Location

Administration Importing Alias Essbase XTD

Services Tables Administration Services
Online Help
Exporting Alias
Tables

MaxL alter database Technical Reference

ESSCMD LOADALIAS Technical Reference

UNLOADALIAS

Setting Two-Pass
Calculations
By default, Analytic Services calculates outlines from the bottom up-
first calculating the values for the children and then the values for the
parent. Sometimes, however, the values of the children may be based
on the values of the parent or the values of other members in the
outline. To obtain the correct values for these members, Analytic
Services must first calculate the outline and then re-calculate the
members that are dependent on the calculated values of other
members. The members that are calculated on the second pass
through the outline are called two-pass calculations.

For more information on bottom-up calculations, see Using Bottom-Up

Calculation.

For example, to calculate the ratio between Sales and Margin, Analytic
Services needs first to calculate Margin, which is a parent member
based on its children, including Sales. To ensure that the ratio is
calculated based on a freshly calculated Margin figure, tag the Margin
% ratio member as a two-pass calculation. Analytic Services calculates
the database once and then calculates the ratio member again. This
calculation produces the correct result.

Even though two-pass calculation is a property that you can give to

any non-attribute member, it works only on the following members:

• Members of accounts dimensions

• Dynamic Calc members
• Dynamic Calc and Store members.

If two-pass calculation is assigned to other members, Analytic Services

ignores it.

To tag a member as two-pass, see "Setting Two-Pass Calculation

Properties" in the Essbase XTD Administration Services Online Help.

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 Analytic Services calculates the outline data.
For more a comprehensive discussion about formulas, see Developing
Formulas.
 To add formulas to a dimension or member, see "Creating and
Editing Formulas in Outlines" in the Essbase XTD Administration
Services Online Help.

Naming Generations
and Levels
You can create names for generations and levels in an outline, such as
a word or phrase that describes the generation or level. For example,
you might create a generation name called Cities for all cities in the
outline. For information about generations and levels, see Dimension
and Member Relationships.

Use generation and level names in calculation scripts or report scripts

wherever you need to specify either a list of member names or
generation or level numbers. For example, you could limit a calculation
in a calculation script to all members in a specific generation. See
Developing Calculation Scripts for information about developing
calculation scripts.

You can define only one name for each generation or level. When you
name generations and levels, follow the same naming rules as for
members. See Understanding the Rules for Naming Dimensions and
Members.

To name generations and levels using Outline Editor, see "Naming

Generations and Levels" in the Essbase XTD Administration Services
Online Help.

Creating UDAs
You can create your own user-defined attributes for members. A user-
defined attribute (UDA) is a word or phrase about a member. For
example, you might create a UDA called Debit. Use UDAs in the
following places:

• Calculation scripts. After you define a UDA, you can query a

member for its UDA in a calculation script. For example, you
 could 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 Developing Calculation
Scripts.
• 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.

If you want 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.

Follow these rules when creating UDAs:

• You can define multiple UDAs per member.

• You cannot set the same UDA twice for one member.
• You can set the same UDA for different members.
• A UDA name can be the same as a member, alias, level, or
generation name. When you name UDAs, follow the same
naming rules as for members. See Understanding the Rules
for Naming Dimensions and Members.
• You cannot create a UDA on shared members.
• You cannot create a UDA on members of attribute
dimensions.
• A UDA applies to the specified member only. Descendants and
ancestors of the member do not automatically receive the
same UDA.
To add UDAs to a member, see "Working with UDAs" in the Essbase
XTD Administration Services Online Help.

Adding Comments
You can add comments to dimensions and members. A comment can
be up to 255 characters long. Outline Editor displays comments to the
right of the dimension or member in the following format:

/* comment */ 
 
 To add comments to a dimension or member, see "Setting
Comments on Dimensions and Members" in the Essbase XTD
Administration Services Online Help.

Working with Attributes

Attributes describe characteristics of data such as the size and color of
products. Through attributes you can group and analyze members of
dimensions based on their characteristics.

This chapter describes how to create and manage attributes in an

Analytic Server outline. This chapter contains the following sections:

• Process for Creating Attributes

• Understanding Attributes
• Understanding Attribute Dimensions
• Designing Attribute Dimensions
• Building Attribute Dimensions
• Setting Member Names in Attribute Dimensions
• Calculating Attribute Data

You can find other information about attributes in relevant sections of

this book.

Information Needed More Information

Defining attributes Building Attribute Dimensions and

through dimension build Associating Attributes

Using attributes in • Designing Partitioned

partitions Applications
• Creating and Maintaining
Partitions

Using attributes in report Developing Report Scripts

writer
Process for Creating
Attributes
When working with attributes in Outline Editor perform the following
tasks:

1. Create a new dimension. See Adding Dimensions and

Members to an Outline. In the outline, position the attribute
dimensions after all standard dimensions.
2. Tag the dimension as an attribute dimension and set attribute
dimension type as text, numeric, Boolean, or date. See
Creating Attribute Dimensions.
3. Add members to the attribute dimension. See Adding
Dimensions and Members to an Outline.
4. Associate a base dimension with the attribute dimension. See
Understanding the Rules for Attribute Dimension Association.
5. Associate members of the base dimension with members of
the attribute dimension. See Understanding the Rules for
Attribute Member Association.
6. If necessary, set up the attribute calculations. See Calculating
Attribute Data.

Understanding
Attributes
You can use the Analytic Services 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 into the analysis market attributes such as the
population size of each market region.

Such an analysis could tell you that decaffeinated drinks sold in cans in
small (less than 6,000,000-population) markets 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.

Here are a few ways analysis by attribute provides depth and

perspective, supporting better-informed decisions.

• 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,000-1,000,000, and >1,000,000.
• Through the Attribute Calculations dimension automatically
created by Analytic Services, 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, Analytic Services 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. For
example, the crosstab in Figure?60 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.

Figure 60: Crosstab Example

            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 
 

Understanding
Attribute Dimensions
In the Sample Basic database, products have attributes that are
characteristics of the products. For example, products have an
attribute that describes their packaging. In the outline, you see these
characteristics as two dimensions, the Products dimension, and the
Pkg Type attribute dimension that is associated with it. An attribute
dimension has the word Attribute next to its name in the outline.

Figure?61 shows part of the Sample Basic outline featuring the Product
dimension and three attribute dimensions, Caffeinated, Ounces, and
Pkg Type.

Figure 61: Outline Showing Base and Attribute Dimensions

In the outline, to the right of the Product dimension, the terms
Caffeinated, Ounces, and Pkg Type show that these attribute
dimensions are associated with the Product dimension.

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 the outline in Figure?61, 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

Analytic Services calculates attribute information at retrieval time.
Attribute data is not stored in the database.

Understanding Members of Attribute Dimensions

Members of an attribute dimension are potential attributes of the
members of the associated base dimension. After you associate a base
dimension with an attribute dimension, you associate members of the
base dimension with members of the associated attribute dimension.
The Market dimension member Connecticut is associated with the
6000000 member of the Population attribute dimension. That makes
6000000 an attribute of Connecticut.

In the outline, the information next to a base dimension member

shows the attributes of that member. In Figure?61, next to product
"100-10, Caffeinated:True, Ounces:12, Pkg Type:Can" shows that
product 100-10 has three attributes-product 100-10 has caffeine, it is
sold in 12-ounce containers, and the containers are cans.

Understanding the Rules for Base and Attribute Dimensions and

Members
There are several important rules regarding members of attribute
dimensions and their base dimensions.

• You can tag only sparse dimensions as attribute dimensions.

• Before you can save an outline to the server, each attribute
dimension must be associated with a standard, sparse
dimension as its base dimension.
• Attribute dimensions must be the last dimensions in the
outline.
• Attribute dimensions have a type setting-text, numeric,
Boolean, or date. Text is the default setting. Although
assigned at the dimension level, the type applies only to the
level 0 members of the dimension. For more information, see
Understanding Attribute Types.
• If you remove the attribute tag from a dimension, Analytic
Services removes prefixes or suffixes from its member
names. Prefixes and suffixes are not visible in the outline. For
more information, see Setting Prefix and Suffix Formats for
Member Names of Attribute Dimensions.
• A base dimension member can have many attributes, but only
one attribute from each particular attribute dimension.
For example, product 100-10 can have size and packaging
attributes, but only one size and only one type of packaging.
• Analytic Services does not support attributes for Hybrid
Analysis-enabled members.

You can use attribute values in calculations in the following

comparisons:

• > (greater than)

• >= (greater than or equal to)
• < (less than)
• <= (less than or equal to)
• = = (equal to)
• <> or != (not equal to)
• IN
Understanding the Rules for Attribute Dimension Association
When you associate an attribute dimension with a standard dimension,
the standard dimension is known as the base dimension for that
attribute dimension.

• An attribute dimension must be associated with a sparse

standard dimension.
• A standard dimension can be a base dimension for more than
one attribute dimension.
• An attribute dimension can be associated with only one base
dimension.
For example, you might have a Size attribute dimension with
members Small, Medium, and Large. If you associate the Size
attribute dimension with the Product dimension, you cannot also
associate the Size attribute dimension with the Market
dimension. If you also want to track size-related information for
the Market dimension, you must create another attribute
dimension with a different name, for example, MarketSize, and
associate the MarketSize attribute dimension with the Market
dimension.

Understanding the Rules for Attribute Member Association

When you associate a member of an attribute dimension with a
member of a base dimension, follow these rules:

• 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 location in the outline, the attribute associations are
lost.
• Analytic Services 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?62, 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 attribute
since the other members of the Market dimension that have
Population attributes are level 0 members.

Figure 62: 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.

Understanding Attribute Types

Attribute dimensions have a text, numeric, Boolean, or date type that
enables different functions for grouping, selecting, or calculating data.
Although assigned at the dimension level, the attribute type applies
only to level 0 members of the attribute dimension.

• The default attribute type is text. Text attributes enable the

basic attribute member selection and attribute comparisons in
calculations. When you perform such comparisons, Analytic
Services 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 groupings-states with 3,000,000 population or
less in one group, states with a population between 3,000,001
and 6 million in another group, and so on. See Setting Up
Member Names Representing Ranges of Values.
• 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 you have
more than one Boolean attribute dimension, you must specify
a prefix or suffix member name format to ensure unique
member names; for example, Caffeinated_True and
Caffeinated_False. For a discussion of how to change Boolean
names, see Setting Boolean Attribute Member Names.
• You can use date attributes to specify the date format-month-
day-year or day-month-year-and to sequence information
accordingly. For a discussion of how to change date formats,
see Changing the Member Names in Date Attribute
Dimensions. 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.
Analytic Services supports date attributes from January 1, 1970
through January?1, 2038.
Comparing Attribute and Standard Dimensions
In general, attribute dimensions and their members are similar to
standard dimensions and members. You can provide aliases and
member comments for attributes. Attribute dimensions can include
hierarchies and you can name generations and levels. You can perform
the same spreadsheet operations on attribute dimensions and
members as you can on standard dimensions and members; for
example, to analyze data from different perspectives, you can retrieve,
pivot, and drill down in the spreadsheet.

Table?12 describes major differences between attribute and standard

dimensions and their members.

Table 12: Differences Between Attribute and Standard

Dimensions ?
Standard
. Attribute Dimensions
Dimensions

Storage Must be sparse. Their base Can be dense or

dimensions must also be sparse
sparse.

Storage Dynamic Calc only, Can be Store Data,

property therefore not stored in the Dynamic Calc and
database. The outline does Store, Dynamic
not display this property. Calc, Never Share,
or Label Only

Position in Must be the last Must be ahead of

outline dimensions in the outline all attribute
dimensions in the
outline

Partitions Cannot be defined along Can be defined

attribute dimensions, but along standard
you can use attributes to dimensions.
define a partition on a
base dimension.

Formulas Cannot be associated Can be associated

(on?members)
Shared Not allowed Allowed
members

Two-pass Not available Available

calculation
member
property

Two-pass If member formula must Calculation is

calculation with be executed at run time performed on
run-time and is tagged two-pass, standard members
formula calculation skips the with run-time
member and issues formulas and
warning message. Run- tagged two-pass.
time dependent functions
include the following:
@CURRMBR, @PARENT,
@PARENTVAL,
@MDPARENTVAL,
@ANCEST, @ANCESTVAL,
and @MDANCESTVAL.

Two-pass, Order of calculation of Calculation result is

multiple members tagged two-pass not dependent on
dimensions: depends on order in outline order for
Calculation outline. The last members tagged
order dimension is calculated two-pass in more
last. than one
dimension.

Two-pass Calculation skipped, Available

calculation with warning message issued.
no member Thus member intersection
formula of two-pass tagged
members and upper level
members may return
different results from
calculation on standard
dimensions.

Dense dynamic Calculation skips dense Available

calc members in dimensions if they are on
non-existing any non-existing stored
stored blocks block. To identify non-
existing stored blocks,
export the database or run
query to find out whether
block has any data.

UDAs on Not allowed Allowed

members

Consolidations For all members, Consolidation

calculated through the operation indicated
Attribute Calculations by assigning the
dimension members: desired
Sum, Count, Min, Max, consolidation
and Avg. symbol to each
member

Member Available types include All members

selection text, numeric, Boolean, treated as text.
facilitated by and date.
Level 0 member
typing

Associations Must be associated with a N/A

base dimension

Spreadsheet List the base dimension List lower or sibling

drill-downs data associated with the levels of detail in
selected attribute. For the standard
example, drilling down on dimensions. For
the attribute Glass example, drilling
displays sales for each down on QTR1
product packaged in glass, displays a list of
where Product is the base products and their
dimension for the Pkg sales for that
Type attribute dimension. quarter.
Comparing Attributes and UDAs
Attributes and UDAs both enable analysis based on characteristics of
the data. Attributes provide much more capability than UDAs. Table?13
compares them. Checkmarks indicate the feature supports the
corresponding capability.

Table 13: Comparing Attributes and UDAs ?

Attributes
Capability UDAs Feature
Feature

Data Storage

You can associate with sparse

dimensions.

.
You can associate with dense
dimensions.

Data Retrieval

You can group and retrieve

consolidated totals by
Simple More difficult to
attribute or UDA value. For
implement,
example, associate the value
requiring
High Focus Item to various
additional
members of the Product
calculation
dimension and use that term
scripts or
to retrieve totals and details
commands
for just those members.

You can categorize attributes

in a hierarchy and retrieve
More difficult to
consolidated totals by higher
implement
levels in the attribute
hierarchy; for example, if each
product has a specific
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.

You can create crosstab views

displaying aggregate totals of
You can show a You can only
attributes associated with the
crosstab of all retrieve totals
same base dimension.
values of each based on specific
attribute UDA values.
dimension.

You can use Boolean operators

AND, OR, and NOT with
attribute and UDA values to
further refine a query. For
example, you can select
decaffeinated drinks from the
100 product group.

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

.
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
and 6 million, and so on.

.
Through the Attribute
Calculations dimension, you
can view aggregations of
attribute values as sums,
counts, minimums,
maximums, and averages.

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

You can retrieve specific base

members using attribute-
Powerful Limited to text
related information.
conditional and string matches
value-based only
selections

Data Conversion

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.

Calculation Scripts

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.

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

Designing Attribute
Dimensions
Analytic Services provides more than one way 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.

• Using Attribute Dimensions

• Using Alternative Design Approaches
• Optimizing Outline Performance

Using Attribute Dimensions

For the most flexibility and functionality, use attribute dimensions to
define attribute data. Using attribute dimensions provides the following
features:

• Sophisticated, flexible data retrieval

You can view attribute data only when you want to, you can
create meaningful summaries through crosstabs, and using type-
based comparisons, you can selectively view just the data you
want to see.
• Additional calculation functionality

Not only can you perform calculations on the names of members

of attribute dimensions to define members of standard
dimensions, you can also access five different types of
consolidations of attribute data-sums, counts, averages,
minimums, and maximums.
 • Economy and simplicity

Because attribute dimensions are sparse, Dynamic Calc, they are

not stored as data. Compared to using shared members, outlines
using attribute dimensions contain fewer members and are
easier to read.

For more information about attribute features, see Understanding

Attributes.

Using Alternative Design Approaches

In some situations, consider one of the following approaches:

• 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.
• 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 very large
if the categories repeat a lot of members.
• Standard dimensions and members. Additional standard
dimensions provide flexibility, but they add storage
requirements and complexity to a database. For guidelines on
evaluating the impact of additional dimensions, see Analyzing
and Planning.

Table?14 describes situations where you might consider one of these

alternative approaches for managing attribute data in a database.

Table 14: Considering Alternatives to Attribute Dimensions ?

Situation Alternative to Consider

Analyze attributes of UDAs or shared members.

dense dimensions

Perform batch Shared members or members of separate,

calculation of data standard dimensions.

Define the name of a Shared members or members of separate,

member of an
attribute dimension standard dimensions
as a value as that
results from a
formula

Define attributes that Members of separate, standard

vary over time dimensions. For example, to track product
maintenance costs over a period of time,
the age of the product at the time of
maintenance is important. However, using
the attribute feature you could associate
only one age with the product. You need
multiple members in a separate
dimension for each time period that you
want to track.

Minimize retrieval Batch calculation with shared members or

time with large members of separate, standard
numbers of base- dimensions.
dimension members

Optimizing Outline Performance

Outline layout and content can affect attribute calculation and query
performance. For general outline design guidelines, see Designing an
Outline to Optimize Performance.

To optimize attribute query performance, consider the following design

tips:

• 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, the base dimensions are the
most queried dimensions.

For information on optimizing calculation of outlines containing

attributes, see Optimizing Calculation and Retrieval Performance.
Building Attribute
Dimensions
To build an attribute dimension, first tag the dimension as attribute
and assign the dimension a type. Then associate the attribute
dimension with a base dimension. Finally, associate each level 0
member of the attribute dimension with a member of the associated
base dimension.

To build an attribute dimension, see "Defining Attributes" in the

Essbase XTD Administration Services Online Help.
To view the dimension, attribute value and attribute type of a
specific attribute member, use any of the following methods:

Tool Topic Location

Administration Viewing Attribute Essbase XTD

Services Information in Administration Services
Outlines Online Help

MaxL query database Technical Reference

ESSCMD GETATTRINFO Technical Reference

Setting Member Names

in Attribute Dimensions
All member names in an outline must be unique. When you use the
attribute feature, Analytic Services establishes some default member
names. These default names might duplicate names that already exist
in the outline. You can change these system-defined names for the
database and can establish other settings for members of attribute
dimensions in the database. The outline does not show the full
attribute names. You can see and use 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:

• 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

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.

Setting Prefix and Suffix Formats for Member Names of Attribute

Dimensions
The names of members of Boolean, date, and numeric attribute
dimensions are values. It is possible to encounter duplicate attribute
values in different attribute dimensions.

• Boolean example. If you have more than one Boolean

attribute dimension in?an outline, the two members of each
of those dimensions have the same names, by default, True
and False.
• Date example. If you have more than one date attribute
dimension, some member names in both dimensions could be
the same. For example, the date that a store opens in a
certain market could be the same as the date a product was
introduced.
• Numeric example. 12 can be the attribute value for the size of
a product and 12 could also be the value for the number of
packing units for a product. This example results in two
members with the same name-12.
Because Analytic Services does not allow duplicate member names,
you can define unique names by attaching a prefix or suffix to member
names in Boolean, date, and numeric attribute dimensions in the
outline. 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, Analytic Services 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 wish to display shorter names
in retrievals.

To define prefix and suffix formats, see "Defining a Prefix or Suffix

Format for Members of Attribute Dimensions" in the Essbase XTD
Administration Services Online Help.

Setting Boolean Attribute Member Names

When you set the dimension type of an attribute dimension as
Boolean, Analytic Services automatically creates two level 0 members
with the names specified for the Boolean attribute settings. The initial
Boolean member names in a database are set as True and False. If you
want to change these default names, for example, to Yes and No, you
must define the member names for Boolean attribute dimensions
before you create any Boolean attribute dimensions in the database.

Before you can set an attribute dimension type as Boolean, you must
delete all existing members in the dimension.

To define the database setting for the names of members of Boolean

attribute dimensions, see "Setting Member Names for Boolean
Attribute Dimensions" in the Essbase XTD Administration Services
Online Help.

Changing the Member Names in Date Attribute Dimensions

You can change the format of members of date attribute dimensions.
For example, you can use the following date formats:
 • mm-dd-yyyy displays the month before the day; for example,
October 18, 1999 is displayed as 10-18-1999.
• dd-mm-yyyy displays the day before the month; for example,
October 18, 1999 is displayed as 18-10-1999.

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-1999 member exists and you change the format to dd-mm-
yyyy, outline verification will find this member invalid. If you change
the date format, you must rebuild the date attribute dimensions.

To change the names of the members in date attribute dimensions,

see "Setting the Member Name Format of Date Attribute Dimensions"
in the Essbase XTD Administration Services Online Help.

Setting Up Member Names Representing Ranges of Values

Members of numeric attribute dimensions can represent single numeric
values or ranges of values:

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

Figure 63: Population Attribute Dimension and Members

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. Each range includes values greater than the name of the
preceding member up to and including the member value itself.
A setting for the outline establishes that each numeric member
represents the top of its range.
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, Analytic Services automatically

associates members of the base dimension with the appropriate
attribute range. For example, if numeric members represent the tops
of ranges, Analytic Services 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.

To set up ranges in numeric attribute dimensions, see "Assigning

Member Names to Ranges of Values" in the Essbase XTD
Administration Services Online Help.

Changing the Member Names of the Attribute Calculations

Dimension
To avoid duplicating names in an outline, you may need to change the
name of the Attribute Calculations dimension or its members. For more
information about this dimension, see Understanding the Attribute
Calculations Dimension.

Regardless of the name that you use for a member, its function
remains the same. For example, the second (Count) member always
counts, no matter what you name it.
 To change the names of the members in the Attribute Calculations
dimension, see "Changing Member Names of Attribute Calculations
Dimensions" in the Essbase XTD Administration Services Online Help.

Calculating Attribute
Data
Analytic Services calculates attribute data dynamically at retrieval
time, using members from a system-defined dimension created
specifically by Analytic Services. 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 Analytic Services calculations, including
dynamic calculations.

This section includes the following sections:

• Understanding the Attribute Calculations Dimension

• Understanding the Default Attribute Calculations Members
• Viewing an Attribute Calculation Example
• Accessing Attribute Calculations Members Using the
Spreadsheet
• Optimizing Calculation and Retrieval Performance
• Using Attributes in Calculation Formulas
• Understanding Attribute Calculation and Shared Members

Understanding the Attribute Calculations Dimension

When you create the first attribute dimension in the outline, Analytic
Services also creates the Attribute Calculations dimension comprising
five members with the default names Sum, Count, Min (minimum),
Max (maximum), and Avg (average). You can use these members in
spreadsheets or in reports to dynamically calculate and report on
attribute data, such as the average yearly sales of 12-ounce bottles of
cola in the West.
The Attribute Calculations dimension is not visible in the outline. You
can see it wherever you select dimension members, such as in the
Spreadsheet Add-in.

The attribute calculation dimension has the following properties:

• System-defined. When you create the first attribute

dimension in an application, Analytic Services 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. For a discussion
of calculation types, see Understanding the Default Attribute
Calculations Members.
• Label only. Like all label only dimensions, the Attribute
Calculations dimension shares the value of its first child, Sum.
For more information on the?label only dimension property,
see Member Storage Properties.
• 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. For a comprehensive discussion on dynamic
calculations, see Dynamically Calculating Data Values.
• Not displayed in Outline Editor. The Attribute Calculations
dimension is not displayed in Outline Editor. Members from
this dimension can be viewed in spreadsheets and in reports.

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, Analytic Services performs
the following tasks:

1. Finds the base-dimension members that are associated with

the specified attribute-dimension members present in the
current query
2. Dynamically calculates the sum, count, minimum, maximum,
or average for the attribute-member combination for the
current query
3. Displays the results in the spreadsheet or report
4. Discards the calculated values-that is, the values are not
stored in the database
 Note: Analytic Services excludes #MISSING values when
calculating attribute data.

For example, as shown in Figure?64, 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, Analytic Services dynamically calculates the average sales
values of all products associated with these attributes for the current
member combination (Actual?->?Sales?->?East?->?Qtr1):

Figure 64: Retrieving an Attribute Calculations Member

For information on accessing calculated attribute data, see Accessing

Attribute Calculations Members Using the Spreadsheet.

Understanding the Default Attribute Calculations Members

The Attribute Calculations dimension contains five members used to
calculate and report attribute data. These members are as follows:

• Sum calculates a sum, or total, of the values for a member

with an attribute or combination of attributes. Supports non-
additive consolidations such as multiplication, and two-pass
measures.

Note: The Sum member totals members based on their

consolidation property or formula. For example, the Sum
member uses the following formula to consolidate the profit
percentages of 12-ounce products:
 This calculation is not the sum of all percentages for all base-
dimension members with the Ounces attribute 12.
The default calculation for attributes is Sum. If a spreadsheet
user specifies a member of an attribute dimension in a
spreadsheet but does not specify a member of the Attribute
Calculations dimension, Analytic Services retrieves the sum for
the specified attribute or combination of attributes. For example,
in the spreadsheet view in Figure?65, the value in cell C4
represents the sum of sales values for the attributes Ounces_16
and Bottle for the current member combination (Actual?-
>?Sales?->?East?->?Qtr1), even though the Sum member is not
displayed in?the sheet.

Figure 65: Retrieving the Default Attribute Calculations Member

• Count calculates the number of members with the specified

attribute or combination of attributes, for which a data value
exists. Count includes only those members that have data
blocks in existence. To calculate a count of all members with
certain attributes, regardless of whether or not they have
data values, use the @COUNT function in combination with
the @ATTRIBUTE function. For more information, see the
Technical Reference.
• Avg calculates a mathematical mean, or average, of the non-
missing values for an specified attribute or combination of
attributes (Sum divided by Count).
• Min calculates the minimum data value for a specified
attribute or combination of attributes.
• Max calculates the maximum data value for a specified
attribute or combination of attributes.

Note: Each of these calculations excludes #MISSING values.

You can change these default member names, subject to the same
naming conventions as standard members. For a discussion of
Attribute Calculations member names, see Changing the Member
Names of the Attribute Calculations Dimension.

Viewing an Attribute Calculation Example

As an example of how Analytic Services calculates attribute data,
consider the following yearly sales data for the East:

Table 15: Sample Attribute Data

Base-Dimension Associated Sales Value for Attribute-
Member Attributes Member Combination

Cola Ounces_12, Can 23205

Diet Cola Ounces_12, Can 3068

Diet Cream Ounces_12, Can 1074

Grape Ounces_32, 6398

Bottle

Orange Ounces_32, 3183

Bottle

Strawberry Ounces_32, 5664

Bottle

A spreadsheet report showing calculated attribute data might look like

the following illustration:

Figure 66: Sample Spreadsheet with Attribute Data

As shown in the figure above, you can retrieve multiple Attribute
Calculations members for attributes. For example, you can calculate
Sum, Count, Avg, Min, and Max for 32-ounce bottles and cans.

Accessing Attribute Calculations Members Using the

Spreadsheet
You can access members from the Attribute Calculations dimension in
Spreadsheet Add-in. From the spreadsheet, users can view Attribute
Calculations dimension members using any of the following methods:

• Entering members directly into a sheet

• Selecting members from the Query Designer
• Entering members as an EssCell parameter

For more information on accessing calculated attribute data from the

spreadsheet, see the Essbase XTD Spreadsheet Add-in User's Guide.

Optimizing Calculation and Retrieval Performance

To optimize attribute calculation and retrieval performance, consider
the following considerations:

• The calculation order for attribute calculations is the same as

the order for dynamic calculations. For an outline of
calculation order, see Calculation Order for Dynamic
Calculation.
• Since Analytic Services 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:
o Configure the outline using the tips in Optimizing
Outline Performance.
o Drill down to the lowest level of base dimensions before
retrieving data. For example, in Spreadsheet Add-in,
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.
o 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 could group all 8-ounce products. Grouping
members by attribute may decrease retrieval time.

Using Attributes in Calculation Formulas

In addition to using the Attribute Calculations dimension to calculate
attribute data, you can also use calculation formulas on members of
standard or base dimensions to perform specific calculations on
members of attribute dimensions; for example, to determine
profitability by ounce for products sized by the ounce.

Note: You cannot associate formulas with members of attribute

dimensions.

You can use these functions to perform specific calculations on

attributes:

Type of Calculation Function to Use

Generate a list of all base members with a @ATTRIBUTE

specific attribute. For example, you can
generate a list of members that have the
Bottle attribute, and then increase the price
for those members.

Return the value of the level 0 attribute @ATTRIBUTEVAL

member from a numeric or date attribute @ATTRIBUTEBVAL
dimension (@ATTRIBUTEVAL), from a
boolean attribute dimension @ATTRIBUTESVAL
(@ATTRIBUTEBVAL), or from a text attribute
dimension (@ATTRIBUTESVAL) that is
associated with the base member being
calculated.
For example, you can 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).

Convert a date string to numbers for a @TODATE

calculation. For example, you can use
@TODATE in combination with the
@ATTRIBUTEVAL function to increase
overhead costs for stores opened after a
certain date.

Generate a list of all base dimension @WITHATTR

members associated with attributes that
satisfy the conditions that you specify. For
example, you can generate a list of products
that are greater than or equal to 20 ounces,
and then increase the price for those
products.

Note: For syntax information and examples for these functions, see
the Technical Reference. For an additional example using
@ATTRIBUTEVAL in a formula, see Calculating an Attribute Formula.

Understanding Attribute Calculation and Shared Members

Attribute calculations start at level 0 and stop at the first stored
member. Therefore, if your outline has placed a real member in
between two shared members in a an outline hierarchy, the calculation
results may not include the higher shared member.

For example:

Member 1 (stored)
     Member A (stored)
          Member 2 (shared) 
 Member B (stored)
     Member 1 (shared member whose stored member is Member 1 
above) 
 
In this example, when an attribute calculation is performed, the
calculation starts with level 0 Member 2, and stops when it encounters
the first stored member, Member A. Therefore, Member 1 would not be
included in the calculation.

Avoid mixing shared and stored members to avoid unexpected results

with attribute calculation. 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.

Linking Objects to
Analytic Services Data
This chapter described how you can link various kinds of data with any
cell in an Analytic Services database, using a linked reporting object
(LRO). This ability is similar to the file attachment features in an e-
mail software package.

An LRO provides improved support for planning and reporting

applications and can enhance your data analysis capabilities.

This chapter contains the following sections:

• Understanding LROs
• Understanding LRO Types and Data Cells
• Setting Up Permissions for LROs
• Viewing and Deleting LROs
• Exporting and Importing LROs
• Limiting LRO File Sizes for Storage Conservation

Understanding LROs
LROs are objects that you associate with specific data cells in an
Analytic Services database. Users create linked objects through
Spreadsheet Add-in by selecting a data cell and choosing a menu item.
There is no limit to the number of objects you can link to a cell. The
objects are stored on the Analytic Server where they are available to
any user with the appropriate access permissions. Users retrieve and
edit the objects through the Linked Objects Browser, which displays all
objects linked to the selected cell.

Table 16: Types of Linked Objects ?

Object
Description
Type

Cell note A text annotation of up to 599 characters.

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 An acronym for Uniform Resource Locator. A string

that identifies the location of a resource on the World
Wide Web, such as a document, image, downloadable
file, service, electronic mailbox, or other resource.
For example:
http://www.hyperion.com
ftp://ftp.hyperion.com
file:///D|/ESSBASE/docs/index.htm

Linked A set of data cells that you can link to in another

partition Analytic Services database.

For example, a sales manager may attach cell notes to recently

updated budget items. A finance manager might link a spreadsheet
containing supporting data for this quarter's results. A product
manager might link bitmap images of new products. A sales manager
may link the URL of a company's Web site to quickly access the
information on the Web site.

Understanding LRO
Types and Data Cells
LROs are linked to data cells-not to the data contained in the cells. The
link is based on a specific member combination in the database.
Adding or removing links to a cell does not affect the cell contents.

When a user links an object to a cell, Analytic Services creates an

entry for the object in the linked object catalog for the database. The
catalog, an internal data structure stored with the database index,
contains information describing the object, such as the object handle,
object type, the name of the last user to modify the object, and the
date the object was modified. Developers use the object handle in
Analytic Services API functions to refer to the object.

The storage strategy depends on the LRO type:

• 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, the Analytic Services Kernel stores the
contents of the file in the database directory on the Analytic
Server, giving it a .LRO extension. Analytic Services imposes
no restrictions on the data formats of linked files and
performs no file-type checking. It is up to the user's client
machine to render the file after retrieving it from the Analytic
Server.
• If the object is a URL, Analytic Services stores the URL string
as part of the object description in the catalog entry. Analytic
Services does not check the syntax of the URL until the user
tries to view it. At that time, Analytic Services 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
Analytic Services Partitioning feature.

Before you perform any tasks related to LROs, be aware of these facts:

• Analytic Services 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
and so are the links to linked objects.
• Shared members share data values but do not share LROs.
This is because LROs are linked to specific member
combinations and shared members do not have identical
member combinations. If you want a given object to be linked
to shared members, you must 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, first delete it, then use Spreadsheet Add-in to
re-link the object to the desired member combination.

Setting Up Permissions
for LROs
Users who add, edit, and delete LROs through client interfaces need to
have the appropriate security permissions in the active database. If
the object is a linked partition, the user must also have the required
permissions in the database containing the linked partition.

This table lists the permissions required for several different tasks.

Table 17: Permissions Required for LRO Tasks

Task Permission

Add a linked object to a database Read/Write

View an existing linked object Read

Edit an existing linked object Read/Write

Delete a linked object Read/Write

Export the LRO catalog to a file Read

Import the LROs from the LRO-catalog file Read/Write

Sometimes you might want to prevent users from linking files to data
cells without changing their access to other data in a database. You
can accomplish this by setting 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 only attach very small files (under 1?kilobyte).
 To set the maximum LRO file size for an application, see "Limiting
LRO File Sizes" in Essbase XTD Administration Services Online Help.

Viewing and Deleting

LROs
Users work with LROs through Spreadsheet Add-in on a cell-by-cell
basis. That is, they select a cell and open the Linked Object Browser,
which displays the objects linked to the selected cell. With
Administration Services, you can view and delete all LROs for the
entire database. You can also view LROs based on selection criteria
such as user name and last modification date. For example, you might
want to purge all objects that are older than a certain date, or remove
the objects belonging to a user who has left the company.

To view the linked objects for a database, use any of the following
methods:

Tool Topic Location

Administration Managing LROs Essbase XTD

Services Administration Services
Online Help

MaxL query database Technical Reference

ESSCMD LISTLINKEDOBJECTS Technical Reference

To delete the linked objects for a database, use any of the following
methods:

Tool Topic Location

Administration Managing LROs Essbase XTD

Services Administration
Services Online Help

MaxL alter database Technical Reference

ESSCMD PURGELINKEDOBJECTS Technical Reference

Exporting and
Importing LROs
To improve backup and data-migration capabilities, you can export and
re-import LROs from data intersections in a database.

To export and import linked objects for a database, use any of the
following methods:

Tool Topic Location

Administration Exporting Essbase XTD Administration

Services LROs Services Online Help
Importing
LROs

MaxL export lro Technical Reference

import lro

Limiting LRO File Sizes

for Storage
Conservation
Because Analytic Services stores linked files in a repository on the
server, you might want to limit the size of files that users can link. By
default, the size is unlimited. Limiting the size prevents a user from
taking up too much of the server resources by storing extremely large
objects. You can set the maximum linked file size for each application.
If a user attempts to link a file that is larger than the limit, an error
message displays.

To prevent users from attaching anything except very small files, enter
1. Setting the file size to 1, lets users link only cell notes, URLs, and
files less than 1 kilobyte in size.

Note: The maximum file size setting applies only to linked files and
does not affect cell notes or URLs. The maximum cell note length is
fixed at 599 characters. The maximum URL string length is fixed at
512 characters.

To limit the size of a linked object, use any of the following methods:

Tool Topic Location

Administration Limiting LRO File Essbase XTD

Services Sizes Administration Services
Online Help

MaxL alter Technical Reference

application

ESSCMD SETAPPSTATE Technical Reference

Designing and Building

Currency Conversion
Applications
You use the Analytic Services currency conversion feature to translate
financial data from one currency into another currency. Currency
conversion facilitates comparisons among countries, and enables
consolidation of financial data from locations that use different
currencies. This feature can be licensed as an "add-on" to Analytic
Server.

For example, consider an organization that analyzes profitability data

from the UK, reported in pounds, and from Japan, reported in yen.
Comparing local currency profitability figures side-by-side in a
spreadsheet is meaningless. To understand the relative contribution of
each country, you need to convert pounds into yen, yen into pounds,
or both figures into another currency.

As another example, reporting total profitability for North America

requires standardization of the local currency values that constitute the
North America total. Assuming that the United States, Mexico, and
Canada consolidate into Total North America, the profitability total is
meaningless if data is kept in local currencies. The Total North America
sum is meaningful only if local currencies are converted to a common
currency prior to consolidation.

The Analytic Services installation includes the option to install the

Sample currency application, which consists of two databases, Interntl
and Xchgrate. If you do not have access to these databases, contact
your Analytic Services administrator. For information about installing
Sample currency applications, see the Essbase XTD Analytic Services
Installation Guide.

This chapter contains the following topics:

• About the Sample Currency Application

• Structure of Currency Applications
• Conversion Methods
• Building Currency Conversion Applications and Performing
Conversions

About the Sample

Currency Application
The Sample currency application builds on the business scenario
introduced in Case Study: Designing a?Single-Server, Multidimensional
Database, as the Beverage Company (TBC) expands its business
outside the United States. TBC adds the following markets:
 • Three locations in Canada: Toronto, Vancouver, and Montreal
• Four locations in Europe: the UK, Germany, Switzerland, and
Sweden

In addition, TBC adds a new member, US, which is a consolidation of

data from the United States 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 needs to analyze actual data in two ways:

• Actuals are converted at actual exchange rates.

• 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 Analytic Server, the
databases are in the Sample application. If you do not have access to
the databases, contact your Analytic Services administrator. For
information about installing Sample currency applications, see the
Essbase XTD Analytic Services Installation Guide.

Structure of Currency
Applications
In a business application requiring currency conversion, the main
database is divided into at least two slices. One slice handles input of
the local data, and another slice holds a copy of the input data
converted to a common currency.

Analytic Services holds the exchange rates required for currency

conversion in a separate currency database. The currency database
outline, which is automatically generated by Analytic Services from the
main database after you assign the necessary tags, typically maps a
given conversion ratio onto a section of the main database. After the
currency database is generated, it can be edited just like any other
Analytic Services database.
The relationship between the main database and the currency
database is illustrated in Figure?67.

Figure 67: Currency Application Databases

Main Database
To enable Analytic Services 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 a

minimum, the main database must contain the following dimensions:

• A dimension tagged as time. Tagging a dimension as time

generates a dimension in the currency database that is
identical to the time dimension in the main database. In the
Sample Interntl database, the dimension tagged as time is
Year.
• A dimension tagged as accounts. Tagging a dimension as
accounts and assigning currency categories to its members
creates a dimension in the currency database that contains
members for each of the individual currency categories.
Category assignment enables the application of different
exchange rates to various accounts or measures. In the
Sample Interntl database, the dimension tagged as accounts
is Measures.
Each descendant of a member inherits the currency category tag
of its ancestor. A member or sub-branch of members can also
have its own category.
For example, profit and loss (P&L) accounts may use exchange
rates that differ from the rates used with balance sheet
accounts. In addition, some accounts may not require
conversion. For example, in the Sample Interntl database,
members such as Margin% and Profit% require no conversion.
You tag members not to be converted as No Conversion. The No
Conversion tag is not inherited.
• A market-related dimension tagged as country. Tagging a
dimension as country and assigning currency names to
individual countries creates a member in the currency
database for each currency. In the Sample Interntl database,
the Market dimension is tagged as country. The currency
name for this dimension is USD (U.S. dollars), because all
local currencies must be converted to USD, the company's
common currency.
Because multiple members can have the same currency name,
the number of currency names is typically less than the total
number of members in the dimension. As shown in Table?18, the
Sample Interntl database uses only six currency names for the
15 members in the Market dimension. Each of the children of the
member Europe use a different currency and, therefore, must be
assigned an individual currency name. However, the US
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
single currency, you need to define a currency name for only the
parent member.

Table 18: Interntl Database Currency Names ?

Dimensions and Members Currency Name

Market - Country USD (U.S. dollar)

US
East
West
South
Central

Canada CND (Canadian dollar)

 Toronto
Vancouver
Montreal

Europe
UK GBP (British pound)
Germany EUR (Euro)
Switzerland CHF (Swiss franc)
Sweden SEK (Swedish krona)

When preparing a main database outline for currency conversion, you

can create an optional currency partition to tell Analytic Services which
slice of the database holds local currency data and which slice of the
database 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.

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.

The Essbase XTD Spreadsheet Add-in User's Guide provides examples

of ad hoc currency reporting capabilities. Report scripts enable the
creation of reports that convert data when the report is displayed, as
discussed under Converting Currencies in Report Scripts.

Note: For a list of methods used to create the main database

outline, see Creating Main Database Outlines.
Currency Database
By assigning currency tags to members in the main database outline,
you enable Analytic Services to generate the currency database
automatically. In the Sample currency application, the currency
database is Xchgrate (XREF TO SCREENSHOT ABOVE).

A currency database always consists of the following three dimensions,

with an optional fourth dimension:

• 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 are usually 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. CurName contains the following currency names:

Table 19: Xchgrate Database Currency Names

Dimension and Members Alias Name

CurName - Country
USD US dollar
CND Canadian dollar
GBP British pound
EUR Euro
 CHF Swiss franc
SEK Swedish krona

• 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.
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).
• A currency database 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, simply
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 are not
required to 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 Applications and Performing
Conversions.

Conversion Methods
Different currency applications have different conversion requirements.
Analytic Services supports two conversion methods:

• Overwriting local values with converted values.

 Some applications require only converted values to be stored in
the main database. Local values are entered and the conversion
operation overwrites local values with common currency values.
This method assumes that there is no requirement for reporting
or analyzing local currencies.
Because this operation overwrites data, you must load local
values and recalculate the data each time you perform a
conversion. This method is useful only when you want to perform
a single (not an ongoing) conversion.
• Keeping local and converted values.

Most applications require data to be stored in both local and

common currency (converted) values. This method permits
reporting and analyzing local data. In addition, data
modifications and recalculations are easier to control. To use this
method, you must define a currency partition (see Main
Database).

Either of these two methods may require a currency conversion to be

applied 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
Spreadsheet Add-in, as discussed in the Essbase XTD Spreadsheet
Add-in User's Guide, or by using a report script, as discussed under
Converting Currencies in Report Scripts.

Building Currency
Conversion Applications
and Performing
Conversions
To build a currency conversion application and perform conversions,
use the following process:
 1. Create or open the main database outline. See Creating Main
Database Outlines.
2. Prepare the main database outline for currency conversion.
See Preparing Main Database Outlines.
3. Generate the currency database outline. See Generating
Currency Database Outlines.
4. Link the main and currency databases. See Linking Main and
Currency Databases.
5. Convert currency values. See Converting Currency Values.
6. Track currency conversions. See Tracking Currency
Conversions.
7. If necessary, troubleshoot currency conversion. See
Troubleshooting Currency Conversion.

Creating Main Database Outlines

To create a main database outline, you need to create or open an
Analytic Services database outline, modify the outline as needed, and
then save the outline for use in the currency conversion application.

To create a new outline or open an existing outline, use any of the

following methods:

Tool Topic Location

Administration Opening and Essbase XTD

Services Editing Outlines Administration Services
Online Help

MaxL create Technical Reference

database

ESSCMD CREATEDB Technical Reference

Preparing Main Database Outlines

After you create or open the main database outline, you need to
modify dimensions and members to enable Analytic Services to
generate the currency database outline automatically. For more
information, see Main Database.
 To prepare a main database outline, see "Preparing the Main
Database Outline for Currency Conversion" in Essbase XTD
Administration Services Online Help.

Generating Currency Database Outlines

After you verify and save the main database outline, you can generate
the currency outline. The currency outline contains dimensions,
members, currency names, and currency categories previously defined
in the main database outline. The currency database outline is
basically structured and ready to use after being generated but may
require additions to make it complete.

To generate a currency database outline, see "Generating a Currency

Database Outline" in Essbase XTD Administration Services Online Help.

Linking Main and Currency Databases

To perform a currency conversion calculation, Analytic Services must
recognize a link between the main and currency databases. Generating
a currency outline does not automatically link a main database with a
currency database. When you link the databases, you specify the
conversion calculation method and the default currency type member.

To link main and currency databases, see "Linking a Database to a

Currency Database" in Essbase XTD Administration Services Online
Help.

Converting Currency Values

After you create a currency conversion application, you convert data
values from a local currency to a common, converted currency by
using the CCONV command in calculation scripts. For example, you
might convert data from a variety of currencies into USD (U.S.
dollars). You can convert the data values back to the original, local
currencies by using the CCONV TOLOCALRATE command.

You can convert all or part of the main database using the rates
defined in the currency database. You can overwrite local values with
converted values, or you can keep both local and converted values in
the main database, depending on your tracking and reporting needs.
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. Analytic
Services does not display a warning message in this situation.

Note: When you convert currencies using the CCONV command,

the resulting data blocks are marked as dirty for the purposes of
Intelligent Calculation. Thus, Analytic Services recalculates all
converted blocks when you recalculate the database.

To see sample currency conversion calculation scripts, see the

Technical Reference.

Overwriting Local Values with Converted Values

If you want to overwrite local values, you do not need to create a
currency partition dimension in the main database. Use the CCONV
command in a calculation script to convert all data in the database:

The following calculation script converts the values in the database to

USD:

CCONV USD; 
CALC ALL; 
 

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 only converts 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 setting is TRUE in
the essbase.cfg file.

Keeping Local and Converted Values

You can keep both local and converted values in a database. In the
main database you need to define the members that store the local
and the converted values. You define the members by creating a
currency partition dimension (see Main Database). The currency
partition dimension has two partitions, one for local values and one for
converted values.

To create a calculation script that copies local data to a converted

partition and calculates the data, use the following process:
1. Use the DATACOPY command to copy data from the local to
the converted partition.
2. Use the FIX command to calculate only the converted
partition and use the CCONV command to convert the data.

Note: When using a currency partition dimension, you must

FIX on a member of the dimension to use the CCONV
command.

3. Use the CALC command to recalculate the database.

The following example is based on the Sample Interntl database and

the corresponding Sample Xchgrate currency database. Figure?68
shows the currency partition from the Sample Interntl database.

Figure 68: Calculating Local and Converted Currency Conversions

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)
CCONV TOLOCALRATE "Bud xchg";
ENDFIX
CALC ALL; 
 

Note: When you convert currencies using the CCONV command,

the resulting data blocks are marked as dirty for the purposes of
Intelligent Calculation. Thus, Analytic Services 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 US use dollars as the
unit of currency. Therefore, all children of US consolidate to US.
Consolidation stops at the country level, however, because North
America contains countries that use other currencies.
Converting Currencies in Report Scripts
You can convert currencies in report scripts, using the CURRENCY
command to set the output currency and the currency type. For the
syntax and definitions of Report Writer commands, see the Technical
Reference.

Note: Analytic Services cannot perform "on the fly" currency

conversions across transparent databases. If you have two
transparent partition databases that 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??????Mar 
??????????????????????========?========?======== 
100­10????????????????3???????????3????????3 
100­20????????????????2???????????2????????2 
100­30????????????????#Missing?#Missing?#Missing 
100???????????????????5???????????5????????5 
????????????Currency: Jan­>Peseta­>Act xchg 

????????????Currency: Jan­>Peseta­>Act xchg 
??????????????????????Illinois Sales Budget 
??????????????????????Jan??????Feb??????Mar 
??????????????????????======== ======== ======== 
100­10????????????????3???????????3????????3 
100­20????????????????2???????????2????????2 
100­30????????????????#Missing?#Missing?#Missing 
100???????????????????5???????????5????????5  
 
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
   ! 
 

Tracking Currency Conversions

You can use the CCTRACK setting in the essbase.cfg file to control
whether Analytic Services tracks the currency partitions that have
been converted and the exchange rates that have been used for the
conversions. Tracking currency conversions has the following
advantages:

• Enables conversion to occur at report time through

Spreadsheet Add-in or Report Writer
• Enables conversion of a converted currency back to its
original, local rate through use of the CCONV TOLOCALRATE
command
• Prevents data inacurracies due to accidental reconversion of
data during a currency calculation.
By default CCTRACK is turned on. Analytic Services 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 either "converted" or
"unconverted." Analytic Services does not store a flag for member
combinations within a partition. When CCTRACK is turned on, the
following restrictions apply:

• If you are using currency partitions, you can use a FIX

statement with the CCONV command only on currency
partition members. For example, in the Sample Basic
database, the following example is valid:
• FIX(Actual)
• CCONV "Act xchg"­>US$;
• ENDFIX]
• If you are not using currency partitions, you must use CCONV
with a FIX statement.

Reasons to Turn Off CCTRACK

For increased efficiency when converting currency data between
currency partitions, you may want to turn off CCTRACK. For example,
you load data for the current month into the local 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.

Methods for Turning Off CCTRACK

You can turn off CCTRACK in three ways:

• 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 provide increased 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 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:
o 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.
o Similarly, the currency report options assume that the
data is unconverted (is in local currency). If the data
has already been converted in the database, it is
reconverted at report time, resulting in inaccurate data.
o 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. Analytic
Services does not display a warning message in this situation.

Troubleshooting Currency Conversion

For information about how to troubleshoot currency conversions, see
"Troubleshooting Currency Conversion" in Essbase XTD Administration
Services Online Help.

Designing Partitioned
Applications
An Analytic Services partitioned application can span multiple servers,
processors, or computers. A partition is the piece of a database that is
shared with another database. Partitioning applications can provide the
following benefits:

• Improved scalability, reliability, availability, and performance

of databases
• Reduced database sizes
• More efficient use of resources

This chapter contains the following sections:

• Process for Designing a Partitioned Database

• Understanding Analytic Services Partitioning
• Deciding Whether to Partition a Database
• Determining Which Data to Partition
• Deciding Which Type of Partition to Use
• Planning for Security for Partitioned Databases
• Case Studies for Designing Partitioned Databases

Caution: Design partitions carefully. Hyperion strongly

recommends that you read this chapter before creating partitions.

Process for Designing a

Partitioned Database
Here is the suggested process for designing a partitioned database.

1. Learn about partitions. See Understanding Analytic Services

Partitioning.
2. Determine whether the database can benefit from
partitioning. See Deciding Whether to Partition a Database.
3. Identify the data to partition. See Determining Which Data to
Partition.
4. Decide on the type of partition. See Deciding Which Type of
Partition to Use.
5. Understand the security issues related to partitions. See
Planning for Security for Partitioned Databases.
Understanding Analytic
Services Partitioning
Analytic Services Partitioning is a collection of features that makes it
easy to design and administer databases that span Analytic Services
applications or servers. Partitioning is licensed separately from Analytic
Services. The Partitioning option must be licensed for every server that
contains a database partition.

Partitioning can provide the following benefits:

• Synchronize the data in multiple partitioned databases.

Analytic Services tracks changes made to data values in a
partition and provides tools for updating the data values in
related partitions.
• Synchronize the outlines of multiple partitioned databases.
Analytic Services tracks changes made to the outlines of
partitioned databases and provides tools for updating related
outlines.
• Allow users to navigate between databases with differing
dimensionality. When users drill across to the new database,
they can drill down to more detailed data.

Based on user requirements, select one of the following partitioning

strategies:

• Partition applications from the top down. Use top-down

partitioning to split a database onto multiple processors,
servers, or computers. Top-down partitioning can improve the
scalability, reliability, and performance of databases. To
achieve the best results with top-down partitioning, create a
separate application for each partitioned database.
• Partition applications from the bottom up. Use bottom-up
partitioning to manage the flow of data between multiple
related databases. Bottom-up partitioning can improve the
quality and accessibility of the data in databases.
• Partition databases according to attribute values associated
with base dimensions (a base dimension is a standard
dimension associated with one or more attribute dimensions).
Partitioning a base dimension according to its attributes
 enables the user to extract data based on the characteristics
of a dimension such as flavor or size.

This section contains the following sections:

• What Is a Partition?
• Data Sources and Data Targets
• Overlapping Partitions
• Attributes in Partitions

What Is a Partition?
A partition is a piece of a database that is shared with another
database. Partitions contain the following parts, as illustrated in
Figure?69.

• Type of partition. A flag indicating whether the partition is

replicated, transparent, or linked.
• Data source information. The server, application, and
database name of the data source.
• Data target information. The server, application, and database
name of the data target.
• Login and password. 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 user operations.
• Shared areas. A definition of one or more areas, or subcubes,
shared between the data source and the data target. To share
more than one non-contiguous portion 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 Analytic Services 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. Analytic Services 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.
• State of the partition. Information about whether the partition
is up-to-date and when the partition was last updated.
 Figure 69: Parts of a Partition

Data Sources and Data Targets

Partitioned databases contain at least one data source, the primary
site of the data, and at least one data target, the secondary site of the
data. A single database can serve as both the data source for one
partition and the data target for another. When you define a partition,
you map cells in the data source to their counterparts in the data
target:

Figure 70: Data Source and Data Target

An Analytic Services database can contain many different partitions as

well as data that is not shared with any other Analytic Services
database. You can define partitions between the following databases:

• Different databases in different applications, as long as each

database uses the same language (for example, German).
• Different databases in different applications on different
processors or computers, as long as each database uses the
same language (for example, German).
• Different databases in one application. This practice is not
recommended, because you cannot reap the full benefits of
partitioning databases unless each database is in a separate
application.
You can only define one partition of each type between the same two
databases. For example, you can only create one replicated partition
between the Sampeast East database and the Samppart Company
database. The East or Company databases can, however, contain many
replicated partitions that connect to other databases.

A single 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:

Figure 71: Data Shared at Multiple Targets

Overlapping Partitions
An overlapping partition occurs when similar data from two or more
databases serve as the data source for a single 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
dimension East, the data for Boston mapped to database 3 from
database 1 and database 2, overlap. This data overlap results in an
overlapping partition:

Figure 72: Overlapping Partitions

An overlapping partition is allowed in linked partitions, but is invalid in
replicated and transparent partitions and generates an error message
during validation.

Attributes in Partitions
You can use attribute functions for partitioning on attribute values. But
you cannot partition an attribute dimension. Use attribute values to
partition a database when you want 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 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.

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:

Figure 73: Correct Partitioning

Source???????????????????Target
@ATTRIBUTE(Caffeinated)??@ATTRIBUTE(Caffeinated) 
 

Based on the previous example, this partition is incorrect:

Figure 74: Incorrect Partitioning

Source???????????????????Target
Caffeinated??????????????Caffeinated 
 

For more information about these commands, refer to the section on

calculation commands in the Technical Reference.

For more information on attribute dimensions, see Working with

Attributes.

Deciding Whether to
Partition a Database
Partitioning a database is not always the correct option. The following
sections provide questions you can use to determine if partitioning the
database is the best solution for you.

• When to Partition a Database

• When Not to Partition a Database

When to Partition a Database

Review the following list of questions. If you answer yes to many of
them, or answer yes to some that are very important to you, you may
wish to partition databases.
 • Should the data be closer to the people who are using it? Is
the network being stressed because users are accessing data
that is far away?
• Would a single failure be catastrophic? If everyone is using a
single database for mission-critical purposes, what happens if
the database goes down?
• Does it take too long to perform calculations after new data is
loaded? Can you improve performance by spreading the
calculations across multiple processors or computers?
• Do users want to see the data in different application
contexts? Would you like to control how they navigate
between databases?
• Do you have separate, disconnected databases storing related
information? Does the related information come from different
sources? Are you having trouble synchronizing it?
• Will you add many new organizational units? Would they
benefit from having their own databases? Partitioned
databases help you grow incrementally.
• Are users having to wait as other users access the database?
• Do you want to save disk space by giving users access to data
stored in a remote location?
• Should you reduce network traffic by replicating data in
several locations?
• Do you need to control database outlines from a central
location?

When Not to Partition a Database

Sometimes, it does not make sense to partition a centralized database.
Partitioning a database can require additional disk space, network
bandwidth, and administrative overhead. Review the following list of
questions. If you answer yes to many of them, or answer yes to some
that are very important to you, you may not want to partition a
database.

• Do you have resource concerns? For example, are you unable

to purchase more disk space or allow more network traffic?
• Do you perform complex allocations where unit level values
are derived from total values?
• Are you required to keep all databases online at all times?
Keeping databases online can be a problem if you have
databases in several time zones, because peak user load may
differ between time zones. Using linked and transparent
 partitions exacerbate this problem, but using replicated
partitions might help.
• Are the databases in different languages? Analytic Services
can only partition databases if both databases use the same
language, such as German.

Determining Which
Data to Partition
When designing a partitioned database, find out the following
information about the data in the database:

• Which database should be the data source and which the data
target? The database that "owns" the data should be the data
source. Owning the data means that this is the database
where the data is updated and where most of the detail data
is stored.
• Are some parts of the database accessed more frequently
than others?
• What data can you share among multiple sites?
• How granular does the data need to be at each location?
• How frequently is the data accessed, updated, or calculated?
• What are the available resources? How much disk space is
available? CPUs? Network resources?
• How much data needs to be transferred over the network?
How long does that take?
• Where is the data stored? Is it in one location or in more than
one location?
• Where is the data accessed? Is it in one location or in more
than one location?
• Is there information in separate databases that should be
accessed from a central location? How closely are groups of
data related?

The answers to these questions determine which data to include in

each partition. For examples, see Case Studies for Designing
Partitioned Databases.

Note: You cannot partition attribute dimensions. See Attributes in

Partitions.
Deciding Which Type of
Partition to Use
Analytic Services supports the following types of partitions:

• A replicated partition is a copy of a portion of the data source

that is stored in the data target.
• A transparent partition allow 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, in another Analytic Services database, or
on another Analytic Server.
• A linked partition sends users from a cell in one database to a
cell in another database. Linked partitions give users a
different perspective on the data.

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.

In the Samppart and Sampeast applications shipped with Analytic

Services, for example, the database administrator 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 the corporate headquarters, their response times are faster and
they have more control over the down times and administration of the
local data. For a more complete description of the sample partitioned
databases provided with Analytic Services, see Case Study 1:
Partitioning an Existing Database.

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, Analytic Services overwrites their changes when the
database administrator updates the replicated partition.
The database administrator can prevent the data in the replicated
portion of the data target from being updated. This setting takes
precedence over access provided by security filters and is also honored
by batch operations such as dataload and calculation. By default,
replicated partitions are not updateable. For directions on how to set a
partition as updateable, see the Essbase XTD Administration Services
Online Help.

Use a replicated partition when you want to achieve any of the

following goals:

• Decrease network activity.

• Decrease query response times.
• Decrease calculation times.
• Make it easier to recover from system failures.

These sections help you assess the value of replicated partitions:

• Rules for Replicated Partitions

• Advantages and Disadvantages of Replicated Partitions
• Performance Considerations for Replicated Partitions
• Replicated Partitions and Port Usage

Rules for Replicated Partitions

Replicated partitions must follow these rules:

• You must be able to map the shared replicated areas of the

data source and data target outlines even though the shared
areas do not have to be identical. You must tell Analytic
Services 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.
• You cannot create a replicated partition on top of a
transparent partition. In other words, none of the areas that
you use as a replicated partition target can come from a
transparent partition source:

Figure 75: Invalid Replicated Partition

 • The cells in the data target of a replicated partition cannot
come from two different data sources; the cells in one
partition must come from just one database. If you want to
replicate cells from more than one database, 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 the Sampeast East
database into a third database, such as the Sampwest West
database.
• 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 a replicated partition contains
dynamic data, not stored data. Hence, an attempt to map
attributes in replicated partitions results in an error message.
However, you can use the WITHATTR command to replicate
attribute data.

For a discussion of using Dynamic Time Series members in replicated

partitions, see Using Dynamic Time Series Members in Partitions.

Advantages and Disadvantages of Replicated

Partitions
Replicated partitions can solve many database problems, but replicated
partitions are not always the ideal partition type. This section describes
the advantages and disadvantages of using a replicated partition.

Advantages of Replicated Partitions

Following are the advantages of using a replicated partition.

• Replicated partitions can decrease network activity, because

the data is now stored closer to the end users, in the data
target. Decreased network activity results in improved
retrieval times for the 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 more
than one place, if a single database fails, only the users
connected to that database are unable to access the
information. It is still available at and can be retrieved from
the other sites.
• Local database administrators can control the down time of
their local databases. For example, because users in the
eastern region are accessing their?own replicated data
instead of the Company database, the database administrator
can bring down the Company database without affecting the
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 just the eastern budget information, instead of
accessing a larger company database containing budget
information for all regions.

Disadvantages of Replicated Partitions

Following are the disadvantages of using a replicated partition.

• You need more disk space, because you are storing the data
in two or more locations.
• The data must be refreshed regularly by the database
administrator, so it is not up-to-the-minute.

Performance Considerations for Replicated Partitions

To improve the performance of replicated partitions, consider the
following when replicating data.

• Do not replicate members that are dynamically calculated in

the data source to greatly reduce replication time, because
Analytic Services 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 to greatly
reduce replication time. Instead, try to 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:
o 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.
o 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, you must 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 Requires data outside the replicated area to be
calculated.
o Requires calculation scripts from which you cannot
extract just the portion to be calculated at the data
target.
o Is being replicated onto a computer with little
processing power, such as a laptop.
• Partitioning along a dense dimension takes more time than
partitioning along a sparse dimension. When Analytic Services
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. For
example, if the Market dimension were dense and you
replicated the data in the East member, Analytic Services
must access every block in the database and then create each
block at the data target during the replication operation.
• You cannot replicate data into a member that is dynamically
calculated at the data target. Dynamic Calc and Dynamic Calc
and Store members do not contain any data until a user
requests the data at run time. Analytic Services does not load
or replicate into Dynamic Calc and Dynamic Calc and Store
 members. Analytic Services avoids sending replicated data for
both dynamic dense and dynamic sparse members on the
replication target, since this data is not stored on the data
target.
• See Populating or Updating Replicated Partitions to replicate
only the data values that have changed instead of the entire
partition.

Replicated Partitions and Port Usage

One port is used for every unique user and computer combination. If a
user defines several replicated partitions on one server using the same
user name, then only one port is occupied.

In a replicated partition, when a user (user1) drills into an area in the

target that accesses source data, user1 is using the user name
declared in the partition definition (partition user) to access the data
from the source database. This access causes the use of an additional
port because different users (user1 and partition user) are connecting
to the application.

If a second user (user2) connects to the target database and drills

down to access source data, user2 also uses the user name declared in
the partition definition (partition user) to access the source database.
Because the partition user is already connected to the source
database, an additional port is not needed for the partition user, as
long as user2 is accessing the same source database.

Note: Because of the short-term nature of replication, replicated

partitions and ports are rarely 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 76: Transparent Partitions

Because the data is retrieved directly from the data source, users see
the latest version of the data. When they update the data, their
updates are written back to the data source. This process means that
other users at both the data source and the data target have
immediate access to those updates.

With a transparent partition, users at the data source may notice

slower performance as more users access the source data and users at
the data target may notice slower performance as more users access
the source data.

For example, the database administrator at TBC can use a transparent

partition to calculate each member of the Scenario dimension on a
separate CPU. This process reduces the elapsed time for the
calculation, while still providing users with the same view of the data.
For a more complete description of a transparent partition based on
the Sample Basic database, see Case Study 1: Partitioning an Existing
Database.

Use a transparent partition when you want to achieve the following

goals:

• Show users the latest version of the data.

• Allow users at the data target to update data.
• Decrease disk space.

These sections help you assess the value of transparent partitions:

• Rules for Transparent Partitions

• Advantages and Disadvantages of Transparent Partitions
• Performance Considerations for Transparent Partitions
 • Calculating Transparent Partitions
• Performance Considerations for Transparent Partition
Calculations
• Transparent Partitions and Member Formulas
• Transparent Partitions and Port Usage

Rules for Transparent Partitions

Transparent partitions must follow these rules:

• The shared transparent areas of the data source and data

target outlines do not have to be identical, but you must be
able to map the dimensions in them. You must tell Analytic
Services 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, but attribute associations
should 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.
• You cannot use attribute dimensions or members to define a
transparent partition. For example, associated with the
Market dimension, the Market Type attribute dimension has
members Urban, Suburban, and Rural. You cannot define a
partition on Urban, Suburban, or Rural.
• 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:

Figure 77: Valid Transparent Partition

 • As illustrated in Figure?78, you cannot create a transparent
partition on top of more than one other partition. 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 location-either the local disk or a
remote disk.

Figure 78: Invalid Transparent Partition

• Carefully consider any formulas you assign to members in the

data source and data target.

For a discussion on using Dynamic Time Series members in

transparent partitions, see Using Dynamic Time Series Members in
Partitions.

Advantages and Disadvantages of Transparent

Partitions
Transparent partitions can solve many database problems, but
transparent partitions are not always the ideal partition type. This
section describes the advantages and disadvantages of using a
transparent partition.

Advantages of Transparent Partitions

Following are the advantages of using a transparent partition:

 • 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, Analytic
Services makes those changes at the data target.
• Individual databases are smaller, so they can be calculated
more quickly.
• The distribution of the data is invisible to the end user and
the end user's tools.
• You can load the data from either the data source or the data
target.

Disadvantages of Transparent Partitions

Following are the disadvantages of using a transparent partition:

• Transparent partitions increase network activity, because

Analytic Services 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 the data target need them.
• You can perform some administrative operations only on local
data. For example, if you archive the data target, Analytic
Services archives just the data target and does not archive
the data source. The following administrative operations work
only on local data:
o CLEARDATA calculation command
o DATACOPY calculation command
o EXPORT command
o VALIDATE command
o BEGINARCHIVE and ENDARCHIVE commands
o Restructure operations in Administration Services
• When you perform a calculation on a transparent partition,
Analytic Services performs the calculation using the current
values of the local data and transparent dependents. Analytic
Services does not recalculate the values of transparent
dependents. 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.
Analytic Services 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
accurate.
For example, suppose that the data target outline contained a
Market dimension with East, West, South, and Central members
and the data source outline contained 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
any changes made to New York and New Jersey in the data
source. To perform an accurate calculation, therefore, you must
first calculate East in the data source and then calculate the data
target.
For a tip on improving performance of transparent calculations,
see Calculating Transparent Partitions.
• 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.

If these disadvantages are too serious, consider using replicated or

linked partitions instead.

Performance Considerations for Transparent

Partitions
To improve the performance of transparent partitions, consider the
following facts when creating the partition:

• Partitioning along dense dimensions in a transparent partition

can greatly slow performance. The slow performance results
because dense dimensions are used to determine the
structure and contents of data blocks. If a database is
partitioned only along a dense dimension at the target,
Analytic Services must compose data blocks by performing
network calls for the remote data in the transparent partition
 in addition to the disk I/O for the local portion of the block. 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.
• 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.
• Partitioning base dimensions can greatly slow performance.
• For calculation-related performance considerations, see
Performance Considerations for Transparent Partition
Calculations.

Calculating Transparent Partitions

When you perform a calculation on a transparent partition, Analytic
Services performs the calculation using the current values of the local
data and transparent dependents. When calculating local data that
depends on remote data, Analytic Services performs a bottom-up
calculation. The bottom-up calculation can be done only if the
calculator cache on the target database is used properly. For complete
information on bottom-up calculations, see Using Bottom-Up
Calculation. For information on the calculator cache, see Sizing the
Calculator Cache.

Increasing the amount of memory assigned to the calculator cache

greatly improves calculation performance with transparent partitions.
When a calculation is started, a message in the application log
indicates whether or not the calculator cache is enabled or disabled on
the target database. Using the calculator cache on the target database
reduces the number of blocks that are requested from the data source
during calculation. Reducing the blocks requested, in turn, reduces the
amount of network traffic that is generated by transferring blocks
across the network. For information on estimating the size of the
calculator cache, see Sizing the Calculator Cache.

Performance Considerations for Transparent Partition

Calculations
Calculating data on the data target can greatly slow performance when
the data target must retrieve each dependent data block across the
network, and then perform the calculation.

Performance with transparent calculations may also slow if Analytic

Services must perform a top-down calculation on any portion of the
data target that contains top-down member formulas. When the data
target contains no top-down member formulas, Analytic Services can
perform a bottom-up calculation on the data target, which is much
faster.

When Analytic Services performs the calculation on the data source, it

can always perform a bottom-up calculation. For a comparison of top-
down and bottom-up calculations, see Using Bottom-Up Calculation.

Consider using these calculation alternatives:

• 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 for batch calculation. Analytic Services
performs the calculation only when users request it.
• A replicated layer between the low-level transparent data and
high-level local data.

Other performance strategies include the following:

• Keep the partition fully within the calculator cache area (see
Sizing the Calculator Cache). Keeping a partition fully within
the calculator cache 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 Analytic Services to use the top-down calculation
method. For more information, see Bottom-Up and Top-Down
Calculation.

Transparent Partitions and Member Formulas

If the data target and data source outlines are identical except for
different member formulas, make sure that the partition definition
produces the desired calculation results.

For example, suppose that the data source and data target outlines
both contain a Market dimension with North and South members, and
children of North and South. On the data target, Market is calculated
from the data for the North and South members (and their children)
on the data source. If any of these members on the data source
contain member formulas, these formulas are calculated, thus
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.

Make sure that any formulas you assign to members in the data source
and data target produce the desired results.

Transparent Partitions and Port Usage

One port is used for every unique user and machine combination. If a
user defines several transparent partitions on one server, using the
same user name, then only one port is occupied.

In a transparent partition, when a user (user1) drills into an area in

the target that accesses source data, user1 is using the user name
declared in the partition definition (partition user) to access the data
from the source database. This process causes the use of an additional
port because different users (user1 and partition user) are connecting
to the application.

If a second user (user2) connects to the target database and drills

down to access source data, user2 also uses the user name declared in
the partition definition (partition user) to access the source database.
Because the partition user is already connected to the source
database, an additional port is not needed for the partition user, as
long as user2 is accessing the same source database.

Linked Partitions
A linked partition connects two different databases with a data cell.
When the end user clicks the linked cell in the data source, you drill
across to a second database, the?data target, and view the data there.
If you are using Spreadsheet Add-in, for example, a new sheet opens
displaying the dimensions in the second database. You can then drill
down into these dimensions.

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 very different
dimensions than the database from which you connected.

To prevent users from seeing privileged data, establish security filters

on both the data source and the data target. For directions on
establishing security filters, see Planning for Security for Partitioned
Databases.

Figure 79: Linked Partition

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, they 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 database administrator can link individual
business unit databases to the corporate database. For an example of
creating a linked partition, see Case Study 3: Linking Two Databases.
A user in such a scenario can perform these tasks:

• 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.
• Drill down in the new spreadsheet to more detailed data.

Figure 80: Source and Target for Linked Partition

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, where users move
from the data target to the data source.

Use a linked partition when you want to connect databases with

different dimensionality.

These sections help you assess the value of linked partitions:

• Advantages and Disadvantages of Linked Partitions

• Drill Across and Linked Partitions
• Linked Partitions and Port Usage

Advantages and Disadvantages of Linked Partitions

Linked partitions allow users to navigate to databases that contain
different dimensions, but linked partitions are not always the ideal
partition type. This section describes the advantages and
disadvantages of using a linked partition.

Advantages of Linked Partitions

Following are the advantages of linked partitions:

• You can view data in a different context; that is, you can
navigate between databases containing many different
dimensions.
• You do not have to 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 more than
one database. 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 Analytic Services is
accessing the database directly and not through a data
target.

Disadvantages of Linked Partitions

Following are the disadvantages of linked partitions:

• You must create an account for users on each database or

default access to the?destination database (such as through a
guest account). For information on creating accounts, see Drill
Across and Linked Partitions.
• Users must access the linked database using Analytic Services
Release 5-aware tools. If you have custom built tools, you
must extend them using the Analytic Services Release 5 Grid
API.

Drill Across and Linked Partitions

When a user clicks on a linked cell in a linked partition, a spreadsheet
opens and displays the linked database. This process is called drill
across. To facilitate drill across access you can use the following
strategies:

• 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 both the Company and East databases.
See Managing Users and Groups.
• 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. Once you have created the account,
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, Analytic Services

logs the user into the data target using the following steps:

1. Checks to see if the user has an account on the data target

with the same name and password. If so, Analytic Services
logs the user in using that account.
2. Checks to see if you have specified a default account on the
data target when you created the partition. If you did,
Analytic Services logs the user in using that account.
3. Opens a login window prompting the user to enter a new login
and password. Once the user enters a valid login and
password, Analytic Services logs the user in using that
account.

Linked Partitions and Port Usage

When accessing a linked partition, Analytic Services tries to use the
end user's (user1) login information to connect to the source database.
If user1 does not have access to the source database, Analytic
Services looks for the linked partition default user name and password.
If these defaults are not specified, user1 is requested to enter login
information to access the source database. Port usage varies
depending on the number of different user names being used to access
the various source and target databases (and whether those databases
are contained within the same or different servers).

Choosing a Partition Type

The following table should help you choose which type of partition to
use.

Feature Replicated Transparent Linked

Up-to-the-minute data x x

Reduced network traffic x x

Reduced disk space x x

Increased calculation speed x

Smaller databases x x

Improved query speed x x

Invisible to end users x x

Access to databases with x

different dimensionality

Easier to recover x

Less synchronization x
required

Ability to query data based x x

on its attributes

Ability to use front-end x x

tools that are not
Distributed OLAP-aware

Easy to perform frequent x

updates and calculations

Ability to update data at the x x

data target

View data in a different x

context

Perform batch updates and x

simple aggregations
Planning for Security
for Partitioned
Databases
Users accessing replicated, transparent, or linked partitions may need
to view data stored in two or more databases. The following sections
describe how to set up security so that users do not view or change
inappropriate data.

Process for Setting up End User Security

Create the required end users with the correct filters.

1. Create accounts for users at the data target.

See Managing Users and Groups.
2. Create read and write filters at the data target to determine
what end users can view and update.
See Managing Security for Users and Applications.
3. If you are creating a replicated partition, determine whether
users can make changes to a replicated partition at the data
target. This setting overrides user filters that allow users to
update data.
See the Essbase XTD 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 two or more databases.
See Drill Across and Linked Partitions.

Process for Setting up Administrator Security

The administrative account performs all read and write operations
requested by the data target for the data source. For example, when
end users request data at the data target, the administrative account
retrieves the data. When end users update data at the data target, the
administrative account logs into the data source and updates the data
there.

You can create filters on the administrative account in addition to

filters 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 various 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 both the data source and

the data target.
See Setting the User Name and Password.
Analytic Services 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 what administrators
can view and update.
See Managing Security for Users and Applications.
o For replicated partitions, set up read filters at the data
source to determine which data Analytic Services reads
when replicating and set up write filters at the data
target to determine which data Analytic Services writes
to when replicating.
o For transparent partitions, set up read filters at the data
source to determine which data Analytic Services
retrieves for end users and set up write filters at the
data source to determine which data Analytic Services
updates for end users.

Case Studies for

Designing Partitioned
Databases
The following sections describe examples of partitioning a database:

• Case Study 1: Partitioning an Existing Database

• Case Study 2: Connecting Existing Related Databases
• Case Study 3: Linking Two Databases

Case Study 1: Partitioning an Existing Database

Assume that TBC, the fictional soft drink company upon which the
Sample Basic database is based, started out with a centralized
database. As the eastern region grew, however, this solution was no
longer feasible. The networks to the eastern region could not handle
the large flow of data. Users were constantly waiting for data that they
needed to make decisions. One day, the network went down and users
at the eastern region could not access the data at all.

Everyone agreed that the eastern region needed to access its own data
directly, without going through the company database. In addition,
TBC decided to change where budgeting information was stored. The
corporate budget stays at company headquarters, but the eastern
region budget moves to the eastern region's database.

So, assume that TBC decided to ask you to partition their large
centralized database into two smaller databases-Company and East.

This example is based on the Samppart application, which contains the

Company database, and the Sampeast application, which contains the
East database. Both are shipped with Analytic Services.

This illustration shows a subset of the partitioned databases. The

arrows indicate flow from the data source to the data target. The
Company database is the data source for the Corp_Budget member
and the data target for the East and the East Actual members. The
East database is the data source for its East and Actual members and
the data target for the Corp_Budget member.
Use this procedure to create a partition based on this example:
1. Determine which data to partition.
The Sample Basic database contains five standard dimensions-
Year, Measures, Product, Market, and Scenario.
o Partition the database along the East member of the
Market dimension to give the eastern region more
control over the contents of its database.
o Partition the database along the Actual and
Corp_Budget members of the Scenario dimension.
2. Choose the data source and the data target.
o For Corp_Budget, use Company as source and East as
Target; because the company owns the corporate
budget, it is the source.
o 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.
3. Decide on the type of partition to use.
o For East, use transparent because the data target
(Company) needs up-to-the-minute data.
o For Corp_Budget, use transparent because the data
target (East) needs up-to-the minute data.
o For East Actual, use replication because the data target
(Company) does not need up-to-the-minute data.
4. Finally, create the partitioned databases by performing the
following tasks.
o Creating the new Sampeast application.
 o Creating the new East database by cutting the Company
outline and pasting it into the East outline. Then delete
the extra members (that is, South, West, and Central)
and promote East.
o If necessary, editing existing data sources, rules files,
calculation scripts, report scripts, and outlines.
o Creating the partitions.
o Loading data into the new partitions.

Now that the corporate database is partitioned, users and database

administrators see the following benefits:

• Faster response times, because they are competing with

fewer users for the data and they are accessing the data
locally.
• Database administrators can control the down time of their
local databases, making them easier to maintain.
• Access to more data-now 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.

Case Study 2: Connecting Existing Related Databases

Assume that TBC has several databases, such as Inventory, Payroll,
Marketing, and Sales. Users viewing the Sample Basic database want
to share data with and navigate to those other databases and you, the
database administrator, want to synchronize related data. It is
impractical to combine all of the databases into one database, for the
following reasons:

• So many users access it that performance is slow.

• You cannot find a down time to administer the database.
• No one has control over their own data, because it is centrally
managed.
• The database is very sparse, because so much of the data is
unrelated.

By connecting the databases instead, you can reap the following

benefits:

• Leverage work that has already been completed.

• Synchronize the data.
So you decide to connect multiple databases.

Note: This example is not shipped with Analytic Services.

1. Determine which data to connect. First, connect the Inventory

database.
o Replicate the Opening_Inventory and Ending_Inventory
members from the Measures dimension of the Inventory
database into the Measures dimension of the Sample
Basic database.
o Do not replicate the Number_On_Hand,
Number_Shipped, and Number_Returned members in
the Measures dimension of the Inventory database to
the Sample Basic database.
o Add a link to the Inventory database so that users can
view these more detailed measures if they need to.
o Create a partition containing data from the Payroll,
Marketing, and Sales databases in the Sample Basic
database.
2. Choose the data source and the data target. In the case of
the Opening_Inventory and Ending_Inventory members, the
Inventory database is the data source and the Sample Basic
database is the data target.
3. Decide on the type of partition to use.
Use a replicated partition for the Opening_Inventory and
Ending_Inventory members because the network connection is
slow.
4. Connect the Payroll, Marketing, and Sales databases. Perform
the tasks in step?1 through step?3 for each database.
5. Finally, create the partitioned databases by performing the
following tasks:
o Editing existing data sources, rules files, calculation
scripts, report scripts, and outlines
o Creating the partitions
o If necessary, loading data into the new partitions

Now that the Sample Basic database is partitioned, users and database
administrators see the following benefits:

• Database administrators can control the down time of their

local databases, making them easier to maintain.
• Access to more data-now users can link to new databases.
 • Higher quality data, because the databases are now
synchronized, that is, they use the same data.

Case Study 3: Linking Two Databases

Assume that TBC, the fictional soft drink company upon which the
Sample Basic database is based, has two main databases-the Sample
Basic database and TBC Demo. Both databases have similar outlines,
but TBC Demo has two additional dimensions, Channel, which
describes where a product is sold, and Package, which describes how
the product is packaged.

The database administrator for the Sample Basic database notices that
more and more users are requesting that she add channel information
to the Sample Basic database. But, since she does not own the data
for channel information, she is reluctant to do so. She decides instead
to allow her users to link to the TBC Demo database which already
contains this information.

Note: This example is not shipped with Analytic Services.

Here are the steps to take:

1. Determine which data to link.

The database administrator decides to link the Product
dimension of the Sample Basic database to the Product
dimension of TBC Demo. Users can then drill across to TBC
Demo and view the Channel and Package information.
2. Choose the data source and the data target. Because users
start at the Sample Basic database, it is considered the data
target. Likewise, because users move to TBC Demo, it is
considered the data source.

Note: This setup is the opposite of replicated and transparent

databases, where users move from the data target to the
data source.

3. Decide on the type of partition to use.

Use a linked partition because the databases have different
dimensionality.
4. Finally, create the partition:
 o Establish a link from the Product member of the Sample
Basic database to the Product dimension of the TBC
Demo database. Remember to map the extra
dimensions from TBC Demo, Channel and Product, to
void in the Sample Basic database. For more
information, see Mapping Data Cubes with Extra
Dimensions.
o Set up a guest account on TBC Demo that gives the
users who connect from the Sample Basic database
permissions to access the Channel and Package
dimensions. For a general discussion on creating
accounts, see Granting Permissions to Users and
Groups. For directions on how to assign accounts to
linked partitions, see Choosing a Partition Type and
Choosing a Partition Type.

Now that the databases are linked, users and database administrators
see the following benefits:

• Users have access to more data than before.

• The database administrator for the Sample Basic database
does not need to maintain the TBC Demo database, all she
needs to do is check the link periodically to make sure that it
still works.

Creating and
Maintaining Partitions
When you build a new partition, each database in the partition uses a
partition definition file to record all information about the partition,
such as its data source and data target and the areas to share. You
must have Database Designer permissions or higher to create a
partition.This chapter contains the following sections that describe how
to create a replicated, transparent, or linked partition:

• Process for Creating Partitions

• Choosing a Partition Type
• Setting up the Data Source and the Data Target
• Defining a Partition Area
• Mapping Members
 • Validating Partitions
• Saving Partitions

Caution: You must design partitions carefully. Hyperion strongly

recommends that you read Designing Partitioned Applications,
before creating partitions.

After you create a partition, you must maintain the partition. This
chapter contains the following sections that describe how to maintain
an existing partition:

• Process for Maintaining Partitions

• Testing Partitions
• Synchronizing Outlines
• Populating or Updating Replicated Partitions
• Editing and Deleting Partitions
• Viewing Partition Information
• Troubleshooting Partitions

Process for Creating

Partitions
Here is the suggested process for creating database partitions.

1. Set the partition type as replicated, transparent, or linked.

See Choosing a Partition Type.
2. Set up the data source and the data target, including
specifying the location of the data source, the location of the
data target, notes to describe each, and the source outline.
See Setting up the Data Source and the Data Target.
3. Set up the administrative account to use to connect the data
source and the data target partitions. See Setting the User
Name and Password.
4. Define the area of the database to partition. See Defining a
Partition Area.
5. If necessary, map the members in the data source to the
members in the data target. See Mapping Members.
6. Validate the partition. See Validating Partitions.
7. Save the partition. See Saving Partitions.
 8. If the partition is replicated, populate the partition. See
Populating or Updating Replicated Partitions.
9. Load and calculate the new database that contains the
partition. Loading and calculating the partition may require
you to change existing rules files and calculation scripts. See
Understanding Data Loading and Dimension Building and
Calculating Analytic Services Databases.

Choosing a Partition Type

When you create a partition, choose one of the following types:

• A replicated partition is a copy of a portion of the data source

that is stored in the data target. For detailed information, see
Replicated Partitions.
• A transparent partition allow users to access data from the
data source as though it?were stored in the data target.
However, the data is stored at the data source, which can be
in another application or in another Analytic Services
database or on another Analytic Server. For detailed
information, see Transparent Partitions.
• A linked partition sends users from a cell in one database to a
cell in another database. A linked partition gives users a
different perspective on the data. For detailed information,
see Linked Partitions.
To choose a partition type, see "Specifying the Partition Type and
Settings" in the Essbase XTD Administration Services Online Help.

Setting up the Data Source and the Data Target

You must set up the data source and the data target, including
specifying their location, entering notes about each one (optional), and
specifying the source outline.

To set up the data source and the data target:

1. Specify the location of the data source.
Specify the names of the Analytic Server, application, and
database to use as the data source. See "Specifying Connection
Information for Partitions" in the Essbase XTD Administration
Services Online Help.
2. Specify the location of the data target.
 Specify the names of the Analytic Server, application, and
database to use as the data target. See "Specifying Connection
Information for Partitions" in the Essbase XTD Administration
Services Online Help.

Note: Do not use network aliases, such as localhost, for the

data source or data target names unless you are certain that
they are propagated to all computers on your system. If
you're not certain, use the full server name. This is especially
important for linked partitions, because this is the host name
that clients connected to the data target use to find the data
source.

3. If desired, enter a note to describe the data source or data

target.
See "Specifying Connection Information for Partitions" in the
Essbase XTD Administration Services Online Help.
4. If desired, specify the outline to which you can make
changes.
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. For more information, see
Synchronizing Outlines.

Setting the User Name and Password

You must specify a user name and password for Analytic Services to
use when communicating between the data source and the data
target. The user name and password must be identical on both the
data source and the data target. Analytic Services uses this user name
and password to:

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

For more information, see Planning for Security for Partitioned

Databases.
 To set the user name and password for the data source and the data
target, see "Specifying Connection Information for Partitions" in the
Essbase XTD Administration Services Online Help.

Defining a Partition Area

You can define or edit the areas of the data source to share with the
data target in a partition. An area is a subcube within a database. For
example, an area could be all Measures at the lowest level for Actual
data in the Eastern region. A partition is composed of one or more
areas.

When you define a replicated area, make sure that both the data
source and data target contain the same number of cells. This verifies
that the two partitions have the same shape. For example, if the area
covers 18 cells in the data source, the data target should contain an
area covering 18 cells into which to put those values. The cell count
does not include the cells of attribute dimensions.

For more information on partition areas, see Determining Which Data

to Partition.

Note: Use member names instead of their aliases to create area

definitions. Although Analytic Services validates the aliases, the
partitions will not work.

To define a partition area, see "Defining Areas in Partitions" in

Essbase XTD Administration Services Online Help.

Mapping Members
To create a partition, Analytic Services must be able to map all shared
data source members to data target members. Hyperion recommends
that data source member names and data target member names are
the same to reduce the maintenance requirements for the partition,
especially when the partition is based on member attributes.

If the data source and the data target contain the same number of
members and use the same member names, Analytic Services
automatically maps the members. You need only validate, save, and
test the partitions, as described in Validating Partitions, Saving
Partitions, and Testing Partitions. If Analytic Services cannot map
automatically, you must map manually.
 Map data source members to data target members in any of the
following ways:
• Enter or select member names in manually.
• Import the member mappings from an external data file.
• Create area-specific mappings.

For more information, see Essbase XTD Administration Services Online

Help.

The following sections provide details about mapping members:

• Mapping Members with Different Names

• Mapping Data Cubes with Extra Dimensions
• Mapping Shared Members
• Importing Member Mappings
• Mapping Attributes Associated with Members
• Creating Advanced Area-Specific Mappings

Mapping Members with Different Names

If the data source outline and data target outline contain different
members or if the members have different names in each outline, you
must map the data source members to the data target members. In
the following example, the first two member names are identical, but
the third member name is different:

Source Target
Product  Product 
???Cola ???Cola
Year  Year 
???1998 ???1998
Market  Market 
???East ???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.
Mapping Data Cubes with Extra Dimensions
The number of dimensions in the data source and data target may
vary. The following example illustrates a case where there are more
dimensions in the data source outline than in the data target outline:

Source Target
Product  Product 
???Cola ???Cola
Market  Market 
???East ???East
Year 
???1999 
???1998 
???1997

If you want to map member 1997 of the Year dimension from the data
source to the data target, you can map it to Void in the data target.
But first, you must define the areas of the data source to share with
the data target:

Source Target
@DESCENDANTS(Market), 1997 @DESCENDANTS(Market)

You can then map the data source member to Void in the data target:

Source Target
1997 Void

"Void" is displayed automatically; entering "Void" yourself may cause

errors.

If you do not include at least one member from the extra dimension in
the area definition, you will receive an error message when you
attempt to validate the partition.

Note: When you map a member from an extra dimension, the

partition results reflect data only 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, then 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 Target
Product  Product 
???Cola ???Cola
Market 
???East
Year  Year 
???1997 ???1997

In such cases, you must first define the shared areas of the data
source and the data target:

Source Target
@IDESCENDANTS(Product) @IDESCENDANTS(Product), East

You can then map member East from the Market dimension of the data
target to Void in the data source:

Source Target
Void 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.

Mapping Shared Members

When you create a replicated or transparent partition using a shared
member, use the real member names in the mapping. Analytic
Services maps the real member, not the shared one, from the data
source.
Importing Member Mappings
You can import member mappings from a text file. Mapping files must
end in .txt. A sample member file must contain all of the following
(except extra columns):

Figure 81: Member Mapping Import File

• Data target members column-lists the member names in the

data target. Member names containing spaces must be in
quotes.
• Data source members column-lists the member names in the
data source. Member names containing spaces must be in
quotes.
• Non-member column-missing members. Use when you are
mapping an extra member in the data source to Void in the
data target or vice versa.
• Separators-separate the columns. Separators can be tabs or
spaces.
• Extra column-the file can contain extra columns that do not
contain member names.

Mapping Attributes Associated with Members

You must accurately map attribute dimensions and members from the
data source to the data target to ensure that the partition is valid.

Note: You cannot map members of attributes dimension in

replicated partitions. For more information, refer to Rules for
Replicated Partitions. You can, however, map attributes in
transparent and linked partitions. For information on using
attributes in partitions, see Attributes in Partitions.

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 Target
@DESCENDANTS(100) @DESCENDANTS(200)
@DESCENDANTS(East) @DESCENDANTS(East)

Then map attributes as follows:

Source Target
100­10 200­10
100­20 200­20
100­30 200­30
Caffeinated With Caffeine
Caffeinated_True With_Caffeine_True
Caffeinated_False With_Caffeine_No

If you map attribute Caffeinated_True to attribute With_Caffeine_No,

you receive an error message during validation. You must associate
caffeinated cola from the data source to caffeinated cola in the data
target.

There can be instances where an attribute dimension or an attribute

member exists in the outline of the data source but not in the outline
of the data target, or vice versa. For example:

Source Target
Caffeinated 
???True 
???False

In such cases, you have the following choices:

• 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 Working with

Attributes. For a general discussion of attributes in partitions, see
Attributes in Partitions.

Creating Advanced Area-Specific Mappings

If you can map all of the members in your data source to their
counterparts in the data target using standard member mapping, then
you don't need to perform advanced area-specific mapping.

If, however, you need to control how Analytic Services maps members
at a more granular level, you may need to use area-specific mapping.
Area-specific mapping maps members in one area to members in
another area only in the context of a particular area map.

Use area-to-area mapping when you want to:

• Map data differently depending on where it is coming from.

• Map more than one member in the data source to a single
member in the data target.

Since Analytic Services 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 area-specific mapping to map the members.

Example 1: Advanced Area-Specific Mapping

The data source and data target contain the following dimensions and
members:
Source Target
Product  Product 
???Cola ???Cola
Market  Market 
???East ???East
Year  Year 
???1998  ???1998 
???1999 ???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, then 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. You must 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 must also map these members to Void in the data target.

Example 2: Advanced Area-Specific Mapping

You can also use advanced area-specific mapping if the data source
and data target are structured very differently but contain the same
kind of information.

This strategy works, for example, if your data source and data target
contain the following dimensions and members:

Source Target
Market  Customer_Planning 
???NY  ???NY_Actual 
???CA ???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, then 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. You must define the area
(NY and Actual, and NY_Actual) and then create area-specific 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 that it is accurate
before you use it. In order to validate a partition, you must have
Database Designer permissions or higher. After you validate, save the
partition definition. If necessary, you can edit an existing partition.

When Analytic Services validates a partition definition, it checks on the

Analytic Server for the data source and the data target to ensure that:

• The area definition is valid (contains no syntax errors).

• 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; a transparent
 target does not overlap with a transparent target; and a
replication 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.
• 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.
Analytic Services does not display an error message when
results are incomplete.

After you validate, save the partition. When you save a partition, the
partition definition is saved to two different .ddb files, on both the data
source server and the data target server.

To validate a partition, use any of the following methods:

Tool Topic Location

Administration Validating Partitions Essbase XTD

Services Administration
Services Online
Help

ESSCMD VALIDATEPARTITIONDEFFILE Technical

Reference

MaxL create partition Technical

Reference

Saving Partitions
After you validate the partition definition, you can save the partition
definition to any of the following locations:

• 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
single .ddb file.
To save a partition definition, see "Saving Partitions" in the Essbase
XTD Administration Services Online Help.

Process for Maintaining

Partitions
Here is the suggested process for maintaining database partitions.

1. Test the partition. See Testing Partitions.

2. Synchronize the outlines of the data target and the data
source. See Synchronizing Outlines.
3. Update or populate replicated partitions. See Populating or
Updating Replicated Partitions.
4. Edit or delete existing partitions. See Editing and Deleting
Partitions.
5. Viewing information about existing partitions. See Viewing
Partition Information.
6. Troubleshoot partitions. See Troubleshooting Partitions.

Testing Partitions
To test a partition:

• View data targets using the Spreadsheet Add-in or other tool

to make sure that the user sees the correct data.
• When testing a linked partition, make sure that Analytic
Services links you to the expected database and that the
default user name and password work correctly.

Synchronizing Outlines
When you partition a database, Analytic Services 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, Analytic Services 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 of the outlines, the two outlines are no
longer synchronized. Although Analytic Services does try to make
whatever changes it can to replicated and transparent partitions when
the outlines are not synchronized, Analytic Services may not be able to
make the data in the data source available in the data target.

However, Analytic Services tracks changes that you make to your

outlines and provides tools to make it easy to keep your outlines
synchronized.

This section describes Analytic Services synchronizes outlines.

• Setting the Source Outline and the Target Outline

• Performing Outline Synchronization
• Tracking Changes
• Updating Shared Members During Outline Synchronization

Setting the Source Outline and the Target Outline

Before you can synchronize your outlines, you must determine which
outline is the source outline and which is the target outline.

• The source outline is the outline that outline changes are

taken from.
• The target outline is the outline that outline changes are
applied to.

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, then the default source outline is East.

You can also use the data target outline as the source outline. You
might want to do this 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). This allows the database administrator to make
changes in the Company outline and apply those changes to each
regional outline when she synchronizes the outline.

If you make changes to the:

 • Shared area in the source outline, you can propagate these
changes to the target outline when you synchronize the
outlines.
• 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 Creating and Changing
Database Outlines.

Analytic Services updates as many changes as possible to the target

outline. If Analytic Services 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. For more information, see in Viewing the Analytic Server and
Application Logs.

To set the source outline, see Setting up the Data Source and the
Data Target.

Performing Outline Synchronization

To synchronize outlines, use any of the following methods:

Tool Topic Location

Administration Synchronizing Outlines Essbase XTD

Services Administration
Services Online
Help

MaxL refresh outline Technical

Reference

ESSCMD GETPARTITIONOTLCHANGES Technical

Reference
APPLYOTLCHANGEFILE
RESETOTLCHANGETIME
PURGEOTLCHANGEFILE

Note: For synchronizing non-Unicode-mode outlines with multi-byte

characters, you can use only non-Unicode clients such as ESSCMD
or MaxL statements executed through the MaxL Shell.
Tracking Changes
The following table describes what happens when you change the
source outline and then synchronize the target outline with the source
outline:

Action You
Action Analytic Services Takes
Take

Make 1. Records the changes in a change log

changes to named essxxxx.chg, where xxxxx is the
the source number of the partition. If you have more
outline than one partition on a source outline,
Analytic Services creates a change log for
each partition.
2. Creates or updates the outline change
timestamp for that partition in the .ddb 
file. Each partition defined against the
source outline has a separate timestamp
in the .ddb file.

Pull changes 1. Compares the last updated timestamp in

from the the target outline's .ddb file to the last
outline updated timestamp in the source outline's
source .ddb file. Analytic Services 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, Analytic Services
retrieves those changes from the source
outline's change log and places them in
the target outline's change log. The
change logs may have different names on
the source outline and the target outline.

Select the 1. Applies the changes to the target outline.

changes to 2. Updates the timestamp in the target
apply to the outline's .ddb file, using the time from
target outline the source outline.
Caution: If you choose not to apply some changes, you cannot
apply those changes later.

Updating Shared Members During Outline

Synchronization
An actual member and its shared members in the source outline are
propagated to the target outline if at least one actual or shared
member is defined in the partition area. In illustrated in Figure?82, the
partition definition is @IDESC("Diet"). The parent 100 and its children
(100-10, 100-20, 100-30) are not defined in the partition area. The
parent Diet and its children (100-10, 100-20, 100-30) are defined in
the partition area. The children of Diet are shared members of the
actual members.

Figure 82: Shared Members and Outline Synchronization

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?82, 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, then 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?83, A1 and A2 are in the defined partition area, and A11, A21,
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.

Figure 83: Implied Shared Members and Outline Synchronization

The reverse is true again. If A1 is not defined in the partition area and
its implied shared member is, then any change to A1 is propagated to
the target outline.

Populating or Updating Replicated Partitions

The database administrator should regularly update data in a
replicated partition. How frequently you update replicated partitions
depends on users' requirements for up-to-the-minute data. Analytic
Services keeps track of when the data source was last changed and
when the data target was last updated so that you can determine
when to update replicated partitions. This information is saved at the
data source. Either database administrator-that of the data source site
or that of the data target site-can be responsible for replicating data.

Analytic Services also tracks which cells in a partition are changed. You
can choose to update:

• Just the cells that have changed since the last replication-It is
fastest to update just the cells that have changed.

Note: If you've deleted data blocks on the data source,

Analytic Services 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 by using the
CLEARDATA command in a calculation script; using "Clear
combinations" in your rules file during a data load;?issuing
CLEAR UPPER, CLEAR INPUT or RESETDB commands in
Administration Services; restructuring the database keeping
only level 0 or input data; or deleting sparse members.

• All cells-This is much slower. You may need to update all cells
if you are recovering from a disaster where the data in the
data target has been destroyed or corrupted.

You can replicate:

• All data targets connected to a data source. For example, if

you replicate all data targets connected to the Sampeast East
database, Analytic Services updates the Budget, Actual,
Variance, and Variance % members in the Samppart
Company database:
• From all data sources connected to a data target. For
example, if you replicate from all data sources connected to
the Samppart Company database, Analytic Services pulls the
Budget, Actual, Variance, and Variance % members from the
Sampeast East database and updates them in the Samppart
Company database.
To update a replicated partition, use any of the following methods:

Tool Topic Location

Administration Replicating Data Essbase XTD

Services Administration
Services Online Help
MaxL refresh replicated Technical Reference
partition

ESSCMD GETUPDATEDREPLCELLS Technical Reference

GETALLREPLCELLS
PUTUPDATEDREPLCELLS
PUTALLREPLCELLS

Editing and Deleting Partitions

You can edit and delete existing partitions. When you edit a partition,
you use the same interface that you used to create the partition,
making modifications as necessary.

When you delete a partition, Analytic Services deletes the partition

definition from the .ddb file on the data source and data target
servers.

To edit or delete a partition, see "Opening the Create or Edit Partition

Window" and "Deleting Partitions" in Essbase XTD Administration
Services Online Help.

Viewing Partition Information

To view information about a partition, use any of the following
methods:

Tool Topic Location

Administration Opening the Create or Edit Essbase XTD

Services Partition Window Administration
Services Online
Help

MaxL display partition Technical

Reference

ESSCMD PRINTPARTITIONDEFFILE Technical

Reference
Troubleshooting Partitions
The following table lists common problems that you may encounter
when using partitions.

Symptom Possible Causes Solutions

When replicating The connection Retry the replication

to multiple data between the data operation. If?one
targets, some are source and one of the database is
not replicated. data targets was lost unavailable,
during the replication replicate into just
operation. the databases that
are available.

Not all information The data source and Synchronize outlines

arrived at the data the data target outlines for the data source
target. are no longer and the data target
mappable. and try again.

You keep running Partitions connect to Purchase more

out of ports. other databases using ports.
ports.

When you try to Someone has deleted, Edit the partition

access a partition, renamed, or moved the having problems
you cannot application containing and specify the new
connect to it. the database to which application name or
you are trying to location.
connect.

Partitioned Your host names may Make sure that the

databases can no not match. Did you use host names are
longer connect to the hosts file to synchronized
each other. provide aliases to your between the
local machine? servers.

Analytic Services Users are changing Set the partition to

overwrites user data at a replicated not allow user
edits. partition that you updates or explain
 overwrite each time to users why their
that you update the data disappears.
partition.

Administration Was the target outline Examine the

Services does not changed, but not the partition definition.
reflect outline source outline? Analytic
changes; that is, it Services only
lists the outlines as propagates changes to
being in sync even the source outline.
though one outline Does the outline
has changed. change affect a defined
partition? Analytic
Services does not
propagate changes to
the outline that do not
affect any partitions.

Data is confusing. Your partition may not Check your partition

be set up correctly. to make sure that
you are partitioning
the data that you
need.

Moved members or Moving a dimension If possible, structure

dimensions in the past a dimension that your outline so that
source outline are is not in the partition members and
not reflected may not get dimensions are not
properly in a propagated to the moved across
synchronized target during outline partitions. If this is
target outline. synchronization. Also, not possible, change
moving a member past the target outline to
a member that is not in reflect the source
the partition may not outline moved
get propagated. members or
dimensions.
Accessing Relational
Data with Hybrid
Analysis
Because relational databases can store several terabytes of data, they
offer nearly unlimited scalability. Multidimensional databases are
generally smaller than relational databases but offer sophisticated
analytic capabilities. With Essbase XTD Hybrid Analysis, you can
integrate a relational database with an Essbase XTD Analytic Services
database and thereby leverage the scalability of the relational
database with the conceptual power of the multidimensional database.

Hybrid Analysis eliminates the need to load and store lower-level

members and their data within the Analytic Services database. This
feature gives Analytic Services the ability to operate with almost no
practical limitation on outline size and provides for rapid transfer of
data between Analytic Services databases and relational databases.

This chapter helps you understand Hybrid Analysis and explains how
you can take advantage of its capabilities. The chapter includes the
following topics:

• Understanding Hybrid Analysis

• Defining Hybrid Analysis Relational Sources
• Retrieving Hybrid Analysis Data
• Using Outline Editor with Hybrid Analysis
• Managing Data Consistency
• Managing Security in Hybrid Analysis
• Using Formulas with Hybrid Analysis
• Unsupported Functions in Hybrid Analysis

Understanding Hybrid
Analysis
Hybrid Analysis integrates a relational database with an Analytic
Services multidimensional database so that applications and reporting
tools can directly retrieve data from both databases. Figure?84
illustrates the hybrid analysis architecture:

Figure 84: Hybrid Analysis Architecture

Hybrid Analysis Relational Source

The initial step in setting up Hybrid Analysis is to define the relational
database as a hybrid analysis relational source (1 in Figure?84).

You define the hybrid analysis relational source in Essbase XTD

Integration Services Console. (The individual tasks are discussed in
Defining Hybrid Analysis Relational Sources.) Through Integration
Services Console, you first specify the relational data source for the
OLAP model. The OLAP model is a schema that you create from tables
and columns in the relational database. To build the model, Integration
Services accesses the star schema of the relational database (a in
Figure?84).

Using the model, you define hierarchies and tag levels whose members
are to be enabled for hybrid analysis. You then build the metaoutline, a
template containing the structure and rules for creating the Analytic
Services outline, down to the desired hybrid analysis level. The
information enabling hybrid analysis is stored in the OLAP Metadata
Catalog, which describes the nature, source, location, and type of data
in the hybrid analysis relational source.

Next, you perform a member load which adds dimensions and

members to the Analytic Services outline (b in Figure?84). When the
member load is complete, you run a data load to populate the Analytic
Services database with data (c in Figure?84). At this point, the hybrid
analysis architecture is in place:

• The lower level members and their associated data remain in

the relational database.
• The data in the relational database is mapped to the Analytic
Services outline that is defined by Hybrid Analysis.
• The outline resides in the Analytic Services database.

Metadata is data that describes values within a database. The

metadata that defines the hybrid analysis data resides in both
the Analytic Services outline and in the Integration Services
metaoutline on which the Analytic Services outline is based. Any
changes that are made to hybrid analysis data in an OLAP model
or metaoutline that is associated with an Analytic Services
outline must be updated to the outline to ensure accuracy of the
data reported in Analytic Services. See Managing Data
Consistency for information on keeping data and metadata in
sync.
• Upper level members and their associated data reside in the
Analytic Services database.

Data Retrieval
Applications and reporting tools, such as spreadsheets and Report
Writer interfaces, can directly retrieve data from both databases (2 in
Figure?84). Using the dimension and member structure defined in the
outline, Analytic Services determines the location of a member and
then retrieves data from either the Analytic Services database or the
hybrid analysis relational source. If the data resides in the hybrid
analysis relational source, Analytic Services retrieves the data through
SQL commands. Data retrieval is discussed in Retrieving Hybrid
Analysis Data.

If you want to modify the outline, you can use Outline Editor in
Administration Services to enable?or disable dimensions for hybrid
analysis on an as-needed basis. (3 in Figure?84). For information on
using Outline Editor, see Using Outline Editor with Hybrid Analysis.

Hybrid Analysis Guidelines

Hybrid Analysis has some guidelines with which you should be familiar:

• A single Analytic Services database can be associated with

only one hybrid analysis relational source.
• A hybrid analysis relational source can consist of only one
relational database.
• A hybrid analysis enabled member should not be renamed. If
a member is renamed, the member may not be retrieved the
next time you perform a drill-through operation.
• Hybrid Analysis supports only parent-child prefixing on
member names.
• Hybrid Analysis is not supported on accounts dimensions.
• Hybrid Analysis is not supported on user-defined dimensions.
• Only the lowest level members of a dimension can be enabled
for hybrid analysis.
• Analytic Services does not support aliases for members that
are enabled for hybrid analysis.
• Analytic Services requires the OLAP Metadata Catalog created
in Integration Services in order to drill down in a hybrid
analysis relational source.
• You can perform operations and analyses on dimensions that
have attributes attached to one or more levels in an outline
that is hybrid analysis enabled. The attribute dimension
should be fully loaded into Analytic Services.
• Hybrid Analysis does not support scaling of measures
dimension members using any of the operators + (addition), -
(subtraction), * (multiplication), and / (division). If you use
the scaling operators, drill-through queries into hybrid
analysis data may show a mismatch between aggregated
level-0 values in the Analytic Services database and the
corresponding detail values in your relational data source.
• Analytic Services ignores all member properties, such as
formulas, UDAs, and aliases for members that are enabled for
hybrid analysis.
• Hybrid Analysis does not support the Dynamic Times Series
function.
• Hybrid Analysis does not support transparent, replicated, or
linked partitions.
 • Only the first hierarchy of a dimension with alternate
hierarchies can have members enabled for hybrid analysis on
its lowest levels.
• Hybrid Analysis does not support recursive hierarchies.
• Analytic Services supports drill-through operations defined on
members that are enabled for Hybrid Analysis.
• When building a dimension that is enabled for hybrid analysis,
you must ensure that the column in the relational table that
contributes to the leaf level of the Analytic Services portion of
the dimension is non-nullable.
• You can associate an attribute member with a member
enabled for hybrid analysis.

Defining Hybrid
Analysis Relational
Sources
A hybrid analysis relational source is defined in Integration Services
Console. Detailed information and the specific procedures for
performing the following steps is available in Integration Services
online help.

To define a hybrid analysis relational source, perform the following

steps:
1. Configure one or more relational data sources as described in
the Essbase Integration Services Installation Guide.

Note: If you are using two servers during hybrid analysis, the
Data Source Name (DSN) must be configured on both servers
and the DSN must be the same.

2. Create an OLAP model.

The OLAP model star schema is created from tables and columns
in the relational database. To build the model, Integration
Services accesses the relational databases using the DSNs you
configured in step?1.
 3. In the OLAP model, define the hierarchies that you will use for
hybrid analysis.

Note: You can define any member of any dimension as

enabled for hybrid analysis except members in an accounts
dimension. This restriction is necessary because all members
of an accounts dimension, including lower-level members,
must remain in the Analytic Services database.

4. In the metaoutline, use the Build Multidimensional Down to

Here command to select the level whose members will reside
in the Analytic Services multidimensional database.
5. Use the Enable Hybrid Analysis Down to Here command to
select the member levels that will remain in the relational
database.
6. Run a member load to add dimensions and members to the
outline.
7. Run a data load to populate the Analytic Services database
with data.

Note: For detailed information on the above steps, see the Essbase
XTD Integration Services Console online help.

Retrieving Hybrid
Analysis Data
In Hybrid Analysis, applications and reporting tools can directly
retrieve data from both the relational and the Analytic Services
databases by using the following tools:

• Essbase XTD Spreadsheet Add-in

• Essbase XTD Spreadsheet Services
• Report Writer
• Hyperion Analyzer
• Third-party applications

Note: The Analytic Services database and the relational database

must be registered to the same ODBC data sources, and Integration
Services must use the same source name for both databases.
Because data is being accessed from both the hybrid analysis
relational source and the Analytic Services database when you perform
calculations or generate reports, data retrieval time may increase with
Hybrid Analysis; however, most capabilities of Analytic Services data
retrieval operations are available with Hybrid Analysis, including pivot,
drill-through, and other metadata-based methods.

Retrieving Hybrid Analysis Data with Spreadsheet Add-in

Use the Enable Hybrid Analysis option in the Essbase Options dialog
box in Essbase XTD Spreadsheet Add-in and Essbase XTD Spreadsheet
Services to drill down to members in the hybrid analysis relational
source. Refer to the Essbase XTD Spreadsheet Add-in User's Guide and
to Spreadsheet Add-in online help for more information about these
functions.

Supported Drill-Down Options in Hybrid Analysis

Hybrid Analysis supports the following drill-down options in
Spreadsheet Add-in:

• Next Level (children)

• All Levels (all descendants)
• Bottom Level (level 0)
• All Siblings (all members with common parent)

For best performance, use children, bottom level, or siblings zoom-ins;

avoid using a descendents zoom-in.

Supported Drill-Up Option in Hybrid Analysis

Hybrid Analysis supports the Parent drill-up option in Spreadsheet
Add-in and Spreadsheet Services. However, the drill-up on a relational
member always takes you to the leaf level member in the Analytic
Services outline and not to the immediate parent of the relational
member.

Retrieving Hybrid Analysis Data with Report Writer

In Report Writer, two commands, enable and disable respectively,
Hybrid Analysis:
 • <HYBRIDANALYSISON enables a report script to retrieve the
members of a dimension that is enabled for hybrid analysis.
• <HYBRIDANALYSISOFF prevents a report script from
retrieving the members of a dimension that is enabled for
hybrid analysis.

The <ASYM and <SYM commands are not supported with Hybrid
Analysis. If these commands are present in a report, errors may
result. The <SPARSE command is ignored in reports retrieving data
from a hybrid analysis relational source and does not generate errors.

The following is a sample Report Writer script that uses the

IDESCENDANTS command to return hybrid analysis data:

<PAGE (Accounts, Scenario, Market)
Sales
Actual 
 <Column (Time)
<CHILDREN Time 
 <Row (Product)
<IDESCENDANTS 100­10 
 ! 
 

Retrieving Hybrid Analysis Data with Hyperion Analyzer

When you use Hyperion Analyzer, the procedures for retrieving hybrid
analysis data are the same as the procedures for retrieving data that is
not defined for Hybrid Analysis. (See the Hyperion Analyzer
documentation for detailed information.)

For optimal performance when retrieving hybrid analysis data with

Hyperion Analyzer, keep in mind the following guidelines:

• Always place dimensions that are enabled for Hybrid Analysis

along the rows when constructing queries in Analyzer.
• Do not use any sort options if possible.
• Always use the children operator when drilling down to a
hierarchy; do not use the descendants operator.
• Any additional processing in the form of restrictions or
Top/Bottom retrievals may cause slower query times.
Using Outline Editor
with Hybrid Analysis
In Outline Editor, you can toggle the Hybrid Analysis option button to
enable or disable Hybrid Analysis for each dimension that is defined for
hybrid analysis in Integration Services Console. If you open an outline
that is not defined for hybrid analysis, the Hybrid Analysis option
button is not displayed on the toolbar.

Note: When Hybrid Analysis is disabled for a dimension, the end

user is unable to see and drill-through to the hybrid analysis data
associated with the dimension; however, the members of the
dimension are still visible in Outline Editor.

Figure?85 is an example of how an outline defined for hybrid analysis

appears in Outline Editor. Note that dimensions that are enabled for
hybrid analysis are identified to distinguish them from dimensions that
are not enabled for hybrid analysis.

Figure 85: Example of Hybrid Analysis in Outline Editor

Managing Data
Consistency
When you create a hybrid analysis relational source, the data and
metadata are stored and managed in the relational database and in
the Analytic Services database:

• Lower-level members and their associated data remain in the

relational database.
• Data in the relational database is mapped to the Analytic
Services outline which is defined for hybrid analysis.
• The outline resides in the Analytic Services database.
• Upper-level members and their associated data reside in the
Analytic Services database.

Because data and metadata exist in different locations, information

may become out of sync.

Analytic Services depends upon the OLAP Metadata Catalog in

Integration Services to access the hybrid analysis relational source. At
Analytic Services database startup time, Analytic Server checks the
number of dimensions and members of the Analytic Services outline
against the related metaoutline.

Any changes made to the associated OLAP model or metaoutline

during an Integration Services session are not detected by the Analytic
Server until the Analytic Services database is started again.
Undetected changes can cause data inconsistency between the
Analytic Services database and the hybrid analysis relational source.

If changes are made in the hybrid analysis relational source and

members are added or deleted in the OLAP model or metaoutline, such
changes can cause the Analytic Services outline to be out of sync with
the metaoutline on which it is based. These types of changes and their
effect on the hierarchical structure of a dimension are not reflected in
the Analytic Services database until the outline build and data load
process is completed through Integration Services Console.

In Essbase XTD Administration Services, the Restructure Database

dialog box has a check box that enables a warning whenever a
restructuring affects an outline containing a hybrid analysis relational
source. Such a problem occurs, for example, if members with
relational children are moved or deleted.

Warnings are listed in the application log. You should decide if the
warnings reflect a threat to data consistency. To view the application
log, see Viewing the Analytic Server and Application Logs.
The Analytic Services administrator has the responsibility to ensure
that the Analytic Services multidimensional database, the relational
database, and the Integration Services OLAP model and metaoutline
remain in sync. Both Administration Services and Integration Services
Console provide commands that enable the administrator to perform
consistency checks and make the appropriate updates.

For a comprehensive discussion of maintaining data consistency, see

Ensuring Data Integrity.

For a comprehensive discussion of restructuring a database, see

Optimizing Database Restructuring.

Managing Security in
Hybrid Analysis
The Analytic Services administrator determines access to the hybrid
analysis relational source on an individual Analytic Services user level.
Access for Hybrid Analysis is governed by the same factors that affect
overall Analytic Services security:

• Permissions and access levels for individual users and groups

of users
• Permissions and access levels for the server, application, or
database
• Specific database access levels for particular database
members

If a security filter enables you to view only the relational children of

the level 0 members that you have access to in Analytic Services, then
you cannot view the relational children of the level 0 members that
you do not have access to in Analytic Services.

Assume that you have the following outline, where San Francisco and
San Jose are relational children of California, and Miami and Orlando
are relational children of Florida:
In this example, if a filter allows you to view only level 0 member
California and its descendants, you can view California and its
relational children, San Francisco and San Jose; however, you cannot
view the children of level 0 member Florida.

For detailed information on Analytic Services security, see the following

chapters:

• Managing Security for Users and Applications

• Controlling Access to Database Cells
• Security Examples

Using Formulas with

Hybrid Analysis
Formulas used with members enabled for hybrid analysis are subject
to the following limitations:

• Formulas are supported only on a measures dimension.

• Formulas cannot be attached to relational members.
• Formulas cannot reference a relational member by name.
• Member set functions (such as @CHILDREN and
@DESCENDANTS), which generate member lists in a formula,
execute only in the Analytic Services portion of the outline.

If a formula or member enabled for hybrid analysis contains one or

more functions that are not supported by Hybrid Analysis, Analytic
Services returns the following error message:

Error executing formula for member
[member­name­to­which­formula­is­attached] (line [line# 
where the offending function appears inside the formula): 
function [Name of the offending function] cannot be used in
Hybrid Analysis. 
 

Unsupported Functions
in Hybrid Analysis
Hybrid Analysis does not support all Analytic Services functions. The
following topics specify the categories of significant Analytic Services
functions not supported by Hybrid Analysis.

Relationship Functions
Hybrid Analysis does not support functions that look up specific values
in the database based on current cell location and a series of
parameters. Some examples of these functions are given next.

@ANCEST @SPARENT
@SANCEST @CURLEV
@PARENT @CURGEN

Member Conditions Functions

Hybrid Analysis does not support functions used to specify member
conditions. Some examples of these functions are listed next.

@ISIANCEST @ISLEV
@ISIPARENT @ISSAMEGEN
@ISISIBLING @ISUDA
@ISMBR

Range Functions
Hybrid Analysis does not support functions that use a range of
members as arguments. Rather than return a single value, these
functions calculate a series of values internally based on the range
specified. Some examples of range functions that are not supported
are listed next.

@PRIOR @MOVAVG
@SHIFT @ALLOCATE
@PRIORS @MDALLOCATE
@SHIFTS @VAR
@NEXT @VARPER
@MDSHIFT @MEDIAN
@MOVSUM @RANK

Attribute Functions
Hybrid Analysis does not support any Analytic Services functions that
deal with attributes. Some examples of these functions are listed next.

@ATTRIBUTEVAL
@ATTRIBUTESVAL
@WITHATTR

Current Member and XREF Functions

Hybrid Analysis does not support the following functions used to
determine whether the current member is the member being specified.

@CURRMBR
@XREF

Understanding Data
Loading and Dimension
Building
An Analytic Services database contains dimensions, members, and
data values.
 • You can add data values, that is, numbers, to an Analytic
Services database from a data source, such as a spreadsheet
or a SQL database. This process is called loading data. If the
data source is not perfectly formatted, you need a rules file to
load the data values.
• You can add dimensions and members to an Analytic Services
database manually, by using Outline Editor. You can also load
dimensions and members into a database by using a data
source and a rules file. This process is called building
dimensions.

This chapter describes the components involved in loading data values

and loading dimensions and members-data sources and rules files.
This chapter contains the following sections:

• Process for Data Loading and Dimension Building

• Data Sources
• Rules Files
• Situations That Do and Do Not Need a Rules File
• Data Sources That Do Not Need a Rules File
• Security and Multiple-User Considerations

Process for Data

Loading and Dimension
Building
To load data values or dimensions and members into an Analytic
Services database, follow these steps:

1. Set up the data source.

If you are not using a rules file, you must set up the data source
outside Analytic Services. For information on data sources, see
Data Sources.
2. If necessary, set up the rules file.
For a definition and discussion of rules files, see Rules Files.
3. Perform the data load or dimension build.
 For a comprehensive discussion of how to load data and
members, see Performing and Debugging Data Loads or
Dimension Builds.

Data Sources
Data sources contain the information that you want to load into the
Analytic Services database. A data source can contain data values;
information about members, such as member names, member aliases,
formulas and consolidation properties; generation and level names;
currency name and category; data storage properties; attributes; and
UDAs (user-defined attributes).

The following sections describe the components of any kind of data

source.

• Supported Data Sources

• Items in a Data Source
• Valid Dimension Fields
• Valid Member Fields
• Valid Data Fields
• Valid Delimiters
• Valid Formatting Characters

Supported Data Sources

Analytic Services supports the following types of data sources:

• Text files (flat files) from text backups or external sources.

• SQL data sources (non-Unicode only).
• Analytic Services export files. Export files do not need a rules
file to load.
• Microsoft Excel files with the .XLS extension, Version 4.0 and
higher.
• Microsoft Excel files, Version 5.0 and higher. Load as client
objects or files in the file system.
• Lotus?1-2-3 files with the .WKS, .WK1, .WK3, or .WK4 
extension.
• Spreadsheet audit log files.

Note: If you are using Administration Services Console to load data

or build an outline, spreadsheet files are not supported if the
Administration Server is installed on a computer with a UNIX
operating system.

Items in a Data Source

As illustrated in Figure?86, a data source is composed of records,
fields, and field delimiters. A record is a structured row of related
fields. A field is an individual value. A delimiter indicates that a field is
complete and that the next item in the record is another field.

Analytic Services reads data sources starting at the top and proceeding
from left to right.

Figure 86: Records and Fields

As illustrated in Figure?87, data sources can contain dimension fields,

member fields, member combination fields, and data fields.

Figure 87: Kinds of Fields

• Dimension fields identify the dimensions of the database,

such as Market. Use dimension fields to tell Analytic Services
the order of the dimensions in the data source. In Figure?87,
for example, the dimension fields are Market, Product, Year,
Measures, and Scenario. Fields in the Market 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.
• Member fields identify the members or member combinations
of the specified dimensions. Use member fields to tell Analytic
Services to which members to map new data values, or which
members to add to the outline. In Figure?87, for example,
Texas, 100-10, Jan, Sales, and Actual are all member fields.

Note: While processing each record in a data source for a

data load, Analytic Services does not check to ensure a
member specified in a member field belongs to the dimension
specified for the dimension field. Analytic Services loads the
data value to the data cell identified by the member
combination in the record. In Figure?87, for example, if the
second records reversed Jan and Sales (Texas, '100-10',
Sales, Jan, Actual, 42), Analytic Services would load 42 to the
correct data cell.

• 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?87, 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 Figure?88, for 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.

Figure 88: Assigning Data Fields in Headers

Jan,??ActualCola???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:

• Valid Dimension Fields

• Valid Member Fields
• Valid Data Fields
• Valid Delimiters
 • Valid Formatting Characters

Valid Dimension Fields

In a data load, every dimension in the Analytic Services database must
be specified in the either the data source or the rules file. If the data
source does not identify every dimension in the database, you must
identify the missing dimensions in a rules file. 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 may not be specified in the data sources. You must specify
the month in the data source header or the rules file. For information
on setting header records, see Defining Header Records.

A dimension field must contain a valid dimension name. If you are not
performing a dimension build, the dimension must already exist in the
database. If you are performing a dimension build, the dimension
name can be new, but the new name must be specified in the rules
file.

Valid Member Fields

A member field can contain the name of a valid member or an alias. In
Figure?87, for example, Texas and Ohio are valid members of the
Market dimension. Analytic Services must know how to map each
member field of the data source to a member of the database.

In order to be valid, a member field must meet the following criteria:

• The member field must contain a valid member name or

member property. For a discussion of member properties, see
Using the Data Source to Set Member Properties. 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, make sure
that a member containing spaces, such as "New York," is
surrounded by double quotation marks. If you are performing
a data load without a rules file, member names containing
some other characters must also be surrounded by quotation
marks. For a list of the relevant characters, see Data Sources
That Do Not Need a Rules File.

Valid Data Fields

If you are performing a dimension build, you can skip this section.
Data fields are ignored during a dimension build.

Either the data source or the rules file must contain enough
information for Analytic Services to determine where to put each data
value. A data field contains the data value for its intersection in the
database. In Figure?87, for example, 42 is a data field. It is the dollar
sales of 100-10 (Cola) in Texas in January.

In a data field, Analytic Services accepts numbers and their modifiers,

with no spaces or separators between them, and the text strings #MI
and #MISSING.

Valid Modifiers Examples

Currency symbols: $12 is a valid value.

• Dollar $ $ 12 is not a valid value because there
• Euro is a space between the dollar sign and
• Yen ? the 12.

Parentheses around (12)

numbers to indicate a
negative number

Minus sign before -12

numbers. Minus signs
after numbers are not
valid.

Decimal point 12.3

Large numbers with or Both 1,345,218 and 1345218 are valid

without commas values.

#MI or #MISSING to You must insert #MI or #MISSING into

represent missing or any data field that has no value. If you
unknown values do not, the data source may not load
correctly. For instructions on how to
replace a blank field with #MI or
#MISSING, see Replacing an Empty
Field with Text.

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 Figure?89
into the Sample Basic database, for example, define the last field as a
data field.

Figure 89: Setting Data Fields

Jan    Cola    East    Sales    Actual    100
Feb    Cola    East    Sales    Actual    200 
 
To define a data field, see "Defining a Column as a Data Field" in
Essbase XTD Administration Services Online Help.

If there is no value in the data field (or the value is #MISSING),

Analytic Services does not change the existing data value in the
database. Analytic Services does not replace current values with empty
values.

Note: If the data source contains blank fields for data values,
replace them with #MI or #MISSING. Otherwise, the data may not
load correctly. For instructions on how to replace a blank field with
#MI or #MISSING, see Replacing an Empty Field with Text.

Valid Delimiters
You must separate fields from each other with delimiters. If you are
loading data without a rules file, you must uses spaces to delimit
fields.
If you are using a rules file, delimiters can be any of the following:

• Tabs (Tabs are the default delimiter expected by Analytic

Services.)
• Spaces
• New lines
• Carriage returns
• Commas

Extra Delimiters Without a Rules File

In data sources that are loaded without a rules file, Analytic Services
ignores extra delimiters. In Figure?90, for example, the fields are
separated by spaces. Analytic Services ignores the extra spaces
between the fields.

Figure 90: File Delimiters

East??????Cola???Actual???Jan???Sales???10
East???Cola???Actual???Feb???Sales???21
East???Cola???Actual???Mar???Sales???30
 
 

Extra Delimiters with a Rules File

In data sources that are loaded with a rules file, Analytic Services
reads extra delimiters as empty fields. For example, if you try to use a
rules file to load the file in Figure?91 into the Sample Basic database,
the load fails. Analytic Services reads the extra comma between East
and Cola in the first record as an extra field. Analytic Services then
puts Cola into Field 3. In the next record, however, Cola is in Field 2.
Analytic Services expects Cola to be in Field 3 and stops the data load.

Figure 91: File Delimiters

East,,Cola,Actual,Jan,Sales,10
East,Cola,Actual,Feb,Sales,21
East,Cola,Actual,Mar,Sales,30 
 

To solve the problem, delete the extra delimiter from the data source.
Valid Formatting Characters
Analytic Services views some characters in the data source as
formatting characters only. For that reason, Analytic Services ignores
the following characters:

== Two or more equal signs, such as for double underlining

- - Two or more minus signs, such as for single underlining
_ _ Two or more underscores
== Two or more IBM PC graphic double underlines (ASCII
character 205)
_ _ Two or more IBM PC graphic single underlines (ASCII
character 196)

Ignored fields do not affect the data load or dimension build.

For example, Analytic Services ignores the equal signs in Figure?92

and loads the other fields normally.

Figure 92: Ignoring Formatting Characters During Loading

East?????Actual????"100­10"
?????????Sales?????Marketing
?????????=====?????=========
Jan???????10???????????8
Feb???????21??????????16 
 

Rules Files
Rules are a set of operations that Analytic Services performs on data
values or on dimensions and members when it processes a data
source. Use rules to map data values to an Analytic Services database
or to map dimensions and members to an Analytic Services outline.

Figure 93: Loading Data Sources Through Rules Files

Rules are stored in rules files. A rules file tells Analytic Services which
build method to use, specifies whether data values or members are
sorted or in random order, and tells Analytic Services how to transform
data values or members before loading them. It is best to create a
separate rules file for each dimension.

Analytic Services 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. Analytic Services does not change the data source.
You can re-use 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. Using ESSCMD.

Situations That Do and

Do Not Need a Rules
File
You need a rules file if the data source does not map perfectly to the
database or if you are performing any of the following tasks:

• Loading data from a SQL data source

• Building dimensions
 o Adding new dimensions and members to the database
o Changing existing dimensions and members in the
database
• Changing the data in any way, including the following:
o Ignoring fields or strings in the data source
o Changing the order of fields by moving, joining,
splitting, or creating fields
o Mapping the data in the data source to the database by
changing strings
o 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
o Setting header records for missing values
o Rejecting an invalid record and continuing the data load

You do not need a rules file if you are performing a data load and the
data source maps perfectly to the database. For a description of a data
source that maps perfectly, see Data Sources That Do Not Need a
Rules File.

Note: If you are using a rules file, each record in the rules file must
have the same number of fields. See Dealing with Missing Fields in
a Data Source.

Data Sources That Do

Not Need a Rules File
If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

If a data source contains all information required to load the data

values in it into the database, you can load the data source directly.
This kind of load is called a free-form data load.

To load a data value successfully, Analytic Services must encounter

one member from each dimension before encountering the data value.
For example, in Figure?87, Analytic Services loads the data value 42
into the database with the members Texas, 100-10, Jan, Sales, and
Actual. If Analytic Services encounters a data value before a member
of each dimension is specified, it stops loading the data source.
To map perfectly, a data source must contain all of the following and
nothing other than the following:

• One or more valid members from each dimension. A member

name must be enclosed in quotation marks if it contains any
of the following:
o Spaces
o Numeric characters (0-9)
o Dashes (minus signs, hyphens)
o Plus signs
o & (ampersands)

If you are performing a data load without a rules file, when

Analytic Services encounters an invalid member field, it
stops the data load. Analytic Services loads all fields read
before the invalid field into the database, resulting in a
partial load of the data values. For information on
continuing the load, see Loading Dimension Build and Data
Load Error Logs.
• One or more valid data values. For examples of valid values,
see Valid Data Fields.
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.
• Valid delimiters. For a list of valid delimiters, see Valid
Delimiters.

The fields in the data source must be formatted in an order that

Analytic Services understands. The simplest way to format a record is
to include a member from each dimension and a data field, as
illustrated in Figure?94:

Figure 94: Sample Free-Form Data Source

Sales "100­10" Ohio Jan Actual 25
Sales "100­20" Ohio Jan Actual 25
Sales "100­30" Ohio Jan Actual 25 

If the data source is not correctly formatted, it will not load. You can
edit the data source using a text editor and fix the problem. If you find
that you must perform many edits (such as moving several fields and
records), it might be easier to use a rules file to load the data source.
For a definition and discussion of rules files, see Rules Files.
The following sections describe more complicated ways to format free-
form data sources:

• Formatting Ranges of Member Fields

• Formatting Columns

Formatting Ranges of Member Fields

If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

You can express member names as ranges within a dimension. For

example, Sales and COGS form a range in the Measures dimension.
Ranges of member names can handle a series of values.

A data source can contain ranges from more than one dimension at a
time.

In Figure?95, for example, Jan and Feb form a range in the Year
dimension and Sales and COGS form a range in the Measures
dimension.

Figure 95: Multiple Ranges of Member Names

Actual Texas ?????Sales????????COGS
????????????????Jan????Feb????Jan???Feb
"100­10"????????98?????89?????26????19
"100­20"????????87?????78?????23????32
 
 

In Figure?95, Sales is defined for the first two columns and COGS for
the last two columns.

The following sections describe additional types of ranges:

• Setting Ranges Automatically

• Handling Out of Range Data Values
• Interpreting Duplicate Members in a Range
• Reading Multiple Ranges
Setting Ranges Automatically
If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

When Analytic Services encounters two or more members from the

same dimension with no intervening data fields, it sets up a range for
that dimension. The range stays in effect until Analytic Services
encounters another member name from the same dimension, at which
point Analytic Services replaces the range with the new member or
new member range.

Figure?96, for example, contains a range of Jan to Feb in the Year

dimension. It remains in effect until Analytic Services encounters
another member name, such as Mar. When Analytic Services
encounters Mar, the range changes to Jan, Feb, Mar.

Figure 96: Ranges of Member Names

Texas Sales
????????????????????Jan???Feb???Mar
Actual????"100­10"??98????89????58
??????????"100­20"??87????78????115 
 

Handling Out of Range Data Values

If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

When Analytic Services encounters a member range, it assumes that

there is a corresponding range of data values. If the data values are
not in the member range, the data load stops. Analytic Services loads
any data fields read before the invalid field into the database, resulting
in a partial load of the data.

Figure?97, for example, contains more data fields than member fields
in the defined range of members. The data load stops when it reaches
the 10 data field. Analytic Services loads the 100 and 120 data fields
into the database.
Figure 97: Extra Data Values

Cola ???Actual???East
??????????Jan????Feb
Sales?????100????120????10
COGS??????30?????34?????32 
 

For information on restarting the load, see Loading Dimension Build

and Data Load Error Logs.

Interpreting Duplicate Members in a Range

If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

Be sure to structure ranges in the source data so that Analytic Services

interprets them correctly. If the a member appears more than once in
a range, Analytic Services ignores the duplicates.

The file in Figure?98 contains two ranges: Actual to Budget and Sales
to COGS. It also contains duplicate members.

Figure 98: Duplicate Members in a Range

Cola East
        Actual    Budget    Actual    Budget
        Sales     Sales     COGS      COGS
Jan     108       110       49        50
Feb     102       120       57        60 
 

Analytic Services ignores the duplicate members. The members that

Analytic Services ignores have a line through them in the following
example:

Figure 99: Ignored Duplicate Members

Cola East
        Actual    Budget    Actual    Budget
        Sales     Sales     COGS      COGS
Jan     108       110       49        50
Feb     102       120       57        60 
 

For Actual, the first member of the first range, Analytic Services maps
data values to each member of the second range (Sales and COGS).
Analytic Services then proceeds to the next value of the first range,
Budget, similarly mapping values to each member of the second
range. As a result, Analytic Services interprets the file as shown in
Figure?100.

Figure 100: How Analytic Services Interprets the File in Figure?98

Cola East
           Actual            Budget
           Sales     COGS    Sales    COGS
Jan        108       110     49       50
Feb        102       120     57       60 
 

Reading Multiple Ranges

If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

As Analytic Services scans a file, it processes the most recently

encountered range first when identifying a range of data values. In
Figure?100, for example, there are two ranges: Actual and Budget and
Sales and COGS. While reading the file from left to right and top to
bottom, Analytic Services encounters the Actual and Budget range first
and the Sales and COGS range second. Because the Sales and COGS
range is encountered second, Analytic Services puts data fields in the
Sales and COGS part of the database first.
Formatting Columns
If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

Files can contain columns of fields. Columns can be symmetric or

asymmetric. Symmetric columns have the same number of members
under them. Asymmetric columns have different numbers of members
under them. Analytic Services supports loading data from both types
of columns.

Symmetric Columns
If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

Symmetric columns have the same number of members under them.

In Figure?101, for 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).

Figure 101: Symmetric Columns

Product????Measures????Market????Year????Scenario
"100­10"???Sales???????Texas?????Jan?????Actual??????112
"100­10"???Sales???????Ohio??????Jan?????Actual??????145 
 

The columns in the following file are also symmetric, because Jan and
Feb have the same number of members under them:

Figure 102: Groups of Symmetric Columns

                              Jan           Feb
                        Actual  Budget  Actual  Budget
"100­10"  Sales  Texas  112     110     243     215
"100­10"  Sales  Ohio   145     120     81      102 
 
Asymmetric Columns
If you are performing a dimension build, skip this section. You cannot
perform a dimension build without a rules file.

Columns can also be asymmetric. In Figure?103, the Jan and Feb

columns are asymmetric because Jan has two columns under it (Actual
and Budget) and Feb has only one column under it (Budget):

Figure 103: Valid Groups of Asymmetric Columns

                         Jan     Jan     Feb
                         Actual  Budget  Budget
"100­10"  Sales  Texas   112     110      243
"100­10"  Sales  Ohio    145     120      81 
 

If a file contains asymmetric columns, you must label each column

with the appropriate member name.

The file in Figure?104, for example, is not valid because the column
labels are incomplete. The Jan label must appear over both the Actual
and Budget columns.

Figure 104: Invalid Asymmetric Columns

                         Jan             Feb
                         Actual  Budget  Budget
"100­10"  Sales  Texas   112     110     243
"100­10"  Sales  Ohio    145     120     81 
 

This file in Figure?105 is valid because the Jan label is now over both
Actual and Budget. It is clear to Analytic Services that both of those
columns map to Jan.

Figure 105: Valid Asymmetric Columns

                         Jan     Jan     Feb
                         Actual  Budget  Budget
"100­10"  Sales  Texas   112     110      243
"100­10"  Sales  Ohio    145     120      81 
 

Security and Multiple-

User Considerations
Analytic Services supports concurrent multiple users reading and
updating the database. Thus, users can use the database while you are
dynamically building dimensions, loading data, or calculating the
database. In a multi-user environment, Analytic Services protects data
by using the security system described in Managing Security for Users
and Applications.

• 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.
• Multi-User Data Load Issues

You can load data values while multiple users are connected to a
database. Analytic Services uses a block locking scheme for
handling multi-user issues. When you load data values, Analytic
Services does the following:
o Locks the block it is loading into so that no one can
write to the block.
See Ensuring Data Integrity for information on Analytic
Services transaction settings, such as identifying whether
other users get read-only access to the locked block or
noting how long Analytic Services waits for a locked block
to be released.
o Updates the block.

See Data Locks for information on whether Analytic

Services unlocks a block when its update is complete or
 waits for the entire data load to complete before unlocking
the block.
• Multi-User Dimension Build Issues

You cannot build dimensions while other users are reading or

writing to the database. After you build dimensions, Analytic
Services restructures the outline and locks the database for the
duration of the restructure operation.

Creating Rules Files

A rules files tells Analytic Services what changes to make to the data
source and outline during a data load or dimension build. For a
definition and discussion of rules files, see Rules Files. This chapter
describes how to create a rules file for data loading or dimension
building:

• Understanding the Process for Creating Data Load Rules Files

• Understanding the Process for Creating Dimension Build Rules
Files
• Combining Data Load and Dimension Build Rules Files
• Creating Rules Files
• Setting File Delimiters
• Naming New Dimensions
• Selecting a Build Method
• Setting and Changing Member and Dimension Properties
• Performing Operations on Records, Fields, and Data
• Setting Field Type Information
• Validating and Saving

For a comprehensive discussion of performing a data load or dimension

build after you create a rules file, see Performing and Debugging Data
Loads or Dimension Builds.
Understanding the
Process for Creating
Data Load Rules Files
To create a data load rules file, follow these steps:

1. Determine whether to use the same rules file for data loading
and dimension building.
For a discussion of factors that influence your decision, see
Combining Data Load and Dimension Build Rules Files.
2. Create a new rules file.
For a process map, see Creating Rules Files.
3. Set the file delimiters for the data source.
For a description of file delimiters, see Setting File Delimiters.
4. If necessary, set record, field, and data operations to change
the data in the data source during loading.
For a comprehensive discussion, see Using a Rules File to
Perform Operations on Records, Fields, and Data.
5. Validate and save the rules file.
For references for pertinent topics, see Validating and Saving.

For a comprehensive discussion of data sources and rules files, see

Understanding Data Loading and Dimension Building.

Understanding the
Process for Creating
Dimension Build Rules
Files
To create a dimension build rules file, follow these steps:

1. Determine whether to use the same rules file for data loading
and dimension building.
For a discussion of factors that influence your decision, see
Combining Data Load and Dimension Build Rules Files.
2. Create a new rules file.
For a process map, see Creating Rules Files.
3. Set the file delimiters for the data source.
For a description of file delimiters, see Setting File Delimiters.
4. If you are creating a new dimension, name the dimension.
For references to pertinent topics, see Naming New Dimensions.
5. Select the build method.
For references to pertinent topics, see Selecting a Build Method.
6. If necessary, change or set the properties of members and
dimensions you are building.
For references to pertinent topics, see Setting and Changing
Member and Dimension Properties.
7. If necessary, set record and field operations to change the
members in the data source during loading.
For a comprehensive discussion, see Using a Rules File to
Perform Operations on Records, Fields, and Data.
8. Set field type information, including field type, field number,
and dimension.
For references to pertinent topics, see Setting Field Type
Information.
9. Validate and save the rules file.
 For references to pertinent topics, see Validating and Saving.

For a comprehensive discussion of data sources and rules files, see

Understanding Data Loading and Dimension Building.

Combining Data Load

and Dimension Build
Rules Files
Before you start building a rules file, you should determine whether to
use that rules file for both data load and dimension build. Once you
create a rules file, you cannot separate it into two rules files. Likewise,
once you create two rules files, you cannot merge them into one rules
file.

Use the same rules file for both data load and dimension build if you
wish to load the data source and build new dimensions at the same
time.

Use separate rules files for data load and dimension build under any of
the following circumstances:

• To build an outline from scratch

• To perform different field operations during the data load and
dimension build
• To re-use the data load or dimension build rules file
separately
• To use data sources that contain no data values, only
dimensions

Creating Rules Files

To create a new rules file:

1. If you are creating the rules file on the Analytic Server,

connect to the server. If you are creating the rules file on the
client, you do not need to connect to the Analytic Server.
 2. Open Data Prep Editor.
For references to pertinent topics, see Opening Data Prep Editor.
3. Open the data source.
For a brief discussion and for references to pertinent topics, see
Opening a Data Source.

Opening Data Prep Editor

You can open Data Prep Editor with a new or existing rules file. After
you open Data Prep Editor, be sure to put the editor in the correct
mode.

To open Data Prep Editor, see "Creating a Rules File" or "Opening an

Existing Rules File" in the Essbase XTD Administration Services Online
Help.
To learn how to use Data Prep Editor, see "About Data Prep Editor" in
the Essbase XTD Administration Services Online Help.

Opening a Data Source

After you open Data Prep Editor, you can open data sources, such as
text files, spreadsheet files, and SQL data sources. The data source
appears in Data Prep Editor so that you can see what needs to be
changed.

You can open a SQL data source only if you have licensed Essbase SQL
Interface. The Essbase SQL Interface Guide provides information on
supported environments, installation, and connection to supported
data sources. Contact your Analytic Services administrator for more
information. When you open a SQL data source, the rules fields default
to the column names of the SQL data source. If the names are not the
same as the Analytic Services dimension names, you need to map the
fields to the dimensions. For a comprehensive discussion of mapping,
see Changing Field Names.

To open text files and spreadsheet files, see "Opening a Data File" in
the Essbase XTD Administration Services Online Help.
To open SQL data sources, see "Opening a SQL Data Source" in the
Essbase XTD Administration Services Online Help.
Setting File Delimiters
A file delimiter is the character (or characters) used to separate fields
in the data source. By default, a rules file expects fields to be
separated by tabs. You can set the file delimiter expected to be a
comma, tab, space, fixed-width column, or custom value. Acceptable
custom values are characters in the standard ASCII character set,
numbered from 0 through 127. Usually, setting the file delimiters is the
first thing you do after opening a data source.

Note: You do not need to set file delimiters for SQL data.

To set file delimiters, see "Setting File Delimiters" in the Essbase

XTD Administration Services Online Help.

Naming New
Dimensions
If you are not creating a new dimension in the rules file, skip this
section.

If you are creating a new dimension, you must name it in the rules file.
Before choosing a dimension name, see Understanding the Rules for
Naming Dimensions and Members.

If you are creating an attribute dimension, the base dimension must

be a sparse dimension already defined in either the outline or the rules
file. For a comprehensive discussion of attribute dimensions, see
Working with Attributes.

To name a new dimension, see "Naming a Dimension" in the Essbase

XTD Administration Services Online Help.
Selecting a Build
Method
If you are not performing a dimension build, skip this section.

If you are building a new dimension or adding members to an existing

dimension, you must tell Analytic Services what algorithm, or build
method, to use. You must specify a build method for each dimension
that you are creating or modifying. For information about each build
method, see Table?22.

To select a build method, see "Choosing a Build Method" in the

Essbase XTD Administration Services Online Help.

Setting and Changing

Member and Dimension
Properties
If you are not performing a dimension build, skip this section.

If you are performing a dimension build, you can set or change the
properties of the members and dimensions in the outline. Some
changes affect all members of the selected dimension, some affect
only the selected dimension, and some affect all dimensions in the
rules file.

You can set or change member and dimension properties using the
Data Prep Editor or a change the member properties in the data
source.
Using the Data Prep Editor to Set Dimension and Member
Properties
To set dimension properties, see "Setting Dimension Properties" in
the Essbase XTD Administration Services Online Help.
To set member properties, see Setting Member Properties in the
Essbase XTD Administration Services Online Help.

Using the Data Source to Set Member Properties

You can modify the properties of both new and existing members
during a dimension build by including member properties in a field in
the data source. 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:
2. Margin%  Margin%  ~ N Sales
3. Set the field type for the properties fields to Property. For a
brief discussion and pertinent references, see Setting Field
Type Information.

The following table lists all member codes used to assign properties to
members in the data source.

Code Description

% Express as a percentage of the current total in a

consolidation

* Multiply by the current total in a consolidation

+ Add to the current total in a consolidation

- Subtract from the current total in a consolidation

/ Divide by the current total in a consolidation

~ Exclude from the consolidation

A Treat as an average time balance item (applies to

accounts dimensions only)

B Exclude data values of zero or #MISSING in the time

balance (applies to accounts dimensions only)

E Treat as an expense item (applies to accounts dimensions

only)

F Treat as a first time balance item (applies to accounts

dimensions only)

L Treat as a last time balance item (applies to accounts

dimensions only)

M Exclude data values of #MISSING from the time balance

(applies?to?accounts dimensions only)

N Never allow data sharing

O Tag as label only (store no data)

S Set member as stored member (non-Dynamic Calc and

not label only)

T Require a two-pass calculation (applies to accounts

dimensions only)

V Create as Dynamic Calc and Store

X Create as Dynamic Calc

Z Exclude data values of zero from the time balance

(applies to accounts dimensions only)
Performing Operations
on Records, Fields, and
Data
In a rules file you can perform operations on records, fields, and data
values before loading them into the database. The data source is not
changed.

For a comprehensive discussion, see Using a Rules File to Perform

Operations on Records, Fields, and Data.

Setting Field Type

Information
If you are not performing a dimension build, skip this section.

In a dimension build, each field in the data source is part of a column

that describes a member in the outline. Fields can contain information
about member names, member properties, or attribute associations.
In order for Analytic Services to process this information, you must
specify the field type in the rules file. You must specify the following
information when setting field types:

• The type of field to expect in that column, such as a

generation field or an alias field. The field type to choose
depends on the data source and the build method. See
Understanding Build Methods.
• The dimension to which the members of that column belong.
See List of Field Types, Rules for Field Types and Using the
Data Source to Set Member Properties.
• The generation or level number of the members of that
column.

The following sections contain detailed information about field types:

 • List of Field Types
• Rules for Field Types
• Using the Data Source to Set Member Properties
To set field information, see "Setting Field Types" in the Essbase XTD
Administration Services Online Help.

List of Field Types

Table?20 lists valid field types for each build method.

Table 20: Field Types ?

Valid Build
Field Type What the Field Contains
Methods
Alias An alias Generation,
level, and
Note: If the Member update parent-child
dimension build setting is set to references
Remove unspecified and the
data source for a new member
contains the alias value of a
removed member, the alias
value will not be assigned to the
new member.

Property A member property. For a list of

properties to set in the data
source, see Using the Data
Source to Set Member
Properties.

Formula A formula

Currency A currency name

name

Currency A currency category

category

UDA A UDA (user-defined attribute)

Attribute In an attribute dimension, the

parent name of the parent member of
the attribute member in the
following field

The name of a A member of the specified

specific attribute dimension. This
attribute member will be associated with
dimension a specified generation or level of
the selected base dimension.
Generation The name of a member in the Generation
specified generation references

Duplicate The name of a member that has

generation duplicate parents; that is, a
member that is shared by more
than one parent

Duplicate The alias for the shared member

generation
alias

Level The name of a member in a Level

level references

Duplicate level The name of a member that has

duplicate parents; that is, a
member that is shared by more
than one parent

Duplicate level The alias for the shared member

alias

Parent The name of a parent Parent-child

reference
Child The name of a child

Rules for Field Types

The field type that you choose for a field depends on the build method
that you selected. Table?21 lists the rules for selecting valid field
types, depending on the build method. If necessary, move the fields to
the required locations. For a brief discussion, see Moving Fields.

To move fields, see "Moving Fields" in the Essbase XTD

Administration Services Online Help.

Table 21: Field Numbers

Build Rules for Assigning Field Types
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.
• Put DUPGEN fields immediately after GEN fields.
• Put DUPGENALIAS fields immediately after
DUPGEN fields.
• Group GEN fields sequentially within a dimension;
for example:
GEN2,PRODUCT???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 second generation
member of the Population dimension.

Level • Put DUPLEVEL fields immediately after LEVEL

fields.
• Put DUPLEVELALIAS fields immediately after the
DUPLEVEL fields.
• Each record must contain a level 0 member. If a
level 0 member is repeated on a new record with a
different parent, Analytic Services rejects the
record unless you select the Allow Moves member
property. To set member properties, see Setting
Member Properties in the Essbase XTD
Administration Services Online Help.
• Group level fields sequentially within a dimension.
• Put the fields for each roll-up in sequential order.
 • Use a single record to describe the primary and
secondary roll-ups.
• 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???UNCES3,PRODUCT???LEVEL2,PRODU
CT

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

Parent- If field type is parent or child, enter 0 (zero) in the Number

child text box.

Attribute The generation or level number must correspond to the

dimension generation or level of the associated base member in the
name 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.

Validating and Saving

Rules files are validated to make sure that the members and
dimensions in the rules file map to the outline. Validation cannot
ensure that the data source loads properly.

To validate a rules file, see "Validating a Rules File" in the Essbase

XTD Administration Services Online Help.
To save a rules file, see "Saving a Rules File" in the Essbase XTD
Administration Services Online Help.
If the rules file is not valid, complete one of the following actions:

• If you are validating a data load rules file, see Requirements

for Valid Data Load Rules Files.
• If you are validating a dimension build rules file, see
Requirements for Valid Dimension Build Rules Files.

If the rules file is correct, you can perform a data load or dimension
build. For a comprehensive discussion of how to load data and
members, see Performing and Debugging Data Loads or Dimension
Builds.

Requirements for Valid Data Load Rules Files

For a data load rules file to validate, all the following questions must
be answered "yes."

• Is the rules file associated with the correct outline? For

information on associating rules files with outlines, see
"Validating a Rules File" in the Essbase XTD Administration
Services Online Help.
• Does each record in the data source contain only one member
from each dimension? For a brief discussion, see Items in a
Data Source.
• Are all member and dimension names spelled correctly?
• Are all members surrounded by quotation marks if they
contain numbers or file delimiters? For a description of
member names that require quotation marks, see Valid
Member Fields.
• Are there no extra delimiters in the data source? For a
discussion of the problems created by extra delimiters, see
Extra Delimiters with a Rules File.
• Is the member that to which each data field maps spelled
correctly in the rules file? For information on mapping data
fields, see Changing Field Names.
• Are the file delimiters correctly placed? For a discussion of the
placement of delimiters, see Valid Delimiters.
• Is the member in the field name a valid member? For
information on setting field names, see Mapping Fields.
• Is the dimension name used in only a single field, that is, not
in a field name and the header? You can map a single data
value to only one set of members.
 • Is only one field defined as a data field? For a brief discussion
and a reference to instructions, see Defining a Column as a
Data Field.
• Is the UDA used for sign flipping in the associated outline? For
a brief discussion, see Flipping Field Signs.

Requirements for Valid Dimension Build Rules Files

For a dimension build rules file to validate, all of the following
questions must be answered "yes."

• Is the rules file associated with the correct outline? For

information on associating rules files with outlines, see
"Validating a Rules File" in the Essbase XTD Administration
Services Online Help.
• Does each record contain only one member from each
dimension? For a brief discussion, see Items in a Data Source.
• Are all member and dimension names spelled correctly?
• Are all members surrounded by quotation marks if they
contain numbers or file delimiters? For a description of
member names that require quotation marks, see Valid
Member Fields.
• Are there no extra delimiters in the data source? For a
discussion of the problems created by extra delimiters, see
Extra Delimiters with a Rules File.
• Are the reference numbers sequential? For a discussion of
limitations and obligations, see Rules for Field Types.
• Are there no repeated generations? For a discussion of
limitations and obligations, see Rules for Field Types.
• Is each field type valid for the build method? See List of Field
Types to identify which field type can be used with which build
methods.
• Are all the fields in correct order? For a review of the rules for
selecting valid field types, see Rules for Field Types.
• Does each child field have a parent field?
• Do all dimension names exist in the outline or the rules file?
• 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. For a
discussion of header records, see Defining Header Records.
Copying Rules Files
You can copy rules files to applications and databases on any Analytic
Server, according to your permissions. You can also copy rules files
across servers as part of application migration.

To copy a rules file, use any of the following methods:

Tool Topic Location

Administration Copying A Rules Essbase XTD Administration

Services File Services Online Help

MaxL alter object Technical Reference

ESSCMD COPYOBJECT Technical Reference

Using a Rules File to

Perform Operations on
Records, Fields, and
Data
This chapter describes how to edit a rules file to perform operations on
records, fields, and data before loading the database. For a
comprehensive discussion of data sources and rules files, see
Understanding Data Loading and Dimension Building. For a
comprehensive discussion of the process of creating a rules file, see
Creating Rules Files.

This chapter contains the following sections about record operations:

• Selecting Records
• Rejecting Records
• Combining Multiple Select and Reject Criteria
 • Setting the Records Displayed
• Defining Header Records

This chapter contains the following sections about field operations:

• Ignoring Fields
• Arranging Fields
• Changing Field Names

This chapter contains the following sections about data operations:

• Defining a Column as a Data Field

• Adding to and Subtracting from Existing Values
• Clearing Existing Data Values
• Scaling Data Values
• Flipping Field Signs

Performing Operations
on Records
You can perform operations at the record level. For example, you can
reject certain records before they are loaded into the database.

This section contains the following sections:

• Selecting Records
• Rejecting Records
• Combining Multiple Select and Reject Criteria
• Setting the Records Displayed
• Defining Header Records

Selecting Records
You can specify which records Analytic Services 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 before Analytic Services loads the
record. If a field or fields in the record do not meet the selection
criteria, Analytic Services 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.

To select a record, see "Selecting Records" in the Essbase XTD

Administration Services Online Help.

Note: If you define selection criteria on more than one field, you
can specify how Analytic Services combines the criteria. For a brief
discussion, see Combining Multiple Select and Reject Criteria.

Rejecting Records
You can specify which records Analytic Services ignores by setting
rejection criteria. Rejection criteria are string and number conditions
that, when met by one or more fields within a record, cause Analytic
Services to reject the record. You can define one or more rejection
criteria. If no field in the record meets the rejection criteria, Analytic
Services 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 Essbase XTD

Administration Services Online Help.

Note: If you define rejection criteria on more than one field, you
can specify how Analytic Services should combine the criteria. For a
brief discussion, see Combining Multiple Select and Reject Criteria.

Combining Multiple Select and Reject Criteria

When you define select and reject criteria on multiple fields, you can
specify how Analytic Services combines the rules across fields, that is,
whether the criteria are connected logically with AND or with OR. If
you select And from the Boolean group, the fields must match all of
the criteria. If you select Or from the Boolean group, the fields must
match only one of the criteria. The global Boolean setting applies to all
select or reject operations in the rules file, for both data load and
dimension build fields.

Note: If selection and rejection criteria apply to the same record

(that is, you try to select and reject the same record), the record is
rejected.
 To determine how to combine select and reject criteria on multiple
fields, see "Combining Selection and Rejection Criteria" in the Essbase
XTD Administration Services Online Help.

Setting the Records Displayed

You can specify the number of records that Analytic Services displays
in Data Prep Editor. You can also specify the first record in Data Prep
Editor. Analytic Services skips all preceding records and, in Data
Preparation Editor, begin the display with the record number you chose
as first. For example, if you enter 5 as the starting record, Analytic
Services does not display records 1 through 4.

Note: Analytic Services treats header records the same as data

records when counting the records to skip.

To set the records displayed, see "Setting the Records Displayed" in

the Essbase XTD Administration Services Online Help.

Defining Header Records

Data sources can contain data records and header records. Data
records contain member fields and data fields. Header records describe
the contents of the data source and describe how to load values from
the data source to the database.

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 either of the following methods:

• You can define header information in the rules file. Rules file
headers are used only during data loading or dimension
building and do not change the data source. Header
information set in a rules file is not used if the rules file also
points to header records in the data source.
• You can define header information in the data source by using
a text editor or spreadsheet and then pointing to the header
 records in the rules file. 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 and not
in the rules file.
When you add one or more headers to the data source, you
must also specify the location of the headers in the data source
in the rules file. The rules file then tells Analytic Services to read
the header information as a header record and not a data
record. You can also specify which type of header information is
in which header record.
Header information defined in the data source takes precedence
over header information defined in the rules file.
To define a header in the rules file, see "Setting Headers in the Rules
File" in the Essbase XTD Administration Services Online Help.
To define a header in the data source, see "Setting Headers in the
Data Source" in the Essbase XTD Administration Services Online Help.

Data Source Headers

You can dynamically build dimensions by adding header information to
the top record of the data source and by specifying the location of the
header record in the rules file.

Figure?106 contains an example of a header record.

Figure 106: Header Record

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. The format of a header record is
illustrated in Figure?107:

Figure 107: Header Record with Three Field Definitions

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, Analytic
Services uses the information in the data source-rather than the
information in the rules file-to determine field types and dimensions.

Valid Data Source Header Field Types

Valid field types must be in capital letters and are as follows:

• GEN, DUPGEN, and DUPGENALIAS

• LEVEL, DUPLEVEL, and DUPLEVELALIAS
• PARENT, CHILD
• PROPERTY
• ALIAS
• FORMULA
• CURNAME
• CURCAT
• UDA
• ATTRPARENT
• The name of an attribute dimension, such as CAFFEINATED

For each field type that you set, you must also enter a field number.
When the field type is the name of an attribute dimension, the field
number cannot be greater than 9. For a brief discussion and references
to pertinent topics, see Setting Field Type Information.
Performing Operations
on Fields
You can perform operations at the field level, for example, moving a
field to a new position in the record.

This section contains the following sections:

• Ignoring Fields
• Ignoring Strings
• Arranging Fields
• Mapping Fields
• Changing Field Names

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
Analytic Services database.

If the data source contains fields that you do not want to load into the
database, tell Analytic Services to ignore those fields. For example, the
Sample Basic database has five standard dimensions: Year, Product,
Market, Measures, and Scenario. If the data source has an extra field,
such as Salesperson, that is not a member of any dimension, ignore
the Salesperson field.

To ignore all fields in a column, see "Ignoring Fields" in the Essbase

XTD Administration Services Online Help.

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. Consider, for example, 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.
 To ignore all instances of a string, see "Ignoring Fields Based on
String Matches" in the Essbase XTD Administration Services Online
Help.

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. The following sections describe:

• Moving Fields
• Joining Fields
• Creating a New Field by Joining Fields
• Copying Fields
• Splitting Fields
• Creating Additional Text Fields
• Undoing Field Operations

Note: To undo a single operation, select Edit > Undo. To undo one
or more field operations, see "Undoing Field Operations" in the
Essbase XTD Administration Services Online Help.

Moving Fields
You can move fields to a different location using a rules file. For
example, a field might be the first field in the data source, but you
want to move it to be the third field during the data load or dimension
build.

In some instances, moved fields may appear to merge. Merging may

occur if the data file has a structure similar to the following:

1<tab>2<tab>3
1<tab>2<tab>(null) 
 

If you move a field that contains empty cells and the moved field
becomes the last field in the record, the field may merge with the field
to its left.

To prevent merging, replace the empty cell with a delimiter.

 To move fields, see "Moving Fields" in the Essbase XTD
Administration Services Online Help.

Note: To undo a move, see "Undoing Field Operations" in the

Essbase XTD 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 you receive a data
source with separate fields for product number (100) and product
family (-10), you must join the fields (100-10) before you load them
into the Sample Basic database.

Before you join fields, move the fields to join into the order in which
you want to join them. If you do not know how to move fields, see
"Moving Fields" in the Essbase XTD Administration Services Online
Help.

To join fields, see "Joining Fields" in the Essbase XTD Administration

Services Online Help.

Note: To undo a join, see "Undoing Field Operations" in the

Essbase XTD Administration Services Online Help.

Creating a New Field by Joining Fields

You can join two or more fields by placing the joined fields into a new
field. This procedure leaves the original fields intact. Creating a new
field is useful if you need to concatenate fields of the data source to
create a member.

For example, if you receive a data source with separate fields for
product number (100) and product family (-10), you must join the
fields (100-10) before you load them into the Sample Basic database.
But suppose that you want the 100 and -10 fields to exist in the data
source after the join; that is, you want the data source to contain
three fields: 100, -10, and 100-10. To do this, create the new field
using a join.

Before you join fields, move the fields to join into the order in which
you want to join them. If you do not know how to move fields, see
Moving Fields.
 To create a new field by joining existing fields, see "Creating a New
Field Using Joins" in the Essbase XTD Administration Services Online
Help.

Note: To undo a creating using join operation, see "Undoing Field

Operations" in the Essbase XTD Administration Services Online
Help.

Copying Fields
You can create a copy of a field while leaving the original field intact.
For example, assume that, during a single dimension build, you want
to define a multilevel attribute dimension and associate attributes with
members of a base dimension. To accomplish this task, you need to
copy some of the fields. For more information about attribute
dimensions, see Working with Multilevel Attribute Dimensions.

To copy a field, select one field and then create a new field using a
join.
To create a new field by joining existing fields, see "Creating a New
Field Using Joins" in the Essbase XTD Administration Services Online
Help.

Note: To undo a copy, see "Undoing Field Operations" in the

Essbase XTD 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 the UPC out of the field and ignore it. Then only 100-10-1,
that is, the product number, is loaded. To ignore a field, see Ignoring
Fields.

To split a field, see "Splitting Fields" in the Essbase XTD

Administration Services Online Help.

Note: To undo a split, see "Undoing Field Operations" in the

Essbase XTD Administration Services Online Help.
Creating Additional Text Fields
You can create a text field between two existing fields. You might
create a text field to insert text between fields that are to be joined.
For example, if you have two fields, one containing 100 and one
containing 10-1, you can insert a text field with a dash between the
two fields and then join the three fields to create the 100-10-1
member of the Product dimension.

To create a new field and populate it with text, see "Creating a New
Field Using Text" in the Essbase XTD Administration Services Online
Help.

Note: To undo a field you created using text, see "Undoing Field
Operations" in the Essbase XTD Administration Services Online
Help.

Undoing Field Operations

You can undo the last field operation that you performed, such as
move, split, join, create using text, or create using join by using the
Edit > Undo command. You can also undo field operations even if you
have performed other actions. Undoing field operations is sequential;
you must undo field operations from the last operation to the first
operation.

To undo one or more field operations, see "Undoing Field Operations"

in the Essbase XTD Administration Services Online Help.

Mapping Fields
This section applies to data load only. If you are performing a
dimension build, skip this section.

You use a rules file to map data source fields to Analytic Services
member names during a data load. You can map fields in a data source
directly to fields in the Analytic Services database during a data load
by specifying which field in the data source maps to which member or
member combination in the Analytic Services 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
Analytic Services dimension names are the same, you do not have
to map the column names.

To map fields, see "Mapping Field Names" in the Essbase XTD

Administration Services Online Help.

Changing Field Names

To load a data source, you must specify how the fields of the data
source map to the dimensions and members of the database. Rules
files can translate fields of the data source so that the fields match
member names each time the data source is loaded. This process does
not change the data source. The rules file does the following:

• 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

This section contains the following sections that describe how to

change field names in the data source to map members and data
values to the database.

• Replacing Text Strings

• Replacing an Empty Field with Text
• Changing the Case of Fields
• Dropping Leading and Trailing Spaces
• Converting Spaces to Underscores
• Adding Prefixes or Suffixes to Field Values

Replacing Text Strings

You can replace text strings so that the fields map to Analytic Services
member names during a data load or dimension build. The data source
is not changed. For example, if the data source abbreviates New York
to NY, you can have the rules file replace each NY with New York
during the data load or the dimension build.

For instructions on how to replace an empty field with text, see

Replacing an Empty Field with Text.

To replace a text string, see "Replacing Field Names" in the Essbase

XTD Administration Services Online Help.
Replacing an Empty Field with Text
You may want to replace empty fields in a column with text. If, for
example, empty fields in the column represent default values, you can
insert the default values or insert #MI to represent missing values.

To replace an empty field with text, see "Replacing an Empty Field

with Text" in Essbase XTD Administration Services Online Help.

Changing the Case of Fields

You can change the case of a field so the field maps to Analytic
Services member names during a data load or dimension build. The
data source is not changed. For example, if the data source capitalizes
a field that is in lower case in the database, you could change the field
to lower case; for example, JAN to jan.

To change the case of values in a field, see "Changing Case of Fields"

in the Essbase XTD Administration Services Online Help.

Dropping Leading and Trailing Spaces

You can drop leading and trailing spaces from around fields of the data
source. A field value containing leading or trailing spaces does not map
to?a?member name, even if the name within the spaces is an exact
match.

By default, Analytic Services drops leading and trailing spaces.

To drop spaces around a field, see "Dropping Spaces Around Fields"

in the Essbase XTD Administration Services Online Help.

Converting Spaces to Underscores

You can convert spaces in fields of the data source to underscores to
make the field values match the member names of the database.

To change spaces to underscores, see "Converting Spaces to

Underscores" in the Essbase XTD Administration Services Online Help.
Adding Prefixes or Suffixes to Field Values
You can add prefixes and suffixes to each field value of the data
source. For example, you can add 2002 as the prefix to all member
names in the Year dimension.

To prefix or suffix values to a field, see "Adding Prefixes and

Suffixes" in the Essbase XTD Administration Services Online Help.

Performing Operations
on Data
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.

This section contains the following sections:

• Defining a Column as a Data Field

• Adding to and Subtracting from Existing Values
• Clearing Existing Data Values
• Scaling Data Values
• Flipping Field Signs

Defining a Column as a Data Field

This section applies to data load only. If you are performing a
dimension build, skip this section.

If each record in the data source contains a column for every

dimension and one data column, you must define the data column as a
data field. In Figure?108, for example, the column with the data values
must be defined as a data field.

Figure 108: Data Field

Market, Product, Year, Measures, Scenario
Texas  100­10  Jan  Sales Actual 42 
Texas  100­20  Jan  Sales Actual 82
Texas  100­10  Jan  Sales Actual 37 
 

You can define only one field in a record as a data field.

To define a data field, see "Defining a Column as a Data Field" in the

Essbase XTD Administration Services Online Help.

Adding to and Subtracting from Existing Values

This section is for data load only. If you are performing a dimension
build, skip this section.

By default, Analytic Services overwrites the existing values of the

database with the values of the data source, but you can determine
how newly loaded data values affect existing data values.

You can use incoming data values to add to or subtract from existing
database values. For example, if you load weekly values, you can add
them to create monthly values in the database.

Using this option makes it more difficult to recover if the database

crashes while loading data, although Analytic Services lists the number
of the last row committed in the application log. For a discussion of the
application log, see Contents of the Application Log.

To prevent difficult recoveries if you are adding to or subtracting from

existing data values and the database shuts down abnormally, as a
Database Transaction setting, set the Commit Row value as 0. This
setting causes Analytic Services to view the entire load as a single
transaction and to commit the data only when the load is complete.
For more information, see Understanding Isolation Levels.

To add to existing data values, see "Adding to Data Values" in the

Essbase XTD Administration Services Online Help.
To subtract from existing data values, see "Subtracting from Data
Values" in the Essbase XTD Administration Services Online Help.
Clearing Existing Data Values
This section is for data load only. If you are performing a dimension
build, skip this section.

You can clear existing data values from the database before you load
new values. By default, Analytic Services overwrites the existing
values of the database with the new values of the data source. If you
are adding and subtracting data values, however, Analytic Services
adds or subtracts the new data values to and from the existing values.

Before adding or subtracting new values, make sure that the existing
values are correct. Before loading the first set of values into the
database, you must make sure that there is no existing value.

For example, assume that the Sales figures for January are calculated
by adding the values for each week in January:

January Sales = Week 1 Sales + Week 2 Sales + Week 3 Sales + 
Week 4 Sales 
 

When you load Week 1 Sales, clear the database value for January
Monthly Sales. If there is an existing value, Analytic Services 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 the
January and February data.

Note: If you are using transparent partitions, clear the values using
the steps that you use to clear data from a local database.

To clear existing values, see "Clearing Existing Data Values" in the

Essbase XTD Administration Services Online Help.
Scaling Data Values
This section is for data load only. If you are performing a dimension
build, skip this section.

You can scale data values if the values of the data source are not in
the same scale as the values of the database.

For example, assume the real value of sales was $5,460. If the Sales
data source tracks the values in hundreds, the value is 54.6. If the
Analytic Services database tracks the real value, you need to multiply
the value coming in from the Sales data source (54.6) by 100 to have
the value display correctly in the Analytic Services database (as 5460).

To scale data values, see "Scaling Data Values" in the Essbase XTD
Administration Services Online Help.

Flipping Field Signs

This section is for data load only. If you are performing a dimension
build, skip this section.

You can reverse or flip the value of a data field by flipping its sign.
Sign flips are based on the UDAs (user-defined attributes) of the
outline. When loading data into the accounts dimension, for example,
you can specify that any record whose accounts member has a UDA of
Expense change from a plus sign to a minus sign. See Creating UDAs
for more information on user-defined attributes.

To reverse a field sign, see "Flipping Signs" in the Essbase XTD

Administration Services Online Help.

Performing and
Debugging Data Loads
or Dimension Builds
This chapter describes how to load data or members from one or more
external data sources to an Analytic Server. You can load data without
updating the outline, you can update the outline without loading data,
or you can load data and build dimensions simultaneously. For
information about setting up data sources and rules files, see
Understanding Data Loading and Dimension Building and Creating
Rules Files.

This chapter contains the following sections:

• Prerequisites for Data Loads and Dimension Builds

• Performing Data Loads or Dimension Builds
• Stopping Data Loads or Dimension Builds
• Reviewing the Tips for Loading Data and Building Dimensions
• Debugging Data Loads and Dimension Builds

Prerequisites for Data

Loads and Dimension
Builds
Before you start to load data or build dimensions, make sure that you
have the following items in place:

• An Analytic Services database.

• A connection to the appropriate Analytic Server.
• One or more valid data sources. For a comprehensive
discussion of data sources, see Data Sources.
• 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.
• If you are using a rules file, for a definition and discussion of
rules files, see Rules Files.

Performing Data Loads

or Dimension Builds
When you start to load data or build dimensions, you must first select
one or more valid data sources that contain the data to load or
dimensions to build. For a list of types of valid data sources, see
Supported Data Sources. Make sure you are connected to the Analytic
Server before you specify the data sources. For a comprehensive
discussion of how to optimize a data load, see Optimizing Data Loads.

When you use Administration Services to perform a data load or

dimension build, you can execute the load or build in the background
so that you can continue working as the load or build processes. You
can then check the status of the background process to see when the
load or build has completed. For more information, see "Performing a
Data Load or Dimension Build" in Essbase XTD Administration Services
Online Help.

Note: If you are loading data into a transparent partition, follow the
same steps as for loading data into a local database.

To load data or build dimensions, use any of the following methods:

Tool Topic Location

Administration Performing a Data Essbase XTD

Services Load or Dimension Administration Services
Build Online Help

MaxL For data loading: Technical Reference

import?data
For dimension
building: import
dimensions

ESSCMD For data loading: Technical Reference

IMPORT
For dimension
building: BUILDDIM
Stopping Data Loads or
Dimension Builds
You can stop a data load or dimension build before it completes. You
should not stop a data load or dimension build unless you are very
sure that stopping is necessary. If a data load or dimension build
process is terminated, Analytic Services displays the file name as
partially loaded.

If you initiate a data load or dimension build from a client and

terminate the data load or dimension build from the server, it could
take some time before the client responds to the termination request.
Because Analytic Services reads the source file until all source data is
read, the amount of time depends on the size of the file and the
amount of source data that Analytic Services has processed. If the
process is terminated from the machine that initiated it, the
termination is immediate.

Note: If you are adding to or subtracting from data values during a

data load, 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. For a description of the operation of each
isolation level setting, see Understanding Isolation Levels. If you
stop a data load that is adding to or subtracting from data values,
see Recovering from an Analytic Server Crash to identify the
recovery procedure.

To stop a data load or dimension build before it completes, use any

of the following methods:

Tool Topic Location

Administration Disconnecting User Essbase XTD

Services Sessions and Administration Services
Requests Online Help

MaxL alter system kill Technical Reference

request
Reviewing the Tips for
Loading Data and
Building Dimensions
This section lists tips for data loading and dimension building. It
contains the following sections

• Determining Where to Load Data

• Loading Data Using a Spreadsheet
• Dealing with Missing Fields in a Data Source
• Loading a Subset of Records from a Data Source

Determining Where to Load Data

Skip this section if you are building dimensions.

If you load data into a parent member, when you calculate the
database, the consolidation of the children's data values can overwrite
the parent data value. To prevent overwriting, be aware of the
following:

• If possible, do not load data directly into a parent.

• If you must load data into a parent member, make sure that
Analytic Services knows not to aggregate #MISSING values
from the children of the parent into the parent, as directed in
the following table:
To set the aggregation, use any of the following methods:

Tool Topic Location

Administration Aggregating Missing Essbase XTD

Services Values During Administration
Calculation Services Online Help

Calculation SET AGGMISSG Technical Reference

Script
MaxL alter database Technical Reference

ESSCMD SETDBSTATEITEM Technical Reference

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. For a discussion of how
Analytic Services calculates #MISSING values, see Aggregating
#MISSING Values.

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.

Loading Data Using a Spreadsheet

Skip this section if you are building dimensions.

If you use a spreadsheet to load data, see the Essbase XTD

Administration Services Online Help and search for "spreadsheet" in
the index.

Dealing with Missing Fields in a Data Source

Each record in the data source must have the same number of fields to
perform a data load or dimension build. If fields are missing, the data
load or dimension build processes incorrectly. For example, the file in
Figure?109 is invalid, because there is no value under Apr. To fix the
file, insert #MISSING or #MI into the missing field. For instructions,
see Replacing an Empty Field with Text.

Figure 109: Missing Fields

Actual Ohio Sales Cola
Jan     Feb    Mar    Apr
10      15     20
 
 
Figure?110 is valid because #MI replaces the missing field.

Figure 110: Valid Missing Fields

Actual Ohio Sales Cola
Jan     Feb    Mar    Apr
10      15     20     #MI
 
 

If a rules file has extra blank fields, join the empty fields with the field
next to them. For a brief discussion, see Joining Fields.

Loading a Subset of Records from a Data Source

You can load a subset of records in a data source during a data load or
a dimension build. For example, you can load records 250 to 500
without loading the other records of the data source.

To load a subset of records:

1. Using a text editing tool, number the records in the data
source.
2. Set the rules file to ignore the column containing the record
number.
For a brief discussion, see Ignoring Fields.
3. 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
less than 250 or greater than 500. For a brief discussion, see
Rejecting Records.

Note: You cannot reject more records than the error log can
hold. By default, the limit is 1000, but you can change it by
setting DATAERRORLIMIT in the essbase.cfg file. See the
Technical Reference for more information.
Debugging Data Loads
and Dimension Builds
If you try to load a data source into Analytic Server, but it does not
load correctly, check the following:

• Are you connected to the appropriate application and

database?
• Are you trying to load the correct data source?

If you can answer both of the above questions with a "yes," something
is probably wrong. Use the following sections to determine what the
problem is and to correct the problem.

• Verifying That Analytic Server Is Available

• Verifying That the Data Source Is Available
• Checking Error Logs
• Recovering from an Analytic Server Crash
• Resolving Problems with Data Loaded Incorrectly
• Creating Rejection Criteria for End of File Markers
• Understanding How Analytic Services Processes a Rules File
• Understanding how Analytic Services Processes Invalid Fields
During a Data Load

When you correct the problems, you can reload the records that did
not load by reloading the error log. For more information, see Loading
Dimension Build and Data Load Error Logs.

Verifying That Analytic Server Is Available

To help identify if the problem is with Analytic Services and not with
the server or network, try to access the server without using Analytic
Services. Check the following:

• Is the server machine running? Try to connect to it without

using Analytic Services. If you cannot, check with your
system administrator.
• Is Analytic Server running? Check with your Analytic Services
administrator.
 • Can the client machine connect to the server machine? Try to
connect to the server machine from the client machine
without using Analytic Services.

Verifying That the Data Source Is Available

If Analytic Services cannot open the data source that you want to load,
check the following:

• Is the data source already open? The data source will already
be open if a user is editing the data source. Analytic Services
can load only data sources that are not locked by another
user or application.
• Does the data source have the correct file extension? All text
files must have a file extension of .TXT. All rules files must
have a file extension of .RUL.
• Is the data source name and the path name correct? Check
for misspellings.
• Is the data source in the specified location? Check to make
sure that no one has moved or deleted the data source.
• If you are using a SQL data source, is the connection
information (such as the user name, password, and database
name) correct?
• If you are using a SQL data source, can you connect to the
SQL data source without using Analytic Services?

Checking Error Logs

If a data load or dimension build fails, the error log can be a valuable
debugging tool. See Understanding and Viewing Dimension Build and
Data Load Error Logs in for more information about error logs.

If there is no error log, check the following:

• Did the person running the data load set up an error log?
Click Help in the Data Load dialog box for information on
setting up an error log. By default, when you use a rules file,
Analytic Services creates an error log.
• Are you sure that the data source and Analytic Server are
available? See Verifying That Analytic Server Is Available and
Verifying That the Data Source Is Available for lists of items to
check.
 • Did the Analytic Server crash during the data load? If so, you
probably received a time-out error on the client. If the server
crashed, see Recovering from an Analytic Server Crash to
identify a recovery procedure.
• Check the application log. For a review of log information, see
Understanding Analytic Server and Application Logs.

If the error log exists but is empty, Analytic Services does not think
that an error occurred during loading. Check the following:

• Does the rules file contain selection or rejection criteria that

rejected every record in the data source? See Selecting
Records and Rejecting Records for a discussion of how to set
selection and rejection criteria.
• Is the rules file correct? Does the rules file validate properly?
See Requirements for Valid Data Load Rules Files and
Requirements for Valid Dimension Build Rules Files for a
discussion of causes of non validation.

Recovering from an Analytic Server Crash

If the server crashes while you are loading data, Analytic Services
sends you a time-out error. The recovery procedures that you need to
perform depend on the type of load you are performing and the
Isolation Level setting:

• 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 transaction setting is
Committed, 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 is Uncommitted,
determine how much data Analytic Services loaded before the
crash:
a. Compare the values of the data source with the values
of the database.
b. If the values that you are adding to or subtracting from
have not changed, reload the data source.
c. 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 re-load the sales figures for each
week up to the current week.

For a description of Isolation Level settings, see Understanding

Isolation Levels.

Resolving Problems with Data Loaded Incorrectly

If the data source loads without error, but the data in the database is
wrong, check the following:

• Are you sure that you loaded the correct data source? If so,
check the data source again to make sure that it contains the
correct values.
• Are there any blank fields in the data source? You must insert
#MI or #MISSING into a data field that has no value.
Otherwise, the data source may?not load correctly. To replace
a blank field with #MI or #MISSING using a rules file, see
Replacing an Empty Field with Text.
• Is the data source formatted correctly? Are all ranges set up
properly?
• Are there any implicitly shared members that you were
unaware of? Implicit shares happen when a parent and child
share the same data value. This situation occurs if a parent
has only one child or only one child rolls up into the parent.
For a definition and discussion of implied sharing, see
Understanding Implied Sharing.
• Did you add incoming data to existing data instead of
replacing incoming data with existing data? For a discussion
of the adding and subtracting process, see Adding to and
Subtracting from Existing Values.
• Have you selected or rejected any records that you did not
intend to select or reject? For a brief discussion of selecting
and rejecting, see Selecting Records and Rejecting Records.
• If the sign is reversed (for example, a minus sign instead of a
plus sign), did you perform any sign flips on UDAs (user-
defined attributes)? For a discussion of the sign flipping
process, see Flipping Field Signs.
• Did you clear data combinations that you did not intend to
clear? For a discussion of the process of clearing data, see
Clearing Existing Data Values.
 • Did you scale the incoming values incorrectly? For examples
of scaling data, see Scaling Data Values.
• Are all member and alias names less than 79 characters long?

Note: You can check data by exporting it, by running a report on it,
or by using a spreadsheet. If doing exports and reports, see
Developing Report Scripts and Using ESSCMD. If using a
spreadsheet, see the Essbase XTD Spreadsheet Add-in User's
Guide.

Creating Rejection Criteria for End of File Markers

A SQL data source may have an end of file marker made up of special
characters that cause a data load or dimension build to fail. To fix this
problem, define a rejection criterion to reject the problem record.

1. Find the end of file marker in the SQL data source.

2. Determine how to search for it using the Analytic Services
search command.
This task may be difficult as the end of file marker may be
composed of one or more special characters. To ignore all
instances of a string, see "Ignoring Fields Based on String
Matches" in the Essbase XTD Administration Services Online
Help.
3. Define a rejection criterion that rejects the end of file marker.
See "Rejecting Records" in the Essbase XTD Administration
Services Online Help.

Understanding How Analytic Services Processes a Rules File

Sometimes, you can track down problems with dimension builds by
understanding how Analytic Services initializes the rules file and
processes the data source.

Analytic Services performs the following steps to initialize a rules file:

1. Validates the rules file against the associated outline.

2. Validates the dimensions. This process includes ensuring that
the build method and field types are compatible and that each
dimension name is unique. Member names must be either
unique or shared.
3. Adds new dimensions defined in the rules file to the outline.
 4. Reads header records specified in the data source.

Then Analytic Services performs the following operations on each

record of the data source during a data load or dimension build:

1. Sets the file delimiters for all records.

2. Applies field operations to the data in the order that the
operations are defined in the rules file. Field operations
include joins, moves, splits, and creating fields using text and
joins. To see the order in which field operations are defined in
the rules file, see Undoing Field Operations. The dialog box
displayed lists all the field operations in order.
3. Analytic Services applies all properties for each field, applying
all properties to field1 before proceeding to field2. Analytic
Services applies field properties in the following order:
a. Ignores fields set to be ignored during data load.
b. Ignores fields set to be ignored during dimension build.
c. Flags the data field.
d. Applies field names.
e. Applies field generations.
f. Performs all replaces in the order that they are defined
in the rules file.
g. Drops leading and trailing spaces.
h. Converts spaces to underscores.
i. Applies suffix and prefix operations.
j. Scales data values.
k. Converts text to lowercase.
l. Converts text to uppercase.
4. Adds members or member information, or both, to the
outline.
5. If you chose to skip lines, Analytic Services skips the number
of lines that you specified; otherwise, Analytic Services
proceeds to the first record.
6. Analytic Services performs selection or rejection criteria in the
order that the criteria are defined in the rules file. Analytic
Services loads or rejects individual records of the data source
based on the specified criteria.

Understanding how Analytic Services Processes Invalid Fields

During a Data Load
The following sections describe how Analytic Services processes invalid
fields during a data load.
 • Missing Dimension or Member Fields
• Unknown Member Fields
• Invalid Data Fields

Missing Dimension or Member Fields

If you are using a rules file for the data load, skip this section. It
applies only to data loaded without a rules file.

In a free-form data load, if a dimension or member field is missing,

Analytic Services uses the value that it used previously for that
dimension or member field. If there is no previous value, Analytic
Services aborts the data load.

For example, when you load Figure?111 into the Sample Basic
database, Analytic Services maps the Ohio member field into the
Market dimension for all records, including the records that have Root
Beer and Diet Cola in the Product dimension.

Figure 111: Valid Missing Members

Jan Sales Actual Ohio
Cola          25
"Root Beer"   50
"Diet Cola"   19 
 

Analytic Services stops the data load if no prior record contains a value
for the missing member field. If you try to load Figure?112 into the
Sample Basic database, for example, the data load stops, because the
Market dimension (Ohio, in Figure?111) is not specified.

Figure 112: Invalid Missing Members

Jan Sales Actual
           Cola          25
           "Root Beer"   50
           "Diet Cola"   19 
 
For information on restarting the load, see Loading Dimension Build
and Data Load Error Logs.

Unknown Member Fields

If you are performing a data load and Analytic Services encounters an
unknown member name, Analytic Services rejects the entire record. If
there is a prior record with a member name for the missing member
field, Analytic Services continues to the next record. If there is no prior
record, the data load stops. For example, when you load Figure?113
into the Sample Basic database, Analytic Services rejects the record
containing Ginger Ale because it is not a valid member name. Analytic
Services loads the records containing Cola, Root Beer, and Cream
Soda. If Ginger Ale were in the first record, however, the data load
would stop.

Figure 113: Unknown Members

Jan, Sales, Actual
Ohio    Cola          2
        "Root Beer"   12
        "Ginger Ale"  15
        "Cream Soda"  11 
 

Note: If you are performing a dimension build, you can add the
new member to the database. See Performing Data Loads or
Dimension Builds.

For information on restarting the load, see Loading Dimension Build

and Data Load Error Logs.

Invalid Data Fields

If you are performing a data load, when Analytic Services encounters
an invalid data field, it stops the data load. Analytic Services loads all
fields read before the invalid field into the database, resulting in a
partial load of the data. In the following file, for example, Analytic
Services stops the data load when it encounters the 15- data value.
Analytic Services loads the Jan and Feb Sales records, but not the Mar
and Apr Sales records.

Figure 114: Invalid Data Field

East Cola   Actual
Sales       Jan     $10
            Feb     $21
            Mar     $15­
            Apr     $16 
 

For information on continuing the load, see Loading Dimension Build

and Data Load Error Logs.

Understanding
Advanced Dimension
Building Concepts
This chapter discusses dimension building.

• Understanding Build Methods

• Using Generation References
• Using Level References
• Using Parent-Child References
• Adding a List of New Members
• Building Attribute Dimensions and Associating Attributes
• Building Shared Members by Using a Rules File

Understanding Build
Methods
The build method that you select determines the algorithm that
Analytic Services uses to add, change, or remove dimensions,
members, and aliases in the outline. The kind of build method that you
select depends on the type of data in the data source.

The following table provides guidelines to help you select the

appropriate build method for the data source:

Table 22: Build Method Guidelines ?

Type of
Data in Desired Build Field Type
Examples
Each Operation Method Information
Record

Top-down Year, Modify the Generation The

data: Each Quarter, properties of references generation
record Month existing number for
specifies dimensions and each field.
the parent's members
name, the
child's
name, the
children of
that child,
and so
forth.

Bottom-up Month, • Create Level The level

data: Each Quarter, shared references number for
record Year members each field.
specifies that?roll
the name up into
of the different
member, generatio
the name ns
of its • Modify
parent, the the
name of its propertie
parent's s of
parent, and existing
so forth. dimensio
ns and
members
Parent Cola, • Create Parent-child Whether a
followed by Diet?Cola shared references field is parent
its child: members or child. The
Each record that roll field number
specifies up into is?0.
the name different
of the generatio
parent and ns
the name • Share
of the new non-leaf
child members
member, in • Modify
that order, propertie
although s of
they can existing
specify dimensio
other ns and
information members
as well.
A list of Jan, Feb, Add all members Add as child .
new Mar, April as children of an of the
members: existing parent specified
Each data (possibly a parent
source lists "dummy" parent)
new
members; .
800-10, Add all members Add as
the data 800-20 at the end of the sibling at
source does dimension the lowest
not specify level
where in
the outline 800-10, Add each new Add as .
the 800-20 member to the sibling to a
members dimension that member
belong. contains similar with a
Analytic members matching
Services string
provides
algorithms
that
determine
where to
add these
members.

A list of Cola 16oz Add members to Generation, The number

base Can, Root an attribute level, or for each field.
dimension Beer 14oz dimension and parent-child The number is
members Bottle associate the references, either the
and their added members depending generation or
attributes. with the on?the level number
appropriate organization of the
members of the of?the associated
base dimension source data member of
the base
dimension or
zero.
Using Generation
References
Top-down data sources are organized left to right from the highest
level to the lowest level. Each record begins with the most general
information and progresses to the most specific information. The name
of the new member is at the end of the record. When using a top-
down data source, use the generation references build method. In the
rules file, specify the generation number and the field type of each
field of the data source.

Analytic Services numbers members within a dimension according to

the hierarchical position of the member within the dimension. The
numbers are called generation references. A dimension is always
generation 1. All members at the same branch in a dimension are
called a generation. Generations are numbered top-down according to
their position relative to the dimension, that is, relative to dimension
1.

For example, as illustrated in Figure?115, the Product dimension in the

Sample Basic database is generation?1. Product has a 100 member,
which is generation 2. 100 has members, such as 100-10, which are
generation 3. To use the generation references build method, you must
specify the generation reference number in the rules file.

Figure 115: Generations

The top half of Figure?116 shows a top-down data source GENREF.TXT.

The data source is used to build the Product dimension. The bottom
half of Figure?116 shows the rules file for the data source, GENREF.RUL.
The rules file specifies the generation number for each field in the data
source. For information on setting field types and references to
pertinent topics, see Setting Field Type Information.

Figure 116: Rules File for Generation Build

Figure?117 shows the tree that Analytic Services builds from this data
source and rules?file:

Figure 117: Generation References

Dealing with Empty Fields

When you use the generation references build method, you can choose
to use null processing. Null processing specifies what actions Analytic
Services takes when it encounters empty fields, also know as null
fields, in the data source.

If null processing is not enabled, Analytic Services rejects all records

with null values and writes an error to the error log.

If null processing is enabled, Analytic Services processes nulls as

follows:

• If the null occurs where Analytic Services expects a

GENERATION field, Analytic Services promotes the next
GENERATION field to replace the missing field. In Figure?118,
for example, there is no field in the GEN3,Products column.
When Analytic Services reads the following record, it
promotes the GEN4 field (100-10a) to GEN3.
 Figure 118: Missing Field in a Generation References Data
Source

GEN2,Products???GEN3,Products???GEN4,Products
100?????????????????????????????100­10a
• If a null occurs directly before a secondary field, Analytic
Services 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
Figure?119, for example, there is no field in the GEN2,
Products or the ALIAS2,Products column. When Analytic
Services reads the following record, it ignores the ALIAS2
field and promotes the GEN3 field (100-10) to GEN2 and the
GEN4 field (100-10a) to GEN3.

Figure 119: Missing Secondary Field in a Generation References

Data Source

GEN2,Products??ALIAS2,Products??GEN3,Products??GEN4,Pro
ducts
???????????????Cola?????????????100­10?????????100­10a
• If the null occurs where Analytic Services expects a secondary
field, Analytic Services ignores the secondary null field and
continues loading. In Figure?120, for example, there is no
field in the ALIAS2, Products column. When Analytic Services
reads the following record, it ignores the ALIAS2 field.

Figure 120: Missing Secondary Field in a Generation References

Data Source

GEN2,Products??ALIAS2,Products??GEN3,Products??GEN4,Pro
ducts
100????????????? ???????????????100­10?????????100­10a

Using Level References

In a bottom-up data source, each record defines a single member of a
dimension. The definition begins with the most specific information
about the member and provides progressively more general
information. A typical record specifies the name of the new member,
then the name of its parent, then its parent's parent, and so forth.

Levels are defined from a bottom-up hierarchical structure. In the

outline in Figure?121, for example, the lowest level members are at
the bottoms of the branches of the Product dimension.

Figure 121: Generation and Level Numbers

To build the outline in Figure?121, you can use the bottom-up data
source shown in Figure?122.

Figure 122: Bottom-up Data Source

100­10­12 100­10 100
100­20­12 100­20 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).

The rules file in Figure?123 uses the level reference build method to
add members to the Product dimension of the Sample Basic database.
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).

The rules file specifies the level number and the field type for each
field of the data source. For more information on setting field types
and references to pertinent topics, see Setting Field Type Information.
To build the tree in Figure?124, for example, use Figure?123 to set up
the data source, LEVEL.TXT, and the rules file, LEVEL.RUL.

Figure 123: Rules File for Level Build

Figure?124 shows the tree that Analytic Services builds from the data
source and rules file of Figure?123.

Figure 124: Levels

Dealing with Empty Fields

When you use the level references build method, you can choose to
use null processing. Null processing specifies what actions Analytic
Services takes when it encounters empty fields, also know as null
fields, in the data source.

If null processing is not enabled, Analytic Services rejects all records

with null values and writes an error to the error log.

If null processing is enabled, Analytic Services processes nulls as

follows:

• If a null occurs where Analytic Services expects a LEVEL field,

Analytic Services promotes the next LEVEL field to replace the
missing field. In Figure?125, for example, there is no field in
the LEVEL0, Products column. When Analytic Services reads
the following record, it promotes the LEVEL1 field (100-10) to
LEVEL0 and the LEVEL2 field (100) to LEVEL1.

Figure 125: Missing Field in a Level References Data Source

 LEVEL0,Products??LEVEL1,Products??LEVEL2,Products
?????????????????100­10???????????100
• If a null occurs directly before a secondary field, Analytic
Services 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 Figure?126,
for example, there is no field in the LEVEL0, Products column.
When Analytic Services reads the following record, it ignores
the ALIAS0 field and promotes the LEVEL1 field (100-10) to
LEVEL0 and the LEVEL2 field (100) to LEVEL1.

Figure 126: Missing Secondary Field in a Level References Data

Source

LEVEL0,Products??ALIAS0,Products??LEVEL1,Products??LEVEL2,Pr
oducts
?????????????????Cola?????????????100­10???????????100
 
 
• If a null occurs where Analytic Services expects a secondary
field, Analytic Services ignores the secondary null field and
continues loading. In Figure?120, for example, there is no
field in the ALIAS0, Products column. When Analytic Services
reads the following record, it ignores the ALIAS0 field.

Figure 127: Missing Secondary Field in a Level References Data

Source

LEVEL0,Products??ALIAS0,Products??LEVEL1,Products??LEVEL2,Pr
oducts
100­10a??????????100­10????????????????????????????100 
 

Using Parent-Child
References
Use the parent-child references build method when every record of the
data source specifies the name of a new member and the name of the
parent to which you want to add the new member.

Members in a database exist in a parent-child relationship to one

another. Figure?128 shows part of the Product dimension with its
parent and children relationships identified.

Figure 128: Parents and Children

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 parent-child
data source cannot specify more than one parent or more than one
child 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 general information on
setting field types and references to pertinent topics, see Setting Field
Type Information. For example, the top half of Figure?129 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. In addition to
identifying parent and child fields, this example associates aliases with
the child field.

Figure 129: Rules Files for Parent-Child Build

Figure?130 shows the tree that Analytic Services builds from this data
source and rules file.

Figure 130: Parents and Children

Adding a List of New

Members
If a data source consists of a list of new members and does not specify
the ancestors of the new members, Analytic Services must decide
where in the outline to add the new members. Analytic Services
provides the following three build methods for this type of data source.

• Add each new member as a sibling of the existing member

whose text most closely matches its own. For a discussion of
the process and an example, see Adding Members Based
upon String Matches.
• Add each new member as a sibling of the lowest-level existing
member. For a discussion of the process and an example, see
Adding Members as Siblings of the Lowest Level.
• Add all new members as children of a specified parent
(generally a "dummy" parent). For a discussion of the process
and an example, see Adding Members to a Specified Parent.
Note: Analytic Services does not support concurrent attribute
association with the Add as build methods.

After Analytic Services adds all new members to the outline, it may be
necessary to move the new members into their correct positions using
Outline Editor. For a brief discussion and references to pertinent topics,
see Positioning Dimensions and Members.

Adding Members Based upon String Matches

You can add new members from a data source to an existing
dimension by matching strings with existing members. When Analytic
Services encounters a new member in a data source, it scans the
outline for a member name with similar text. Analytic Services then
adds the new member as a sibling of the member with the closest
string match.

For example, the data source in Figure?131, SIBSTR.TXT, contains two

new members to add to the Product dimension in the Sample Basic
database, 100-11 and 200-22. The new members are similar to strings
in the Product dimension in that they contain 3 digits, 1 dash, and 2
digits.

To add the example members to the database, set the following values
in the rules file:

For brief
In the rules Perform the following discussions and
file task references to
pertinent topics

Select field 1 • Do not select a field See Setting Field

(Product). type for the field. Type Information.
• Set the dimension
for the field to
Product. Field 1 is
displayed as
Product, as shown
in Figure?130.

Select field 2 Ignore the fields. See Ignoring Fields.

through field
6.
Select the Select the "Add as sibling of See Selecting a
Product matching string" build Build Method.
dimension. method.

Figure 131: Rules File Fields Set to Add Members as Siblings with
String Matches

Figure?132 shows the tree that Analytic Services builds from this data
source and rules file.

Figure 132: Tree for Adding Members as Siblings with String Matches

Adding Members as Siblings of the Lowest Level

You can add new members from a data source as siblings of members
that reside at the lowest level of a dimension, that is, at the leaf
branch. When Analytic Services encounters a new member in a data
source, it scans the outline for the leaf branch of members. Analytic
Services adds the new member as a sibling of these members.

Note: If the outline contains more than one group of members at

this level, Analytic Services adds the new member to the first group
of members that it encounters.
For example, the data source, SIBLOW.TXT, and the rules file,
SIBLOW.RUL, in Figure?133 contain new members (A100-10 and A100-
99) to add to the Measures dimension of the Sample Basic database.

To add the example members dynamically to the database, set the

following values in the rules file:

For brief
In the rules Perform the following discussions and
file task references to
pertinent topics

Select field 3 • Do not select a See Setting Field

(Measures). field type for the Type Information.
field.
• Set the dimension
for the field to
Measures. Field 3
is displayed as
Measures, as
shown in
Figure?133.

Select fields 1, Ignore the fields. See Ignoring Fields.

2, 4, 5, 6.

Select the Select the "Add as sibling of See Selecting a

Measures lowest level" build method. Build Method.
dimension.

Figure 133: Rules File Fields Set to Add Members as Siblings of the
Lowest Level

Figure?134 shows the tree that Analytic Services builds from this data
source and rules file.
Figure 134: Tree for Adding Members as Siblings of the Lowest Level

Adding Members to a Specified Parent

You can add all new members as children of a specified parent,
generally a "dummy" parent. After Analytic Services adds all new
members to the outline, review the added members and move or
delete them in Outline Editor.

When Analytic Services encounters a new member in the data source,

it adds the new member as a child of the parent that you define. The
parent must be part of the outline before you start the dimension
build.

For example, the data source in Figure?135, SIBPAR.TXT, contains two

new members, 600-54 and 780-22, for the Product dimension (field
1). Assume that you previously added a member called NewProducts
under the Products dimension.

To add the example members to the database under the NewProducts

member, set the following values in the rules file:

For brief discussions

In the rules Perform the following
and references to
file task
pertinent topics

Select field 1 • Do not select a See Setting Field Type

(Product). field type for the Information.
field.
• Set the
dimension for the
field to Product.
Field 1 is
displayed as
Product, as
shown in
 Figure?135.

Select fields Ignore the fields. See Ignoring Fields.

2 through 6.

Select the Select the "Add as child See Selecting a Build

Product of" build method. Method. Type
dimension. NewProducts in the
Add as Child of text
box.

Figure 135: Rules File Fields Set to Add Members as a Child of a Spec

ified Parent

Figure?136 shows the tree that Analytic Services builds from this data
source and rules file.

Figure 136: Tree for Adding Members as a Child of a Specified Parent

Building Attribute
Dimensions and
Associating Attributes
When a data source contains attribute information, you must use one
or more rules files to build attribute dimensions and to associate
attributes with members of their base dimensions.

You can use rules files to build attribute dimensions dynamically, to

add and delete?members, and to establish or change attribute
associations.

Working with attributes involves the three following operations:

• If the base dimension does not exist, you must build it.
• You must build the attribute dimension.
• You must associate members of the base dimension with
members of the attribute dimension.

You can use any of three approaches to perform these operations:

• Build both the base and attribute dimensions and perform the
associations all at once. When you use an all-at-once
approach, you use a single rules file to build the base
dimension and one or more attribute dimensions and to
associate the each attribute with the appropriate member of
the base dimension. 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.
• 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 a single step. You
need only to define the attribute associations in the rules file.
For a brief description of this process, see Associating
Attributes.
 • 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. You must use this approach
when you build numeric attribute dimensions that are
multilevel or that have members that represent different-
sized ranges.

The following sections describe how to build attribute dimensions:

• Building Attribute Dimensions

• Associating Attributes
• Updating Attribute Associations
• Working with Multilevel Attribute Dimensions
• Working with Numeric Ranges
• Reviewing the Rules for Building Attribute and Base
Dimensions

Building Attribute Dimensions

Before you build any attribute dimensions in a database, you must
define the attribute member name formats for the outline. For a
comprehensive discussion of assigning attribute member names, see
Setting Member Names in Attribute Dimensions.

You can build attribute dimensions in either of the following two ways:

• The same way that you build standard dimensions, as

described in Process for Data Loading and Dimension
Building.
• At the same time as you associate attributes with members of
the base dimension, as described in Associating Attributes.

Analytic Services does not support concurrent attribute association

with the Add as build methods.

When you define the rules file for building attribute dimensions, be
sure to 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. For a complete example of
a multilevel situation, see Working with Multilevel Attribute
Dimensions.

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?137, 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, Analytic Services associates the attribute 64 with the
500-10 member.

Figure 137: Rules File for Associating Attributes

You can have Analytic Services 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, for the base dimension, clear the Do Not Create Mbrs option. For
more information, see "Setting Member Properties" in the Essbase XTD
Administration Services Online Help.

When you are working with numeric ranges, you may need to build
attribute dimensions and perform associations in separate steps. For a
discussion and example of using separate steps, see Working with
Numeric Ranges.

The Caffeinated3,Product field in the example in Figure?137 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?137 associates attributes as shown in the outline in

Figure?138. The?members 500, 500-10, and 500-20 are new members
of the base dimension, Product. The member 64 is a new member of
the Ounces attribute dimension.

Figure 138: Associating Attributes

Updating Attribute Associations

You can also use the rules file shown in Figure?137 to change attribute
associations. Make sure that you allow association changes. In Data
Prep Editor, in the Dimension Build Settings tab of the Dimension Build
Settings dialog box, check "Allow Association Chgs" for the base
dimension. For more information, see "Setting Member Properties" in
the Essbase XTD Administration Services Online Help.
Working with Multilevel Attribute Dimensions
Multilevel, numeric, Boolean, and date attribute dimensions can have
duplicate level 0 members. For example, associated with a Product
dimension you can have a Size attribute dimension with two levels.
Level 1 categorizes sizes by men or by women. The level 0 members
(attributes) are the actual sizes. You can have a member named 8
under Women and member named 8 under Men.

When an attribute is part of a multilevel numeric, Boolean, or date

attribute dimension, the source data must include columns for all
generations or levels of the attribute dimension. In the rules file, you
must make copies of all fields that comprise the levels of the attribute
dimension. Define the first set of attribute fields to build the attribute
dimension. Define the second set of attribute fields to associate the
attributes with the appropriate base dimension members. To ensure
association with the correct attribute, indicate the parent field for the
attribute field by making a copy of the parent field and setting the
copy of the parent field as the field type Attribute Parent.

The position of the fields in the rules file is important.

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

Note: For brief discussions of and references to topics pertinent to

the following steps, see Setting Field Type Information, Copying
Fields, and Moving Fields.

1. In the rules file, in field 1 and field 2, define the attribute

dimension fields in the same way that you define standard
dimensions; specify type (level or generation), number, and
dimension name.
Analytic Services uses the 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?139 shows the fields of
the rules file at this stage.

Figure 139: Defining Multilevel Attribute Dimensions Before

Adding the Association Fields

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 Analytic Services
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 Analytic Services
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?Analytic Services 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?140, 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.

Figure 140: Source Data and Rules File for Building a Multilevel
Attribute Dimension

When you run a dimension build with the data shown in Figure?140,
Analytic Services builds the Size attribute dimension and associates its
members with the appropriate members of the base dimension.
Figure?141 shows the updated outline.

Figure 141: Multilevel Attribute Dimension

Working with Numeric Ranges
In many cases, you can use one rules file in a single dimension build
operation to dynamically build attribute dimensions for numeric ranges
and to associate the members of the base dimension with the ranges.
However, in the following situations you must use two rules files, one
to build the attribute dimension and one to associate the attributes
with the appropriate members of the base dimension:

• When the range size is different for different members. For

example, you can define small ranges for towns and cities
with smaller populations, larger ranges for mid-sized cities,
and ranges above 1,000,000 for cities with large populations.
• When the ranges are members of a multilevel attribute
dimension. For example, the Population attribute dimension
can have level 1 members that categorize the population
ranges as Towns, Cities, and Metropolitan Areas.

The Population attribute dimension shown in Figure?142 demonstrates

both situations. Population is a multilevel, numeric attribute dimension
with level 0 members representing ranges of different sizes.

Figure 142: Numeric Attribute Dimension with Different-Sized Ranges

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.
Building Attribute Dimensions that Accommodate
Ranges
First, create a rules file that uses the generation, level, or parent-child
build method to build the attribute dimension. In the rules file, be sure
to specify the following:

• The name of the attribute dimension and its associated base

dimension.
• The fields for building the attribute dimension. For a brief
discussion and references to pertinent topics, see Setting
Field Type Information.

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?142, 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?143.

Figure 143: Rules File for Building a Numeric Attribute Dimension with
Ranges
Figure?143 also shows how you can associate aliases with attributes.

Associating Base Dimension Members with Their

Range Attributes
After you build the numeric attribute dimension ranges, you need a
rules file to associate the members of the base dimension with their
attributes. The source data includes fields for the members of the base
dimension and fields for the data values that Analytic Services uses to
associate the appropriate Population attribute.

Define the rules file as shown in Figure?144.

Figure 144: Rules File for Associating Numeric Range Attributes

When you define the association field (for example, Population3,

Market) be sure to place the attribute members within a range. In
Data Prep Editor, in the Field Properties dialog box, on the Dimension
Building Properties tab, click the Ranges button. Select "Place attribute
members within a range."

Note: Figure?144 includes a city, Boston, whose population of

3,227,707 is outside the ranges of the attribute dimension in
Figure?142. (The ranges in Figure?142 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.
Analytic Services 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: After you associate members of the base dimension with
members of the attribute dimension, be aware that 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 member of
the attribute dimension 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 now 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.

Assuring the Validity of Associations

To ensure the validity of attribute associations, you must be careful to
select the correct dimension building options and to perform the builds
in the proper sequence.

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, you should make sure
that associations between attributes and base members are correct. To
ensure that the associations are correct, you can do one of the
following:

• 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 you can rebuild the
dimension with new data. In Data Prep Editor, on the Dimension
Building Properties tab in the Field Properties dialog box, click the
Ranges button. Select "Delete all members of this attribute
dimension." Analytic Services 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, for the base dimension you must select the
"Allow Association Chgs" option.

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.
Be sure to provide a value for the range size. In Data Prep Editor, on
the Dimension Building Properties tab in the Field Properties dialog
box, click the Ranges button and specify the range size for the
attribute dimension.

If Analytic Services 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
out-of-range values.

Consider the example, in Figure?142, where 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,
Analytic Services adds two members to the attribute dimension,
4000000 and 5000000, and associates the base member with the
5000000 attribute.

Figure 145: Dynamically Adding Attribute Range Members

When you add range members and base dimension members at the
same time, Analytic Services 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.

Reviewing the Rules for Building Attribute and Base Dimensions

The following list describes a few areas unique to defining and
associating attributes through dimension build.

Getting Ready

• Before running a dimension build, you must define the

attribute member name formats for the outline. For a
comprehensive discussion of assigning member names in
attribute dimensions, see Setting Member Names in Attribute
Dimensions.
• Defining new attribute dimensions in a rules file is different
from defining new standard dimensions in a rules file.

Defining Fields in Rules Files

Rules files that are used to build single-level attribute dimensions

require fewer field types than rules files that build and associate
members of multilevel attribute dimensions.

• 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. For a description of how to define fields, see
Associating Attributes.
• For multilevel attribute dimensions, Analytic Services 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. For a
description of how to handle multilevel attribute dimensions,
see Working with Multilevel Attribute Dimensions.

Controlling Adding New Attribute Members

When Analytic Services encounters attribute data values that are not
members of the attribute dimension, it automatically adds the values
as new members. To prevent adding new members to attribute
dimensions, do either of the following:

In the Dimension Build Settings dialog box, select the Do Not Create
Mbrs option for the attribute dimension. For more information, see
"Setting Member Properties" in the Essbase XTD Administration
Services Online Help.

Controlling Associations

Association to
How to Control the Association
Control

Making changes to In Data Prep Editor, on the Dimension

attribute associations Build Settings tab of the Dimension Build
Settings dialog box, select the Allow
Association Chgs option for the attribute
dimension. For more information, see
"Setting Member Properties" in the
Essbase XTD Administration Services
Online Help.

Enabling automatic In Data Prep Editor, on the Dimension

association of base Building Properties tab in the Field
members with Properties dialog box, click the Ranges
attributes that button and define the size of the range.
represent ranges of For a brief discussion of field types and
values references to pertinent topics, see Setting
Field Type Information.

Concurrent attribute Use any build method except the Add as

associations build methods. For information about
each build method, see Table?22.

Note: Because attributes are defined only in the outline, the data
load process does not affect them.
Building Shared
Members by Using a
Rules File
The data associated with a shared member comes from a real member
with the same name as the shared member. The shared member
stores a pointer to data contained in the real member; thus the data is
shared between the members and is stored only one time.

In the Sample Basic database, for example, the 100-20 (Diet Cola)
member rolls up into the 100 (Cola) family and into the Diet family.

Figure 146: Shared Members in the Sample Basic Database

You can share members among as many parents as you want. Diet
Cola has two parents, but you can define it to roll up into even more
parents.

You can share members at multiple generations in the outline. In

Figure?146, 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 in Figure?154.

Creating shared members at different generations in the outline is

easy in Outline Editor. However, creating shared members using
dimension build is a little more difficult. You must pick the build
method and format the data source carefully. The following sections
describe how to build shared members in the outline by using a data
source and a rules file.

Note: You should not create an outline in which a shared member

is located before the actual member with which it is associated.

Sharing Members at the Same Generation

Members that are shared at the same generation roll up into the same
branch. In the Sample Basic database, 100-20 (Diet Cola) is shared by
two parents. Both parents roll up into the same branch, that is, the
Product dimension, and both parents are at generation 2.

Figure 147: Members Shared at the Same Generation

This scenario is the simplest way to share members. You can share
members at the same generation by using any of these build methods.
These methods are discussed in the following sections:

• Using Generation References to Create Same Generation

Shared Members
• Using Level References to Create Same Generation Shared
Members
• Using Parent-Child References to Create Same Generation
Shared Members
Using Generation References to Create Same
Generation Shared Members
To create shared member parents at the same generation by using the
generation references build method, define the field type for the
parent of the shared members as DUPGEN. A duplicate generation is a
generation with shared members for children. Use the same GEN
number as the primary member.

For example, to create the Diet parent and share the 100-20, 200-20,
300-20, and 400-20 members, use the sample file, SHGENREF.TXT, and
set up the rules file so that the fields look like SHGENREF.RUL, shown in
Figure?148. Remember 100 is the Cola family, 200 is the Root Beer
family, 300 is the Cream Soda family, and the -20 after the family
name indicates a diet version of the soda.

Figure 148: Sample Generation Shared Member Rules File

The data source and rules file illustrated in Figure?148 build the
following tree:

Figure 149: Sample Generation Shared Member Rules Tree

Using Level References to Create Same Generation
Shared Members
To create shared members of the same generation by using the level
references build method, first make sure that the primary and any
secondary roll-ups are specified in one record. You can specify as
many secondary roll-ups as you want, as long as the roll-ups are all in
one record.

Define the field type for the shared member as LEVEL. Then enter the
level number. To create a shared member of the same generation, set
the level number of the secondary roll-up to have the same number of
levels as the primary roll-up. While processing the data source,
Analytic Services creates a parent at the specified level and inserts the
shared members under it.

For example, to create the shared 100-20 (Diet Cola), 200-20 (Diet
Root Beer), 300-20 (Diet Cream Soda), and 400-20 (Fruit Soda)
members in the Sample Basic database, use the sample file,
SHLEV.TXT, and set up the rules file so that the fields look like
SHLEV.RUL shown in Figure?150.

Figure 150: Sample Level Shared Member Rules File

The data source and rules file illustrated in Figure?150 build the
following tree:

Figure 151: Sample Level Shared Member Rules Tree

Using Parent-Child References to Create Same
Generation Shared Members
To create shared members of the same generation by using the
parent-child references build method, define the PARENT and CHILD
field types. Make sure that Analytic Services is set up to allow sharing
(clear Do Not Share in the Dimension Build Settings tab of the
Dimension Build Settings dialog box). When sharing is enabled,
Analytic Services automatically creates duplicate members under
a?new parent as shared members.

Figure 152: Sample Parent-Child Shared Members Rules File

The data source and rules file illustrated in Figure?152 build the
following tree:

Figure 153: Sample Parent-Child Shared Member Rules Tree

Sharing Members at Different Generations
Sometimes you want shared members to roll up into parents that are
at different generations in the outline. In Figure?154, for example, the
shared members roll?up into parents at generation 2 and at generation
3. This outline assumes that The Beverage Company (TBC) buys some
of its beverages from outside vendors. In this case, it buys 200-20
(Diet Root Beer) from a vendor named Grandma's.

Figure 154: Members Shared at Different Generations

To share members across parents at different generations in the

outline, use one of these build methods. The methods are described in
the following sections:

• Using Level References to Create Different Generation Shared

Members
• Using Parent-Child References to Create Different Generation
Shared Members
Using Level References to Create Different
Generation Shared Members
To create shared members of different generations by using the level
references build method, first make sure that both primary and
secondary roll-ups are specified in one record. You can specify as
many secondary roll-ups as you want, as long as the roll-ups are all in
one record.

Define the field type for the shared member as LEVEL. Then enter the
level number. While processing the data source, Analytic Services
creates a parent at the specified level and inserts the shared members
under it.

For example, to share the products 100-20, 200-20, and 300-20 with
a parent called Diet and two parents called TBC (The Beverage
Company) and Grandma's, use the sample data file and the rules file
in Figure?155.

Figure 155: Level References Sample Rules File for Shared Members at
Different Generations

The data source and rules file illustrated in Figure?155 build the tree
illustrated in Figure?154.

Using Parent-Child References to Create Different

Generation Shared Members
To create shared members at the different generation using the
parent-child references build method, define the PARENT and CHILD
field types. Make sure that Analytic Services is set up to allow sharing
(clear Do Not Share in the Dimension Build Settings tab of the
Dimension Build Settings dialog box). When sharing is enabled,
Analytic Services automatically creates duplicate members under
a?new parent as shared members.
Figure 156: Parent-Child References Sample Rules File for Shared
Members at Different Generations

The data source and rules file illustrated in Figure?156 build the tree
illustrated in Figure?154.

Sharing Non-Leaf Members

Sometimes you want to share non-leaf members (members that are
not at the lowest generation). In Figure?157 for example, 100, 200,
and 300 are shared by TBC and Grandma's. This outline assumes that
TBC (The Beverage Company) buys some of its product lines from
outside vendors. In this case, it buys 200 (all root beer) from a vendor
named Grandma's.

Figure 157: Non-Leaf Members Shared at Different Generations

To share non-leaf members, use one of these build methods. These
methods are described in the following sections:

• Using Level References to Create Non-Leaf Shared Members

• Using Parent-Child References to Create Non-Leaf Shared
Members

Using Level References to Create Non-Leaf Shared

Members
To create shared non-leaf members by using the level references build
method, first make sure that both primary and secondary roll-ups are
specified in one record. You can specify as many secondary roll-ups as
you want, as long as the roll-ups are all in one record.

Define the field type for the parent of the shared member as duplicate
level (DUPLEVEL). Then enter the level number. To create a shared
member of the same generation, set the level number of the
secondary roll-up to have the same number of levels as the primary
roll-up. While processing the data source, Analytic Services creates a
parent at the specified level and inserts the shared members under it.

For example, to share the product lines 100, 200, and 300 with a
parent called Soda and two parents called TBC and Grandma's, use the
sample data file and rules file shown in Figure?158. This data source
and rules file work only if the Diet, TBC, and Grandma's members exist
in the outline. The DUPLEVEL field is always created as a child of the
dimension (that is, at generation 2), unless the named level field
already exists in the outline.

Figure 158: Level References Sample Rules File for Non-Leaf Shared
Members at Different Generations

The data source and rules file illustrated in Figure?158 build the tree
illustrated in Figure?157.
Using Parent-Child References to Create Non-Leaf
Shared Members
To create shared non-leaf members at the same generation using the
parent-child references build method, define the PARENT and CHILD
field types. Make sure that Analytic Services is set up to allow sharing
(clear Do Not Share in the Dimension Build Settings tab of the
Dimension Build Settings dialog box). When sharing is enabled,
Analytic Services automatically creates duplicate members under
a?new parent as shared members.

The parent-child references build method is the most versatile for

creating shared members. It does not have any restrictions on the
position of the shared members in the outline, unlike the generation
references and level references build methods.

Figure 159: Parent-Child Sample Rules File for Non-Leaf Shared

Members

The data source and rules file illustrated in Figure?159 build the tree
illustrated in Figure?157.
Building Multiple Roll-Ups by Using Level References
To enable the retrieval of totals from multiple perspectives, you can
also put shared members at different levels in the outline. Use the
level references build method. The rules file, LEVELMUL.RUL, in
Figure?160 specifies an example of build instructions for levels in the
Product dimension.

Figure 160: Rules File Fields Set to Build Multiple Roll-Ups Using Level
References

Because the record is so long, this second graphic shows the rules file
after it has been scrolled to the right to show the extra members:

Figure 161: Scrolled Window

When you run the dimension build using the data in Figure?160,
Analytic Services builds the following member tree:

Figure 162: Multiple Roll-Ups

This example enables analysis not only by package type (Cans), but
also by packaging material; for example, analysis 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. Consider
creating a multilevel attribute dimension for package type with Steel
and Aluminum as level 0 members under Can. For a discussion of
outline design guidelines, see Analyzing Database Design.

Creating Shared Roll-Ups from Multiple Data Sources

In many situations, the data for a dimension is in two or more data
sources. If you are building dimensions from more than one data
source and want to create multiple roll-ups, load the first data source
using the most appropriate build method and then load all other data
sources using the parent-child references build method. Make sure
that Analytic Services is set up to allow sharing (clear Do Not Share in
the Dimension Build Settings tab of the Dimension Build Settings
dialog box).

For example, using the Product data source in Figure?163:

Figure 163: Soft Drinks Data Source

"Soft Drinks"   Cola
"Soft Drinks"   "Root Beer"
Cola            TBC
"Root Beer"     Grandma's 
 

Analytic Services builds the tree illustrated in Figure?164:

Figure 164: Soft Drinks Tree

Then load the second data source, illustrated in Figure?165, to relate
the products to the vendors using the parent-child build method. Make
sure that Analytic Services is set up to allow sharing.

Figure 165: Second Shared Roll-Ups Data Source

Vendor   TBC
Vendor   Grandma's 
 

Analytic Services builds the tree illustrated in Figure?166:

Figure 166: Shared Roll-Ups Tree

Calculating Analytic
Services Databases
This chapter explains the basic concept of multidimensional database
calculation and provides information about how to calculate an Analytic
Services database.

This chapter includes the following sections:

• About Database Calculation

• About Multidimensional Calculation Concepts
• Setting the Default Calculation
• Calculating Databases
• Parallel and Serial Calculation
• Security Considerations
About Database
Calculation
A database contains two types of values. It contains the values that
you enter, which are called input data, and the values that are
calculated from the input data.

Consider the following examples:

• You enter regional sales figures for a variety of products. You

calculate the total sales for each product.
• 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.

Analytic Services offers two ways that you can calculate a database:

• Outline calculation
• Calculation script calculation

Which way you choose depends on the type of calculation that you
want to do.

Outline Calculation
Outline calculation is the simplest method of calculation. Analytic
Services 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?167 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 167: Relationship Between Members of the Market Dimension

Figure?168 shows the Scenario dimension from the Sample Basic

database. The Variance and Variance % members are calculated by
using the formulas attached to them.

Figure 168: Calculation of Variance and Variance %

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?can use dynamic
calculations to calculate data at retrieval time. For a comprehensive
discussion of dynamic calculation, see Dynamically Calculating Data
Values.

Calculation Script Calculation

Calculation script calculation is the second method of calculation. Using
a calculation script, you can choose exactly how to calculate a
database. For example, you can calculate part of a database or copy
data values between members.

A calculation script contains a series of calculation commands,

equations, and formulas. For example, the following calculation script
increases the actual marketing expenses in the New York region by
5%.
FIX (Actual, "New York")
?????Marketing = Marketing *1.05;
ENDFIX; 
 

For a comprehensive discussion of calculation scripts, see Developing

Calculation Scripts.

About Multidimensional
Calculation Concepts
For an illustration of the nature of multidimensional calculations,
consider the following, simplified database:

Figure 169: Calculating a Multidimensional Database

The database has three dimensions-Accounts, Time, and Scenario.

The Accounts dimension has four members:

• Sales and COGS are input values.

• Margin = Sales - COGS.
• Margin% = Margin % Sales (Margin as a percentage of
Sales).

The Time dimension has four quarters. The example displays only the
members in Qtr1-Jan, Feb, and Mar.
The Scenario dimension has two child members-Budget for budget
values and Actual for actual values.

An intersection of members (one member on each dimension)

represents a data value. Our example has three dimensions; therefore,
the dimensions and data values in the database can be represented as
a cube, as shown in Figure?170:

Figure 170: Three-Dimensional Database

As shown in Figure?171, when you refer to Sales, you are referring to

a slice of the database containing eight Sales values.

Figure 171: Sales, Actual, Budget Slice of the Database

As shown in Figure?172, when you refer to Actual Sales, you are

referring to four Sales values:

Figure 172: Actual, Sales Slice of the Database

To refer to a specific data value in a multidimensional database, you
need to specify each member on each dimension. A data value is
stored in a single cell in the database. In Figure?173, the cell
containing the data value for Sales, Jan, Actual is shaded.

In Analytic Services, member combinations are denoted by a cross-

dimensional operator. The symbol for the cross-dimensional operator is
->. So Sales, Jan, Actual is written Sales?->?Jan?->?Actual.

Figure 173: Sales, Jan, Actual Slice of the Database

When Analytic Services calculates the formula "Margin% = Margin %

Sales," it takes each Margin value and calculates it as a percentage of
its corresponding Sales value.

Analytic Services 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.
6. Analytic Services continues cycling through the database until
it has calculated Margin% for every combination of members
in the database.

For a comprehensive discussion of how Analytic Services calculates a

database, see Defining Calculation Order.

Setting the Default

Calculation
By default, the calculation for a database is a CALC ALL of the
database outline. CALC ALL consolidates all dimensions and members
and calculates all formulas in the outline.

However, you can specify any calculation script as the default database
calculation. Thus, you can assign a frequently-used script to the
database rather than loading the script each time you want to perform
its calculation. Also, if you want a calculation script to work with
calculation settings defined at the database level, you must set the
calculation script as the default calculation.

Use any of the following methods to set the default calculation:

Tool Topic Location

Administration Setting the Default Essbase XTD

Services Calculation Administration
Services Online Help

MaxL alter database Technical Reference

ESSCMD SETDEFAULTCALCFILE Technical Reference

Calculating Databases
If you have Calculation permissions, you can calculate a database.
When you use Essbase 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. For instructions, see "Calculating Databases" in
Essbase XTD Administration Services Online Help.

Use any of the following methods to calculate a database:

Tool Topic Location

Administration Calculating Essbase XTD

Services Databases Administration Services
Online Help

MaxL execute Technical Reference

calculation

ESSCMD CALC, CALCDEFAULT, Technical Reference

and CALCLINE

Spreadsheet Calculating a Spreadsheet Add-in

Add-in Database Online Help

Canceling Calculations
To stop a calculation before Analytic Services completes it, click the
Cancel button while the calculation is running.

When you cancel a calculation, Analytic Services performs one of the

following operations:

• Reverts all values to their previous state

• Retains any values calculated before the cancellation
How Analytic Services handles the cancellation depends on the Analytic
Services Kernel Isolation Level settings. For a description of these
settings, see Understanding Isolation Levels.

Parallel and Serial

Calculation
Analytic Services now supports parallel calculation in addition to serial
calculation. Serial calculation, the default, means that all steps in a
calculation run on a single thread. Each task is completed before the
next is started. Parallel calculation means that the Analytic Services
calculator can analyze a calculation, and, if appropriate, assign tasks
to multiple CPUs (up to 4).

For a comprehensive discussion of parallel calculation, including how to

determine whether Analytic Server should use parallel calculation, see
Using Parallel Calculation.

Security Considerations
In order to calculate a database, you must have Calculate permissions
for the database outline. If you have calculate permissions, you can
calculate any value in the database. With calculate permissions, you
can calculate a value even if a security filter denies you read and
update permissions. Careful consideration should be given to providing
users with calculate permissions.

For information on providing users with calculate permissions and on

security filters, see Managing Security for Users and Applications.

Developing Formulas
This chapter explains how to develop and use formulas to calculate a
database. It provides detailed examples of formulas, which you may
want to adapt for your own use. For more examples, see Reviewing
Examples of Formulas.
This chapter includes the following topics:

• Understanding Formulas
• Understanding Formula Calculation
• Understanding Formula Syntax
• Reviewing the Process for Creating Formulas
• Displaying Formulas
• Composing Formulas
• Estimating Disk Size for a Calculation
• Using Formulas in Partitions

Using formulas can have significant implications for calculation

performance. After reading this chapter, use the information in
Optimizing Calculations to design and create formulas optimized for
performance.

For information on using formulas with Hybrid Analysis, see Using

Formulas with Hybrid Analysis.

Understanding
Formulas
Formulas calculate relationships between members in a database
outline. You can use formulas in two ways:

• Apply them 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 kilobytes. For instructions, see
Composing Formulas.
• Place them in a calculation script. Use this method if you need
to control database calculations carefully. For?more
information, see Using Formulas in a Calculation Script.

The following figure shows the Measures dimension from the Sample
Basic database. The Margin %, Profit %, and Profit per Ounce
members are calculated using the formulas applied to them.

Figure 174: Calculation of Margin %, Profit %, and Profit per Ounce

Analytic Services provides a comprehensive set of operators and
functions, which you can use to construct formula calculations on a
database. The rest of this section provides a description of the
elements you can place in a formula, and provides basic information
about formula calculation and syntax:

• Operators
• Functions
• Dimension and Member Names
• Constant Values
• Non-Constant Values

Operators
The following table shows the types of operators you can use in
formulas:

Table 23: Descriptions of Operator Types

Operator
Description
Type

Mathematical Perform common arithmetic operations. For

example, you can add, subtract, multiply, or
divide values. For a complete list of the
mathematical operators, see the Technical
Reference.

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. For a list of the conditional operators,
see the Technical Reference. For information on
writing conditional formulas, see Conditional
Tests.

Cross- Point to the data values of specific member

dimensional combinations. For example, point to the sales
value for a specific product in a specific region.
 For examples of how to use the cross-
dimensional operator, see Working with Member
Combinations across Dimensions.

For information about using operators with #MISSING, zero, and other

values, see the Analytic Services Functions section in the Technical
Reference.

Functions
Functions are predefined routines that perform specialized calculations
and return sets of members or data values. The following table shows
the types of functions you can use in formulas.

For detailed examples of formulas, see Reviewing Examples of

Formulas.

Table 24: Descriptions of Function Types ?

Function Type Description

Boolean Provide a conditional test by returning either a

TRUE (1) or FALSE (0) value. For example, you
can use the @ISMBR function to determine
whether the current member is one that you
specify.

Mathematical Perform specialized mathematical calculations.

For example, you can use the @AVG function to
return the average value of a list of members.

Relationship Look up data values within a database during a

calculation. For example, you can use the
@ANCESTVAL function to return the ancestor
values of a specified member combination.

Range Declare a range of members as an argument to

another function or command. For example, you
can use the @SUMRANGE function to return the
sum of all members that lie within a specified
range.
Financial Perform specialized financial calculations. For
example, you can use the @INTEREST function
to calculate simple interest or the @PTD
function to calculate period-to-date values.

Member Set Generate a list of members that is based on a

specified member. For example, you can use the
@ICHILDREN function to return a specified
member and its children.

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

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.

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.

Date and Time Use date and time characteristics in calculation

formulas. For example, you can use the
@TODATE function to convert date strings to
numbers that can be used in calculation
formulas.

Miscellaneous This type provides two different kinds of

functionality:
• You can specify calculation modes that
Analytic Services is to use to calculate
a formula-cell, block, bottom-up, and
 top-down
• You can manipulate character strings
for member and dimension names; for
example, to generate member names
by adding a character prefix to a name
or removing a suffix from a name, or
by passing the name as a string.

Custom- This type enables you to perform functions that

Defined you develop for calculation operations. These
Functions custom-developed functions are written in the
Java programming language and are called by
the Analytic Services calculator framework as
external functions.

For a complete list of operators, functions, and syntax, see the

Technical Reference.

Note: Abbreviations of functions are not supported. Some

commands may work in an abbreviated form, but if there is another
function with a similar name, Analytic Services may use the wrong
function. Use the complete function name to ensure correct results.

Dimension and Member Names

You can include dimension and member names in a formula, as
illustrated in the following example:

Scenario
100­10
Feb 
 

Constant Values
You can assign a constant value to a member:

California = 120; 
 
In this formula, California is a member in a sparse dimension and 120
is a constant value. Analytic Services 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 FIX as described in Constant Values Assigned to Members in a
Sparse Dimension.

Non-Constant 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 Analytic Services is enabled to create blocks on
equations.

For example, to create blocks for West that didn't exist prior to running
the calculation, you need to enable Create Blocks on Equations for this
formula:

West = California + 120; 
 

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.

To enable the Create Blocks on Equations feature for all calculation

scripts for a specific database, use any of the following methods:

Tool Topic Location

Administration Enabling Create Essbase XTD

Services Blocks on Equations Administration Services
Online Help

MaxL alter database Technical Reference

ESSCMD SETDBSTATE Technical Reference

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 CREATEBLOCKEQ ON|OFF calculation
command as described in Non-Constant Values Assigned to Members
in a Sparse Dimension.

Understanding Formula
Calculation
For formulas applied to members in a database outline, Analytic
Services calculates formulas when you do the following:

• Run a default (CALC ALL) calculation of a database.

• Run a calculation script that calculates the member containing
the formula; for example, a CALC DIM of the dimension
containing the member, or the member itself. For information
about how to develop calculation scripts and how to use them
to control how Analytic Services calculates a database, see
Developing Calculation Scripts.

For a formula in a calculation script, Analytic Services calculates the

formula when it occurs in the calculation script.

If a formula is associated with a dynamically calculated member,

Analytic Services 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. For an explanation of how you calculate
data values dynamically and how you benefit from doing so, see
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 Analytic Services has to
interrupt the regular calculation to perform the dynamic calculation.

You cannot use substitution variables in formulas that you apply to the
database outline. For an explanation of how substitution variables can
be used, see Using Substitution Variables.
Understanding Formula
Syntax
When you create member formulas, make sure the formulas follow
these rules:

• End each statement in the formula with a semicolon (;). For

example,
Margin % Sales;
• Enclose a member name in double quotation marks (" ") if the
member name meets any of the following conditions:
o Contains spaces; for example,

"Opening Inventory" = "Ending Inventory" - Sales +

Additions;
o Is the same as an operator or function name. See the
Technical Reference for a list of operators and functions.
o Includes any non-alphanumeric character; for example,
hyphens (-), asterisks (*), and slashes (/).
o Is all numeric or starts with one or more numerals; for
example, "100" or "10Prod"
For a complete list of member names that must be
enclosed in quotation marks, see Understanding the Rules
for Naming Dimensions and Members.
• End each IF statement in a formula with an ENDIF statement.

For example, the following formula contains a simple IF... ENDIF

statement. You can apply this formula to the Commission
member in a database outline:
IF(Sales < 100)
???Commission = 0;
ENDIF;

If you are using an IF statement nested within another IF

statement, end each IF with an ENDIF, as illustrated in the
following 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, as illustrated in the following 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 in between) rather

than ELSEIF (one word) in a formula, you must supply an
ENDIF for the IF statement.

• Although ending ENDIF statements with a semicolon (;) is not

required, it is good practice to follow each ENDIF statement in
a formula with a semicolon.

When writing formulas, you can check the syntax using the Formula
Editor syntax checker. For a comprehensive discussion, including
examples, of the main types of formulas, see Checking Formula
Syntax.

For detailed information on syntax for Analytic Services functions and

commands, see the Technical Reference.

Reviewing the Process

for Creating Formulas
You use Formula Editor to create formulas. Formula Editor is a tab in
the Member Properties dialog box in Outline Editor. You can type the
formulas directly into the formula text area, or you can use the
Formula Editor user interface features to create the formula.

Formulas are plain text. If required, you can create a formula in the
text editor of your choice and paste it into Formula Editor.

To create a formula, follow this process:

1. In Outline Editor, select the member to which to apply the

formula.
2. Open Formula Editor.
For more information, see "Creating and Editing Formulas in
Outlines" in the Essbase XTD Administration Services Online
Help.
3. Enter the formula text.
For more information on entering the formula text in the Formula
Editor, see?"Creating and Editing Formulas in Outlines" in the
Essbase XTD Administration Services Online Help. For more
information about composing the formula itself, see Composing
Formulas.
4. Check the formula syntax.
For more information, see Checking Formula Syntax.
5. Save the formula.
For more information, see "Creating and Editing Formulas in
Outlines" in the Essbase XTD Administration Services Online
Help.
6. Save the outline.
For more information, see "Saving Outlines" in the Essbase XTD
Administration Services Online Help.

Displaying Formulas
To display an existing formula, use any of the following methods:

Tool Topic Location

Administration Creating and Editing Essbase XTD
Services Formulas in Outlines Administration Services
Online Help

ESSCMD GETMBRCALC Technical Reference

MaxL query database Technical Reference

Composing Formulas
The following sections discuss and give examples of the main types of
formulas:

• Basic Equations
• Conditional Tests
• Examples of Conditional Tests
• Value-Related Formulas
• Member-Related Formulas
• Formulas That Use Various Types of Functions

For detailed examples of formulas, see Reviewing Examples of

Formulas.

Before writing formulas, review the guidelines in Understanding

Formula Syntax.

Basic Equations
You can apply a mathematical operation to a formula to create a basic
equation. For example, you can apply the following formula to the
Margin member in Sample Basic.

Sales ­ COGS; 
 

In a calculation script, you define basic equations as follows:

Member = mathematical operation;  
 
where Member is a member name from the database outline and
mathematical operation is any valid mathematical operation, as
illustrated in the following example:

Margin = Sales ­ COGS; 
 

Whether the example equation is in the database outline or in a

calculation script, Analytic Services cycles through the database
subtracting the values in COGS from the values in Sales and placing
the results in Margin.

As another example, you can apply the following formula to a Markup

member:

(Retail ­ Cost) % Retail; 
 

In a calculation script, this formula is as follows:

Markup = (Retail ­ Cost) % Retail; 
 

In this example, Analytic Services 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.

For an explanation of the nature of multidimensional calculations, see

About Multidimensional Calculation Concepts

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). You can use the ELSE and ELSEIF commands to
specify alternative actions if the test returns FALSE (0). 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).
For information about and examples of the syntax of the IF and ENDIF
commands, see Understanding Formula Syntax.

When you use a conditional formula in a calculation script, you must

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.

You use Boolean functions to determine which formula to use. The

decision is based on the characteristics of the current member
combination. For example, you?might want to restrict a certain
calculation to the members in the Product dimension that contain input
data. In this case, you 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).

You can use the following Boolean functions to specify conditions.

Use This
Information You Need To Find
Function

The current member has a specified accounts @ISACCTYPE

tag (for example, an Expense tag)

The current member is an ancestor of the @ISANCEST

specified member

The current member is an ancestor of the @ISIANCEST

specified member, or the specified member
itself

The current member is a child of the specified @ISCHILD

member

The current member is a child of the specified @ISICHILD

member, or the specified member itself
The current member is a descendant of the @ISDESC
specified member

The current member is a descendant of the @ISIDESC

specified member, or the specified member
itself

The current member of the specified dimension @ISGEN

is in the generation specified

The current member of the specified dimension @ISLEV

is in the level specified

The current member matches any of the @ISMBR

specified members

The current member is the parent of the @ISPARENT

specified member

The current member is the parent of the @ISIPARENT

specified member, or the specified member
itself

The current member (of the same dimension @ISSAMEGEN

as the specified member) is in the same
generation as the specified member

The current member (of the same dimension @ISSAMELEV

as the specified member) is in the same level
as the specified member

The current member is a sibling of the @ISSIBLING

specified member

The current member is a sibling of the @ISISIBLING

specified member, or the specified member
itself

A specified UDA (user-defined attribute) exists @ISUDA

for the current member of the specified
dimension
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 Analytic Services calculates a database, see
Developing Calculation Scripts. For information on individual Analytic
Services functions and calculation commands, see the Technical
Reference.

Examples of Conditional Tests

You can apply the following formula to a Commission member in the
database outline. In the first example, the formula calculates
commission at 1% of sales if the sales are greater than 500000:

IF(Sales > 500000)
Commission = Sales * .01;
ENDIF; 
 

If you place the formula in a calculation script, you need to associate

the formula with the Commission member as follows:

Commission(IF(Sales > 500000)
Commission = Sales * .01;
ENDIF;) 
 

Analytic Services cycles through the database, performing these

calculations:

1. The IF statement checks to see if the value of Sales for the

current member combination is greater than 500000.
2. If Sales is greater than 500000, Analytic Services multiplies
the value in Sales by 0.01 and places the result in
Commission.

In the next example, the formula tests the ancestry of the current
member and then applies the appropriate Payroll calculation formula.
IF(@ISIDESC(East) OR @ISIDESC(West))
Payroll = Sales * .15;
ELSEIF(@ISIDESC(Central))
Payroll = Sales * .11;
ELSE
Payroll = Sales * .10;
ENDIF; 
 

If you place the formula in a calculation script, you need to associate

the formula with the Payroll member as follows:

Payroll(IF(@ISIDESC(East) OR @ISIDESC(West))
Payroll = Sales * .15;
ELSEIF(@ISIDESC(Central))
Payroll = Sales * .11;
ELSE
Payroll = Sales * .10;
ENDIF;) 
 

Analytic Services cycles through the database, performing the

following calculations:

1. The IF statement uses the @ISIDESC function to check if the

current member on the Market dimension is a descendant of
either East or West.
2. If the current member on the Market dimension is a
descendant of East or West, Analytic Services multiplies the
value in Sales by 0.15 and moves on to the next member
combination.
3. If the current member is not a descendant of East or West,
the ELSEIF statement uses the @ISIDESC function to check if
the current member is a descendant of Central.
4. If the current member on the Market dimension is a
descendant of Central, Analytic Services multiplies the value
in Sales by 0.11 and moves on to the next member
combination.
 5. If the current member is not a descendant of East, West, or
Central, Analytic Services multiplies the value in Sales by
0.10 and moves on to the next member combination.

For information on the nature of multidimensional calculations, see

About Multidimensional Calculation Concepts. For information on the
@ISIDESC function, see the Technical Reference.

Value-Related Formulas
Use this section to find information about formulas related to values:

• Using Interdependent Values

• Calculating Variances or Percentage Variances Between Actual
and Budget Values
• Allocating Values
• Using Member Relationships to Look Up Values
• Using Substitution Variables

Using Interdependent Values

Analytic Services optimizes calculation performance by calculating
formulas for?a?range of members in the same dimension at the same
time. However, some formulas require values from members of the
same dimension, and Analytic Services may not yet have calculated
the required values.

A good example is that of cash flow, in which the opening inventory is

dependent on the ending inventory from the previous month.

In Sample Basic, the Opening Inventory and Ending Inventory values

need to be calculated on a month-by-month basis.

. Jan 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 required calculation is as follows:

1. January Ending   = January Opening ­ Sales + Additions 
2. February Opening = January Ending 
3. February Ending  = February Opening ­ Sales + Additions 
4. March Opening    = February Ending 
5. March Ending     = March Opening ­ Sales + Additions  
 

You can calculate the required results by applying interdependent,

multiple equations to a single member in the database outline.

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 need to associate

the formula with the Opening Inventory member as follows:

"Opening Inventory" (IF(NOT @ISMBR (Jan))

"Opening Inventory" = @PRIOR("Ending Inventory");
ENDIF;
"Ending Inventory" = "Opening Inventory" - Sales + Additions;)

Analytic Services cycles through the months, performing the following

calculations:

• The IF statement and @ISMBR function check that the current

member on the?Year dimension is not Jan. This step is
 necessary because the Opening Inventory value for Jan is an
input value.
• If the current month is not Jan, the @PRIOR function obtains
the value for the Ending Inventory for the previous month.
This value is then allocated to the Opening Inventory of the
current month.
• The Ending Inventory is calculated for the current month.

Note: To calculate the correct results, it is necessary to place the

above formula on a single member, Opening Inventory. If you place
the formulas for Opening Inventory and Ending Inventory on their
separate members, Analytic Services 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.

Calculating Variances or Percentage Variances

Between Actual and Budget Values
You can use the @VAR and @VARPER functions to calculate a variance
or percentage variance between budget and actual values.

You may want the variance to be positive or negative, depending on

whether you are calculating variance for members on the accounts
dimension that are expense or non-expense items:

• Expense items. You want Analytic Services to show a positive

variance if the actual values are lower than the budget values.
For example, you want Analytic Services to show a positive
variance if actual costs are lower than budgeted costs.
• Non-expense items. You want Analytic Services to show a
negative variance if the actual values are lower than the
budget values. For example, you want Analytic Services to
show a negative variance if actual sales are lower than
budgeted sales.

By default, Analytic Services assumes that members are non-expense

items and calculates the variance accordingly.

To tell Analytic Services that a member is an expense item, use this

procedure:
• In Outline Editor, select the member.
 The member must be on the dimension tagged as accounts.
• Open Formula Editor.

See "Creating and Editing Formulas in Outlines" in the Essbase

XTD Administration Services Online Help.
• Tag the member as an expense item. See Setting Variance
Reporting Properties.
When you use the @VAR or @VARPER functions, Analytic
Services shows a positive variance if the actual values are lower
than the budget values.
For example, in Sample Basic, the children of Total Expenses are
expense items. The Variance and Variance % members of the
Scenario dimension calculate the variance between the Actual
and Budget values.
Figure 175: Sample Basic Showing Expense Items

Allocating Values
You can allocate values that are input at the parent level across child
members in the same dimension or in different dimensions by using
the following allocation functions.

Allocated Values Function To

 Use
Values from a member, cross-dimensional member, or @ALLOCATE
value across a member list within the same dimension. The
allocation is based on a variety of specified criteria.
Values from a member, cross-dimensional member, or @MDALLOCATE
value across multiple dimensions. The allocation is based
on a variety of specified criteria.

Note: For examples of calculation scripts using the @ALLOCATE and

@MDALLOCATE functions, see Allocating Values Within or Across
Dimensions and the Technical Reference.

Forecasting Values
You can manipulate data for the purposes of smoothing data,
interpolating data, or calculating future values by using the following
forecasting functions.

Function To
Data Manipulation
Use
To apply a moving average to a data set and replace each term @MOVAVG
in the list with a trailing average. This function modifies the
data set for smoothing purposes.
To apply a moving maximum to a data set and replace each @MOVMAX
term in the list with a trailing maximum. This function
modifies the data set for smoothing purposes.
To apply a moving median to a data set and replace each term @MOVMED
in the list with a trailing median. This function modifies the
data set for smoothing purposes.
To apply a moving minimum to a data set and replace @MOVMIN
each?term in the list with a trailing minimum. This function
modifies the data set for smoothing purposes.
To apply a moving sum to a data set and replace each term @MOVSUM
with a trailing sum. This function modifies the data set for
smoothing purposes.
To apply a moving sum to a data set and replace each term @MOVSUMX
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.
To apply a smoothing spline to a set of data points. A spline is @SPLINE
a mathematical curve that is used to smooth or?interpolate
data.
To calculate future values and base the calculation on curve- @TREND
fitting to historical values.

For information about specific Analytic Services functions, see the

Technical Reference.

Using Member Relationships to Look Up Values

You can use the member combination that Analytic Services is
currently calculating to look up specific values. These functions are
referred to as relationship functions.

Look-up Value Function To Use

The ancestor values of the specified member @ANCESTVAL
combination
The numeric value of the attribute from the specified @ATTRIBUTEVAL
numeric or date attribute dimension associated with the
current member
The text value of the attribute from the specified text @ATTRIBUTESVAL
attribute dimension associated with the current member
The value (TRUE or FALSE) of the attribute from the @ATTRIBUTEBVAL
specified Boolean attribute dimension associated with
the current member
The generation number of the current member @CURGEN
combination for the specified dimension
The level number of the current member combination @CURLEV
for the specified dimension
The generation number of the specified member @GEN

The level number of the specified member @LEV

The ancestor values of the specified member @MDANCESTVAL
combination across multiple dimensions
The shared ancestor values of the specified member @SANCESTVAL
combination
The parent values of the specified member combination @PARENTVAL

The parent values of the specified member combination @MDPARENTVAL

across multiple dimensions
The shared parent values of the specified member @SPARENTVAL
combination
A data value from another database to be used for @XREF
calculation of a value from the current database

For information about specific Analytic Services functions, see the

Technical Reference.

Using Substitution Variables

Substitution variables act as placeholders for information that changes
regularly; for example, time period information. You can use
substitution variables in formulas that you include in a calculation
script. You cannot use substitution variables in formulas that you apply
to the database outline.

When you run a calculation script, Analytic Services replaces the

substitution variable with the value you have assigned to it. You can
create and assign values to substitution variables using Essbase
Administration Services or ESSCMD.

You can set substitution variables at the server, application, and

database levels. Analytic Services must be able to access the
substitution variable from the application and database on which you
are running the calculation script.

For information on creating and assigning values to substitution

variables, see Using Substitution Variables.

To use a substitution variable in a calculation script, type an

ampersand (&) followed by the substitution variable name.
Analytic Services treats any text string preceded by & as a substitution
variable.

For example, assume that the substitution variable UpToCurr is defined

as Jan:Jun. You can use the following @ISMBR function as part of a
conditional test in a calculation script:

@ISMBR(&UpToCurr) 
 

Before Analytic Services runs the calculation script, it replaces the

substitution variable, as follows:

@ISMBR(Jan:Jun) 
 

Member-Related Formulas
This section provides information you need to create formulas that
refer to members:

• Specifying Member Lists and Ranges

• Generating Member Lists
• Manipulating Member Names
• Working with Member Combinations across Dimensions

Specifying Member Lists and Ranges

In some functions you may need to specify more than one member, or
you may need to specify a range of members. For example, the
@ISMBR function tests to see if a member that is currently being
calculated matches any of a list or range of specified members. You
can specify members using the following syntax:

Member List or Range Syntax

A single member The member name. For example:
Mar2001

A list of members A comma-delimited (,) list of

member names. For example:
 Mar2001, Apr2001, May2001

A range of all members at the same The two defining member names
level, between and including the separated by a colon (:). For
two defining members example: Jan2000:Dec2000

A range of all members in the same The two defining member names
generation, between and including separated by two colons (::). For
the two defining members example: Q1_2000::Q4_2000

A function-generated list of For a list of member list contents

members or a range of members and corresponding functions, see
Generating Member Lists.

A combination of ranges and list Separate each range, list, and

function with a comma (,). For
example:
Q1_97::Q4_98, FY99, FY2000
or
@SIBLINGS(Dept01),
Dept65:Dept73, Total_Dept

If you do not specify a list of members or a range of members in a

function that requires either, Analytic Services uses the level 0
members of the dimension tagged as time. If no dimension is tagged
as time, Analytic Services displays an error message.

Generating Member Lists

You can generate member lists that are based on a specified member
by using the these member set functions.

Contents of Member List Function

All ancestors of the specified member, including @ALLANCESTORS
ancestors of the specified member as a shared member.
This function does not include the specified member.
All ancestors of the specified member, including @IALLANCESTORS
ancestors of the specified member as a shared member.
This function includes the specified member.
The ancestor of the specified member at the specified @ANCEST
generation or level.
All ancestors of the specified member (optionally up to @ANCESTORS
the specified generation or level) but not the specified
member.
All ancestors of the specified member (optionally up to @IANCESTORS
the specified generation or level) including the
specified member.
All children of the specified member, but not including @CHILDREN
the specified member.
All children of the specified member, including the @ICHILDREN
specified member.
The current member being calculated for the specified @CURRMBR
dimension.
All descendants of the specified member (optionally up @DESCENDANTS
to the specified generation or level), but not the
specified member nor descendants of shared members.
All descendants of the specified member (optionally @IDESCENDANTS
up?to the specified generation or level), including the
specified member, but not descendants of shared
members.
All descendants of the specified member (optionally up @RDESCENDANTS
to the specified generation or level), including
descendants of shared members, but not the specified
member.
All descendants of the specified member (optionally @IRDESCENDANTS
up?to the specified generation or level), including the
specified member and descendants of shared members.
All members of the specified generation in the @GENMBRS
specified dimension.
All members of the specified level in the specified @LEVMBRS
dimension.
All siblings of the specified member, but not the @SIBLINGS
specified member.
All siblings of the specified member, including the @ISIBLINGS
specified member.
All siblings that precede the specified member in the @LSIBLINGS
database outline, but not the specified member.
All siblings that follow the specified member in the @RSIBLINGS
database outline, but not the specified member.
All siblings that precede the specified member in the @ILSIBLINGS
database outline, including the specified member.
All siblings that follow the specified member in the @IRSIBLINGS
database outline, including the specified member.
Separate lists of members to be processed by functions @LIST
that require multiple list arguments.
The member with the name that is provided as a @MEMBER
character string.
A merged list of two member lists to be processed by @MERGE
another function.
A member list that crosses the specified member from @RANGE
one dimension with the specified member range from
another dimension.
A member list the identifies all shared members among @SHARE
the specified members.
A member list that identifies the range of members @XRANGE
using the level of the arguments, determining the cross
product of all members in the range, and pruning the
set to include only the range requested.
A list of members from which some members have @REMOVE
been removed.
All members that match the specified wildcard @MATCH
selection.
The parent of the current member being calculated in @PARENT
the specified dimension.
All members of the specified generation or level that @RELATIVE
are above or below the specified member.
All members that have a common (UDA) user-defined @UDA
attribute defined on Analytic Server.
All base-dimension members that are associated with @ATTRIBUTE
the specified attribute-dimension member.
All base members that are associated with attributes @WITHATTR
that satisfy the specified conditions.
For information about specific Analytic Services functions, see the
Technical Reference.

Manipulating Member Names

You can work with member names as character strings by using the
following functions:

Character String Manipulation Function To Use

To create a character string that is the result of appending @CONCATENATE
a member name or specified character string to another
member name or character string
To return a member name as a string @NAME

To return a substring of characters from another character @SUBSTRING

string or from a member name

Working with Member Combinations across

Dimensions
Use the cross-dimensional operator to point to data values of specific
member combinations. Create the cross-dimensional operator using a
hyphen (-) and a greater than symbol (>). Do not leave spaces in
between the cross-dimensional operator and the member names.

For example, in this simplified illustration, the shaded data value is

Sales -> Jan -> Actual.

Figure 176: Defining a Single Data Value by Using the Cross-

Dimensional Operator
The following example illustrates how to use the cross-dimensional
operator. This example allocates miscellaneous expenses to each
product in each market.

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

Analytic Services cycles through the database, performing these

calculations:

• Analytic Services divides the Sales value for the current

member combination by the total Sales value for all markets
and all products (Sales -> Market -> Product).
• It multiplies the value calculated in step 1 by the
Misc_Expenses value for?all?markets and all products
(Misc_Expenses -> Market -> Product).
• It allocates the result to Misc_Expenses for the current
member combination.

Consider carefully how you use the cross-dimensional operator, as it

can have significant performance implications. For information about
optimizing and the cross-dimensional operator, see Using Cross-
Dimensional Operators (->).
Formulas That Use Various Types of Functions
Use this section to find information about formulas that use other
types of formulas:

• Mathematical Operations
• Statistical Functions
• Range Functions
• Financial Functions
• Date and Time Functions
• Calculation Mode Functions
• Custom-Defined Functions

Mathematical Operations
You can perform many mathematical operations in formulas by using
the following mathematical functions.

Operation Function
To return the absolute value of an expression @ABS

To return the average value of the values in the specified @AVG

member?list
To return the value of e (the base of natural logarithms) raised @EXP
to power of the specified expression
To return the factorial of an expression @FACTORIAL

To return the next lowest integer value of a member or @INT

expression
To return the natural logarithm of a specified expression @LN

To return the logarithm to a specified base of a specified @LOG

expression
To return the base-10 logarithm of a specified expression @LOG10

To return the maximum value among the expressions in the @MAX

specified member list
To return the maximum value among the expressions in the @MAXS
specified member list, with the ability to skip zero and
#MISSING values
To return the minimum value among the expressions in the @MIN
specified member list
To return the minimum value among the expressions in the @MINS
specified member list, with the ability to skip zero and
#MISSING values
To return the modulus produced by the division of two @MOD
specified?members
To return the value of the specified member raised to the @POWER
specified power
To return the remainder value of an expression @REMAINDER

To return the member or expression rounded to the specified @ROUND

number of decimal places
To return the summation of values of all specified members @SUM

To return the truncated value of an expression @TRUNCATE

To return the variance (difference) between two specified @VAR

members. See?Calculating Variances or Percentage Variances
Between Actual and Budget Values.
To return the percentage variance (difference) between two @VARPER
specified members. See Calculating Variances or Percentage
Variances Between Actual and Budget Values.

For information about specific Analytic Services functions, see the

Technical Reference.

Statistical Functions
You can use these statistical functions to calculate advanced statistics
in Analytic Services.

Calculated Value Function to Use

The correlation coefficient between two parallel data?sets @CORRELATION
The number of values in the specified data set @COUNT

The median, or middle number, in the specified data set @MEDIAN

The mode, or the most frequently occurring value, in the @MODE

specified data set
The rank of the specified member or value in the specified @RANK
data set
The standard deviation, based upon a sample, of the @STDEV
specified members
The standard deviation, based upon the entire population, @STDEVP
of the specified members
The standard deviation, crossed with a range of members, @STDEVRANGE
of the specified members
The variance, based upon a sample, of the specified @VARIANCE
data?set
The variance, based upon the entire population, of the @VARIANCEP
specified data set

For information about specific Analytic Services functions, see the

Technical Reference.

Range Functions
You can execute a function for a range of members by using these
range functions.

Calculation Function to Use

The average value of a member across a range @AVGRANGE
of members
A range of members that is based on the relative @CURRMBRRANGE
position of the member combination Analytic
Services is currently calculating.
The maximum value of a member across a range @MAXRANGE
of members
The maximum value of a member across a range @MAXSRANGE
of members, with the ability to skip zero and
#MISSING values
The next or n th member in a range of members, @MDSHIFT
retaining all other members identical to the
current member across multiple dimensions
The minimum value of a member across a range @MINRANGE
of members
The minimum value of a member across a range @MINSRANGE
of members, with the ability to skip zero and
#MISSING values
The next or n th member in a range of members. @NEXT

The next or n th member in a range of members, @NEXTS

with the option to skip #MISSING, zero, or
both values.
The previous or n th previous member in a range @PRIOR
of members
The previous or n th previous member in a range @PRIORS
of members, with the option to skip
#MISSING, zero, or both values.
The next or n th member in a range of members, @SHIFT
retaining all other members identical to the
current member and in the specified dimension In some cases,
@SHIFTPLUS or
@SHIFTMINUS.

The summation of values of all specified @SUMRANGE

members across a range of members

For information about specific Analytic Services functions, see the

Technical Reference.

Financial Functions
You can include financial calculations in formulas by using these
financial functions.

Calculation Function To Use

An accumulation of values up to the specified @ACCUM
member
The proceeds of a compound interest calculation @COMPOUND

A series of values that represent the compound @COMPOUNDGROWTH

growth of the specified member across a range of
members
Depreciation for a specific period, calculated using @DECLINE
the declining balance method.
A value discounted by the specified rate, from the @DISCOUNT
first period of the range to the period in which the
amount to discount is found
A series of values that represents the linear growth @GROWTH
of the specified value
The simple interest for a specified member at a @INTEREST
specified rate
The internal rate of return on a cash flow @IRR

The Net Present Value of an investment (based on @NPV

a series of payments and incomes)
The period-to-date values of members in the @PTD
dimension tagged as time
The amount per period that an asset in the current @SLN
period may be depreciated (calculated across a
range of periods). The depreciation method used is
straight-line depreciation.
The amount per period that an asset in the current @SYD
period may be depreciated (calculated across a
range of periods). The depreciation method used is
sum of the year's digits.

For information about specific Analytic Services functions, see the

Technical Reference.

Date and Time Functions

You can use dates with other functions by using this date function.
 Function To
Date Conversion
Use
Convert date strings to numbers that can be used in @TODATE
calculation formulas

Calculation Mode Functions

You can specify which calculation mode that Analytic Services uses to
calculate a formula by using @CALCMODE.

Function To
Specification
Use
To specify that Analytic Services uses cell, block, bottom-up, @CALCMODE
and top-down calculation modes to calculate a formula.

Note: You can also use the configuration setting CALCMODE to set
calculation modes to BLOCK or BOTTOMUP at the database,
application, or server level. For details, see the Technical Reference,
under "essbase.cfg Settings" for CALCMODE or "Analytic Services
Functions" for @CALCMODE.

Custom-Defined Functions
Custom-defined functions are calculation functions that you create to
perform calculations not otherwise supported by the Analytic Services
calculation scripting language. You can use custom-defined functions in
formulas and calculation scripts. These custom-developed functions
are written in the Java programming language and registered on the
Analytic Server. The Analytic Services calculator framework calls them
as external functions.

Custom-defined functions are displayed in the functions tree in

Calculation Script Editor. From this tree, you can select a custom-
defined function to insert into a formula.

For a detailed explanation of how to develop and use custom-defined

functions, see Developing Custom-Defined Calculation Functions.
Checking Formula
Syntax
Analytic Services includes Analytic Server-based formula syntax
checking that tells you about syntax errors in formulas. For example,
Analytic Services tells you if you have mistyped a function name.
Unknown names can be validated against a list of custom-defined
macro and function names. If you are not connected to a server or the
application associated with the outline, Analytic Services may connect
you to validate unknown names.

A syntax checker cannot tell you about semantic errors in a formula.

Semantic errors occur when a formula does not work as you expect. To
find semantic errors, run the calculation and check the results to
ensure that they are as you expect.

Analytic Services displays the syntax checker results at the bottom of

the Formula Editor. If Analytic Services finds no syntax errors, it
displays the "No errors" message.

If Analytic Services finds one or more syntax errors, it displays the

number of the line that includes the error and a brief description of the
error. For example, if you do not include a semicolon end-of-line
character at the end of a formula, Analytic Services displays a
message similar to the message shown in Figure?177.

Figure 177: Formula Editor Syntax Checker, Syntax Error Message

Error: line 1: invalid statement; expected semicolon 
 

If a formula passes validation in Formula Editor or Outline Editor, but

Analytic Server detects semantic errors when the outline is saved,
check the following:

• The incorrect formula is saved as part of the outline, even

though it contains errors.
• Analytic Server writes a message in the application log that
indicates what the error is and displays the incorrect formula.
 • Analytic 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.

To check formula syntax, see "Creating and Editing Formulas in

Outlines" in the Essbase XTD Administration Services Online Help.

Estimating Disk Size for

a Calculation
You can estimate the disk size required for a single CALC ALL given
either a full data load or a partial data load. For more information, see
Estimating Calculation Affects on Database Size.

To estimate disk size for a calculation, see ESTIMATEFULLDBSIZE in

the Technical Reference.

Using Formulas in
Partitions
An Analytic Services partition can span multiple Analytic Servers,
processors, or computers. For a comprehensive discussion of
partitioning, see Designing Partitioned Applications and Creating and
Maintaining Partitions.

You can use formulas in partitioning, just as you use formulas on your
local database. However, if a formula you use in one database
references a value from another database, Analytic Services has to
retrieve the data from the other database when calculating the
formula. In this case, you need to ensure that the referenced values
are up-to-date and to consider carefully the performance impact on
the overall database calculation. For a discussion of how various
options affect performance, see Writing Calculation Scripts for
Partitions.

With transparent partitions, you need to consider carefully how you use formulas on the
data target. For a detailed example of the relationship between member formulas and
transparent partitioning, see Transparent Partitions and Member Formulas. For a
discussion of the performance implications, see Performance Considerations for
Transparent Partition Calculations.

Reviewing Examples of
Formulas
This chapter provides detailed examples of formulas, which you may
want to adapt for your own use. For examples of using formulas in
calculation scripts, see Reviewing Examples of Calculation Scripts.

This chapter includes the following sections:

• Calculating Period-to-Date Values

• Calculating Rolling Values
• Calculating Monthly Asset Movements
• Testing for #MISSING Values
• Calculating an Attribute Formula

Calculating Period-to-
Date Values
If the outline includes a dimension tagged as accounts, you can use
the @PTD function to calculate period-to-date values. You can also use
Dynamic Time Series members to calculate period-to-date values. For
an explanation of how to calculate time series data, see Calculating
Time Series Data.
For example, the following figure shows the Inventory branch of the
Measures dimension from the Sample Basic database.

Figure 178: Inventory Branch from Sample Basic Outline

Inventory (~) (Label Only)
???Opening Inventory (+) (TB First) (Expense Reporting) 
IF(NOT @ISMBR(Jan))
???Additions (~) (Expense Reporting)
???Ending Inventory (~) (TB Last) (Expense Reporting) 
 

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:

QTD?(~)?@PTD(Apr:May)
YTD?(~)?@PTD(Jan:May); 
 

For example, assuming that the current month is May, you would add
this formula to the QTD member:

@PTD(Apr:May); 
 

And you would add this formula on the YTD member:

@PTD(Jan:May); 
 

Analytic Services sums the values for the range of months as

appropriate. However, Opening Inventory has a time balance tag, First,
and Ending Inventory has a time balance tag, Last. Analytic Services
takes these values and treats them accordingly. For more?information
on time balance tags, see Calculating First, Last, and Average Values.

The following table provides an example of the calculation results for

the members in the Inventory branch and for the Sales member:

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

The values for Sales and Additions have been summed.

Opening Inventory has a First tag. For QTD, Analytic Services takes
the first value in the current quarter, which is Apr. For YTD, Analytic
Services takes the first value in the year, which is Jan.

Ending Inventory has a Last tag. For QTD, Analytic Services takes the
last value in the current quarter, which is May. For YTD, Analytic
Services takes the last value in the year, which is also May.

Calculating Rolling
Values
You can use the @AVGRANGE function to calculate rolling averages
and the @ACCUM function to calculate rolling year-to-date values.

For example, assume that a database contains monthly Sales data

values and that the database outline includes the members AVG_Sales
and YTD_Sales.

You would add this formula to the AVG_Sales member:

@AVGRANGE(SKIPNONE, Sales, @CURRMBRRANGE(Year, LEV, 0, , 
0)); 
 

And you would add this formula on the YTD_Sales member:

@ACCUM(Sales); 
 
Analytic Services 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. Analytic
Services places the results in AVG_Sales. For an explanation of how
Analytic Services calculates #MISSING values, see Aggregating
#MISSING Values.

This table shows the results when Analytic Services calculates the
cumulative Sales values and places the results in YTD_Sales:

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

Calculating Monthly
Asset Movements
You can use the @PRIOR function to calculate values based on a
previous month's value.

For example, assume that a database contains assets data values that
are stored on a month-by-month basis. You can calculate the
difference between the assets values of successive months (the asset
movement) by subtracting the previous month's value from the
present month's value.
Assume these three members manage the asset values for the
database:

• Assets for the monthly asset values

• Asset_MVNT for the asset movement values
• Opening_Balance for the asset value at the beginning of the
year

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; 
 

This table shows the results when Analytic Services calculates the
difference between the values of assets in successive months:

Assets?->?Time Opening_Balance Jan Feb Mar

Assets 1200 1400 1300 1800

.
Asset_MVNT 200 -100 500

Analytic Services cycles through the months, performing these

calculations:

1. The IF statement and @ISMBR function check to see if 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 month's value.
2. If the current member on the Year dimension is Jan, Analytic
Services 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 month's
assets. Analytic Services subtracts the previous month's
 assets from the current month's assets. It places the result in
the current month's Asset_MVNT value.

Testing for #MISSING

Values
You can test for #MISSING values in a database. For an explanation of
how Analytic Services calculates #MISSING values, see Aggregating
#MISSING Values.

Assume that a database outline contains a member called Commission.

Commission is paid at 10% of sales when the Sales value for the
current member combination is not #MISSING. When applied to a
Commission member in the database outline, the following formula
calculates Commission:

IF(Sales <> #MISSING) Commission = Sales * .1;
ELSE Commission = #MISSING;
ENDIF; 
 

If you place the formula in a calculation script, you need to associate it

with the commission member as follows:

Commission(IF(Sales <> #MISSING) Commission = Sales * .1;
ELSE Commission = #MISSING;
ENDIF;); 
 

Analytic Services cycles through the database, performing the

following calculations:

1. The IF statement checks to see if the value of the Sales

member for the current member combination is not
#MISSING.
2. If Sales is not #MISSING, Analytic Services multiplies the
value in the Sales member by 0.1 and places the result in the
Commission member.
 3. If Sales is #MISSING, Analytic Services places #MISSING in
the Commission member.

Calculating an Attribute
Formula
You can perform specific calculations on attribute-dimension members
in a database.

Note: For a comprehensive discussion of attribute calculations, see

Calculating Attribute Data.

For example, to calculate profitability by ounce for products sized in

ounces, you can use the @ATTRIBUTEVAL function in a calculation
formula. In the Sample Basic database, the Ratios branch of the
Measures dimension contains a member called Profit per Ounce. The
formula on this member is:

Profit/@ATTRIBUTEVAL(Ounces); 
 

Analytic Services 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).
2. Analytic Services then divides Profit by the result of
@ATTRIBUTEVAL to yield Profit per Ounce.

Note: For an explanation of the functions that you use to perform

calculations on attributes in formulas, see Using Attributes in
Calculation Formulas. For more information about the
@ATTRIBUTEVAL function, see the Technical Reference.
Defining Calculation
Order
This chapter describes the order in which Analytic Services calculates a
database. You should understand the concepts of data blocks and of
sparse and dense dimensions before using this information. For a
review of this information, see Sparse and Dense Dimensions. You
should also understand the use of levels and generations. For a review
of this information, see Generations and Levels. If you use dynamic
calculations, see Understanding How Dynamic Calculation Changes
Calculation Order for information on the calculation order for the
dynamically calculated values.

This chapter includes these sections:

• Data Storage in Data Blocks

• Member Calculation Order
• Block Calculation Order
• Data Block Renumbering
• Cell Calculation Order
• Calculation Passes
• Calculation of Shared Members

Data Storage in Data

Blocks
Analytic Services stores data values in data blocks. Analytic Services
creates a data block for each unique combination of sparse dimension
members (providing that at least one data value exists for the
combination).

Each data block contains all the dense dimension member values for
its unique combination of sparse dimension members.

In the Sample Basic database, the Year, Measures, and Scenario

dimensions are dense. The Product and Market dimensions are sparse.
Figure 179: Dimensions from the Sample Basic Database

Note: Sample Basic also contains five attribute dimensions. These

dimensions are sparse, Dynamic Calc, meaning that attribute data
is not stored in the database. For a comprehensive discussion of
attributes, see Working with Attributes.

Analytic Services 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 180: Product and Market Dimensions from the Sample Basic
Database

In Analytic Services, 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 100-10 -> New York.

You can categorize data blocks as follows:

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

For more information on levels and generations, see Generations and

Levels. For information on how Analytic Services stores data in data
blocks, see Data Blocks and the Index System.

Member Calculation
Order
Analytic Services calculates a database at the data block level,
bringing one or more blocks into memory and calculating the required
values within the block. Analytic Services calculates the blocks in
order, according to their block numbers. The database outline tells
Analytic Services how to order the blocks. Within each block, Analytic
Services calculates the values in order according to the hierarchy in
the database outline. Therefore, overall, Analytic Services calculates a
database based on the database outline.

When you perform a default calculation (CALC ALL) on a database,

Analytic Services calculates the dimensions in this order:

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, Analytic Services calculates as follows:
 1. The dimension tagged as accounts
2. The dimension tagged as time
3. Other dense dimensions (in the order they are displayed in
the database outline)
4. Other sparse dimensions (in the order they are displayed in
the database outline)

Otherwise, Analytic Services calculates in this order:

1. Dense dimensions (in the order they display in the database

outline)
2. Sparse dimensions (in the order they display in the database
outline)

Note: Attribute dimensions, which are not included in the database

consolidation, do not affect calculation order. For a comprehensive
discussion of attribute dimensions, see Working with Attributes.

In the Sample Basic database, the dimensions are calculated in this

order: Measures, Year, Scenario, Product, and Market.

You can override the default order by using a calculation script. For a
comprehensive discussion of how to develop and use calculation
scripts, see Developing Calculation Scripts.

Understanding the Effects of Member Relationships

The order of calculation within each dimension depends on the
relationships between members in the database outline. Within each
branch of a dimension, level 0 values are calculated first followed by
their level 1, parent value. Then the level 0 values of the next branch
are calculated followed by their level 1, parent value. The calculation
continues in this way until all levels are calculated.

Figure?181 shows the Year dimension from the Sample Basic

database. The calculation order is shown on the left. This example
assumes that the parent members are not tagged as Dynamic Calc.
For a comprehensive discussion of dynamic calculation, see
Dynamically Calculating Data Values.

Figure 181: Year Dimension from the Sample Basic Database

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.

Analytic Services calculates Qtr1 by consolidating Jan, Feb, and Mar. In

this example, these members are added.

Analytic Services then calculates the Qtr2 through Qtr4 branches in

the same way.

Finally, Analytic Services calculates the Year member by consolidating

the values of Qtr1 through Qtr4. Again, in this example, these
members are added.

Determining Member Consolidation

You can choose how Analytic Services consolidates members by
applying any calculation operator (+, -, /, *, %, ~) to the members in
the database outline.

If an accounts member has a time balance tag (First, Last, or

Average), Analytic Services consolidates it accordingly. For information
on time balance calculations, see Calculating First, Last, and Average
Values.

If a parent member has a label only tag, Analytic Services does not
calculate the parent from its children. If a member has a ~ tag,
Analytic Services does not consolidate the member up to its parent.

Note: If you use dynamic calculations, Analytic Services may use a

different calculation order. For information on the calculation order
for dynamically calculated values, see Calculation Order for
Dynamic Calculation.

Ordering Dimensions in the Database Outline

To ensure the required calculation results, consider the calculation
order of the dimensions in the database outline if you do either of
these tasks:

• Use calculation operators to divide (/), multiply (*), or

calculate percentages (%) for members in the database
outline.
• Place formulas on members in the database outline.

You do not need to 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.

Placing Formulas on Members in the Database

Outline
If you place formulas on members in the database outline, consider
the calculation order of the dimensions. A formula that is attached to a
member on one dimension may be overwritten by a subsequent
calculation on another dimension.

For example, the Sample Basic database has a Measures dimension,

tagged as accounts, and a Year dimension, tagged as time. Measures
is calculated first, and Year second. If you attach a formula to Margin
on the Measures dimension, Analytic Services calculates the formula
when it calculates the Measures dimension. Analytic Services then
overwrites the formula when it aggregates the Year dimension. For
detailed examples of cell calculation order, see Cell Calculation Order.

Using the Calculation Operators *, /, and %

If you use calculation operators to multiply (*), divide (/ ), and
calculate percentages (%) for members in the database outline,
consider the calculation order of the dimensions. The required
calculated values may be overwritten by a subsequent calculation on
another dimension.
For example, the Sample Basic database has a Measures dimension,
tagged as accounts, and a Year dimension, tagged as time. Measures
is calculated first, and Year second. If you multiply members on the
Measures dimension, the calculated results may be overwritten when
Analytic Services aggregates values on the Year dimension. For
detailed examples of cell calculation order, see Cell Calculation Order.

When you use a multiplication (*), division (/ ), or percentage (%)

operator to consolidate members, carefully order the members in the
branch to achieve the required result.

Figure 182: Calculation Operators in the Database Outline

In the above example, assume that the user wants to divide the total
of Child 2 and Child 3 by Child 1. However, if Child 1 is the first
member, Analytic Services starts with Child 1, taking the value of
Parent 1 (currently #MISSING) and dividing it by Child 1. The result is
#MISSING. Analytic Services then adds Child 2 and Child 3. Obviously,
this result is not the required one.

To calculate the correct result, make Child 1 the last member in the
branch. For more information on #MISSING values, see Aggregating
#MISSING Values.

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 in the above example.

Avoiding Forward Calculation References

To obtain the calculation results you expect, ensure that the outline
does not contain forward calculation references. Forward calculation
references occur when the value of a calculating member is dependent
on a member that Analytic Services has not yet calculated. In these
cases, Analytic Services may not produce the required calculation
results.

For example, consider this Product dimension:

Figure 183: Example Product Dimension

This Product dimension has three forward calculation references. Two

shared members and one non-shared member have forward
calculation references:

Figure 184: Example Product Dimension Showing Forward Calculation

References

In Outline Editor, when you verify the outline, Analytic Services

identifies shared members with forward calculation references.
Verifying the outline does not identify non-shared members that have
forward calculation references. You can save and use an outline
containing forward calculation references.
 To verify the outline, see "Verifying Outlines" in the Essbase XTD
Administration Services Online Help.

Consider the five members under Diet. The members P100-20, P300-
20, and P500-20 have forward calculation references:

• P100-20 (+) (Shared Member): Analytic Services calculates

the shared member P100-20 before it calculates the real
member P100-20. Because the real member P100-20 has
children, Analytic Services needs to calculate the real member
by adding its children before it can accurately calculate the
shared member P100-20.
• P300-20 (+) (Shared Member): Analytic Services calculates
the shared member P300-20 before it calculates the real
member P300-20. Because the real member P300-20 has a
formula, Analytic Services needs to calculate the real 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 Analytic Services has
not yet calculated. One referenced member, P300-20, has its
own formula, and Analytic Services needs to calculate P300-
20 before it can accurately calculate P500-20. The members
P200-20 and P400-20 calculate correctly, as they do not have
forward calculation references.
• P200-20 (+) (Shared Member): P200-20 is not a forward
calculation reference, even though Analytic Services
calculates the shared member P200-20 before it calculates
the real member P200-20. The real member P200-20 has no
calculation dependencies (no children and no formula).
Therefore Analytic Services does not need to calculate the
real member before the shared member. Analytic Services
simply takes the value of the real member.
• P400-20 (+) ("P200-10" * 2): P400-20 is not a forward
calculation reference, even though the formula that is applied
to P400-20 references a member that Analytic Services 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. Analytic Services 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, you ensure that Analytic
Services calculates the members in the required order.

Figure 185: Changed Product Dimension Without Forward Calculation

References

Now Analytic Services calculates as follows:

• The real member P100-20 before it calculates the shared

member P100-20. So, P100-20 no longer has a forward
calculation reference.
• The real 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.

Block Calculation Order

Analytic Services calculates blocks in the order in which the blocks are
numbered. Analytic Services takes the first sparse dimension in a
database outline as a starting point. It defines the sparse member
combinations from this first dimension.

In the Sample Basic database, Product is the first sparse dimension in

the database outline.
Figure 186: Dimensions in the Sample Basic Database

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. For a
comprehensive discussion of attribute dimensions, see Working with
Attributes.

Product has 19 members (excluding the shared members, for which

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

Figure 187: Product Dimension from the Sample Basic Database

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.

This table shows the sparse member combinations for the first 5 of
these 19 data blocks.
Block # Product Member Market Member

0 Cola (100-10) New York

1 Diet Cola (100-20) New York

2 Caffeine Free Cola (100-30) New York

3 Colas (100) New York

4 Old Fashioned (200-10) New York

The next member in the Market dimension is Massachusetts. Analytic

Services creates the next 19 data blocks for sparse combinations of
each Product member and Massachusetts.

This table shows the sparse member combinations for the block
numbers 19 through 23.

Block # Product Member Market Member

19 Cola (100-10) Massachusetts

20 Diet Cola (100-20) Massachusetts

21 Caffeine Free Cola (100-30) Massachusetts

22 Colas (100) Massachusetts

23 Old Fashioned (200-10) Massachusetts

Analytic Services continues until blocks have been created for all
combinations of sparse dimension members for which at least one data
value exists.

Analytic Services 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 Analytic Services does not
create a data block for 200-10 -> Massachusetts. However, Analytic
Services 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 Analytic Services skips the block and moves on to the
next block. For a comprehensive discussion of how intelligent
calculation is used to optimize performance, see Optimizing with
Intelligent Calculation.

Data Block
Renumbering
Analytic Services renumbers the data blocks when you make any of
these changes:

• Move a sparse dimension

• Add a sparse dimension
• Change a dense dimension to a sparse dimension
• Move any member in a sparse dimension
• Delete any member in a sparse dimension
• Add a member to a sparse dimension

Cell Calculation Order

Each data block contains all the dense dimension member values for
its unique combination of sparse dimension members. Each data value
is contained in a cell of the data block.

The order in which Analytic Services calculates the cells within each
block depends on how you have configured the database. How you
have configured the database defines the member calculation order of
dense dimension members within each block. It also defines the
calculation order of blocks that represent sparse dimension members.

Use these sections to understand cell calculation order in more detail:

 • Cell Calculation Order: Example 1
• Cell Calculation Order: Example 2
• Cell Calculation Order: Example 3
• Cell Calculation Order: Example 4
• Cell Calculation Order for Formulas on a Dense Dimension

Cell Calculation Order: Example 1

Consider the simplest case in which both of these conditions are true:

• No dimensions have time or accounts tags.

• The setting for aggregating #MISSING values is turned on.
For an explanation of how and why #MISSING values are
aggregated, see Aggregating #MISSING Values.

Market and Year are both dense dimensions. The table shows a subset
of the cells in a data block. Data values have been loaded into the
input cells. Analytic Services calculates the shaded cells. The numbers
in bold show the calculation order for these cells. The cell with multiple
consolidation paths is darkly shaded.

Year -> Market New York Massachusetts East

Jan 112345.00 68754.00 3

Feb 135788.00 75643.00 4

Mar 112234.00 93456.00 5

???Qtr1 1 2 6

As described in Member Calculation Order, Analytic Services calculates

dense dimensions in the order that they display in the database
outline. Assuming that the Year dimension is displayed before the
Market dimension in the database outline, the Year dimension is
calculated before the Market dimension.

The cells are calculated in this order:

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 an
aggregation of Qtr1 -> New York and Qtr1 -> Massachusetts. When
consolidated on Year, it is an aggregation of Jan?-> East, Feb -> East,
and Mar -> East.

Analytic Services knows that Qtr1 -> East has multiple consolidation
paths. Therefore, it calculates Qtr1 -> East only once and uses the
consolidation path of the dimension calculated last. In the above
example, this dimension is Market.

The results are shown in this table:

Year/Market New York Massachusetts East

Jan 112345.00 68754.00 181099.00

Feb 135788.00 75643.00 211431.00

Mar 112234.00 93456.00 205690.00

???Qtr1 360367.00 237853.00 598220.00

Note: Qtr1 -> East has been calculated only once by aggregating
the values for Qtr1.

From the calculation order, you can see that if you place a member
formula on Qtr1 in the database outline, Analytic Services ignores it
when calculating Qtr1 -> East. If you place a member formula on East
in the database outline, the formula is calculated when Analytic
Services 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. For a comprehensive discussion of how to
develop and use calculation scripts, see Developing Calculation Scripts.
Cell Calculation Order: Example 2
Consider a second case in which both of these conditions are true:

• No dimensions have time or accounts tags.

• The setting for aggregating #MISSING values is turned off
(the default). For more information, see Aggregating
#MISSING Values.

Market and Year are both dense dimensions. The table shows a subset
of the cells in a data block. Data values have been loaded into the
input cells. Analytic Services calculates the shaded cells. The numbers
in bold show the calculation order for these cells. The cell with multiple
consolidation paths is darkly shaded.

Year -> Market New York Massachusetts East

Jan 112345.00 68754.00 4

Feb 135788.00 75643.00 5

Mar 112234.00 93456.00 6

???Qtr1 1 2 3/7

As described in Member Calculation Order, Analytic Services calculates

dense dimensions in the order they are defined in the database
outline. Assuming the Year dimension is positioned before the Market
dimension in the database outline, the Year dimension is calculated
before the Market dimension.

The cells are calculated in this order:

1. Qtr1 -> New York

2. Qtr1 -> Massachusetts
3. Qtr1 -> East
4. Jan -> East
5. Feb -> East
6. Mar -> East
7. Qtr1 -> East
In this case Qtr1 -> East is calculated on both the Year and Market
consolidation paths. First, it is calculated as an aggregation of Qtr1 ->
New York and Qtr1 -> Massachusetts. Second, it is calculated as an
aggregation of Jan -> East, Feb -> East, and Mar -> East.

The results are identical to the previous case. However, Qtr1 -> East
has been calculated twice. This fact is significant when you need to
load data at parent levels. For an example in which data is loaded at
the parent level, see Cell Calculation Order: Example 3.

Year/Market New York Massachusetts East

Jan 112345.00 68754.00 181099.00

Feb 135788.00 75643.00 211431.00

Mar 112234.00 93456.00 205690.00

???Qtr1 360367.00 237853.00 598220.00

From the calculation order, you can see that if you place a member
formula on Qtr1 in the database outline, its result is overwritten when
Analytic Services 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.

Cell Calculation Order: Example 3

Consider the previous case in which both of these conditions are true:

• No dimensions have time or accounts tags.

• The setting for aggregating #MISSING values is turned off
(the default). For an explanation of how and why #MISSING
values are aggregated, see Aggregating #MISSING Values.
• Data values have been loaded at a parent levels.

Market and Year are both dense dimensions. The table shows a subset
of the cells in a data block. Data values have been loaded into cells at
the parent level.
Year -> Market New York Massachusetts East

Jan #MISSING #MISSING 181099.00

Feb #MISSING #MISSING 211431.00

Mar #MISSING #MISSING 205690.00

???Qtr1 #MISSING #MISSING

As described in Member Calculation Order, Analytic Services calculates

dense dimensions in the order that they are defined in the database
outline. Assuming the Year dimension is positioned before the Market
dimension in the database outline, the Year dimension is calculated
before the Market dimension.

The cells are calculated in the same order as in Example 2. Qtr1 ->
East is calculated on both the Year and Market consolidation paths.

Because the setting for aggregating #MISSING values is turned off,

Analytic Services does not aggregate 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 were 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.

Analytic Services first correctly calculates the Qtr1 -> East cell by
aggregating Jan?-> East, Feb -> East, and Mar -> East. Second, it
calculates on the Market consolidation path. However, it does not
aggregate the #MISSING values in Qtr1?-> New York and Qtr1 ->
Massachusetts and so the value in Qtr1 -> East is not overwritten.

This table shows the results:

Year/Market New York Massachusetts East

Jan #MISSING #MISSING 181099.00

Feb #MISSING #MISSING 211431.00

Mar #MISSING #MISSING 205690.00

???Qtr1 #MISSING #MISSING 598220.00

Analytic Services needs to calculate the Qtr1 -> East cell twice in order
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.

Cell Calculation Order: Example 4

Consider a case in which all of these conditions are true:

• The Year dimension is tagged as time.

• The Measures dimension is tagged as accounts.
• The setting for aggregating #MISSING values is turned off
(the default). For an example of how and why #MISSING
values are aggregated, see Aggregating #MISSING Values.

Figure?188 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. For more information on Dynamic Calc
members, see Dynamically Calculating Data Values.

Figure 188: Profit Branch of the Measures Dimension in the Sample

Basic Database

This table shows a subset of the cells in a data block. Data values have
been loaded into the input cells. Analytic Services calculates the
shaded cells. The numbers in bold show the calculation order for these
cells. Cells with multiple consolidation paths are darkly shaded.

The Marketing, Payroll, and Misc Expenses values have been loaded at
the Qtr1, parent level.
Measures/Year Jan Feb Mar Qtr1

Sales 31538 32069 32213 13

COGS 14160 14307 14410 14

???Margin 1 4 7 10/15

Marketing #MISSING #MISSING #MISSING 15839

Payroll #MISSING #MISSING #MISSING 12168

Misc #MISSING #MISSING #MISSING 233

???Total Expenses 2 5 8 11/16

??????Profit 3 6 9 12/17

As described in Member Calculation Order, Analytic Services calculates

a dimension tagged as accounts first, followed by a dimension tagged
as time. Therefore, in the above example, Measures is calculated
before Year.

Three cells have multiple consolidation paths:

• Margin -> Qtr1

• Total Expenses -> Qtr1
• Profit -> Qtr1

Because the setting for aggregating #MISSING values is turned off,

Analytic Services does not aggregate the #MISSING values. Thus, any
data that is loaded at parent levels is not overwritten by the
#MISSING values and Analytic Services calculates the three cells with
multiple consolidation paths twice.

The results are shown in this table.

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

???Total Expenses 28240

??????Profit 17378 17762 17803 52943

From the calculation order, you can see that if you place a member
formula on, for example, Margin in the database outline, its result is
overwritten by the consolidation on Qtr1.

Cell Calculation Order for Formulas on a Dense Dimension

The cell calculation order within a data block is not affected by
formulas on members. When Analytic Services encounters a formula in
a data block, it locks any other required data blocks, calculates the
formula, and proceeds with the data block calculation.

When placing a formula on a dense dimension member, carefully

consider the cell calculation order. As described in the examples above,
the dimension calculated last overwrites previous cell calculations for
cells with multiple consolidation paths. If required, you can use a
calculation script to change the order in which the dimensions are
calculated. For a comprehensive discussion of how to develop and use
calculation scripts, see Developing Calculation Scripts.

For a comprehensive discussion of how to develop and use formulas,

see Developing Formulas.

Calculation Passes
Whenever possible, Analytic Services 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, Analytic Services needs to perform more than one
calculation pass through a database. On subsequent calculation
passes, Analytic Services brings data blocks back into memory,
performs further calculations on them, and saves them again.

When you perform a default, full calculation of a database (CALC ALL),

Analytic Services attempts to calculate the database in one calculation
pass. If you have dimensions that are tagged as accounts or time,
Analytic Services may have to do more than one calculation pass
through the database.

This table shows the number of calculation passes Analytic Services

performs if you have dimensions that are tagged as time or accounts,
and you have at least one formula on the accounts dimension.

Dimension During each calculation

Tagged As: Calculation
pass, Analytic Services
Passes
Accounts Time calculates based on:

Dense or None 1 All dimensions

Sparse

Dense Dense 1 All dimensions

Dense Sparse 2 Pass 1: Accounts and time

dimensions
Pass 2: Other dimensions

Sparse Sparse 2 Pass 1: Accounts and time

dimensions
Pass 2: Other dimensions

Sparse Dense 2 Pass 1: Accounts dimension

Pass 2: Other dimensions
If you are using formulas that are tagged as Two-Pass, Analytic
Services may need to do an extra calculation pass to calculate these
formulas. For a comprehensive discussion of two-pass calculations, see
Using Two-Pass Calculation.

When you use a calculation script to calculate a database, the number

of calculation passes Analytic Services needs to perform depends upon
the calculation script. For a discussion of single pass and multiple pass
calculations, see Calculation Passes and Understanding Multiple-Pass
Calculations. For information on grouping formulas and calculations,
see Grouping Formulas and Calculations.

When you calculate a database, Analytic Services automatically

displays the calculation order of the dimensions for each pass through
the database and tells you how many times Analytic Services has
cycled through the database during the calculation. Analytic Services
displays this information in the ESSCMD window and in the application
log.

To display the application log, see Viewing the Analytic Server and
Application Logs.

For each data block, Analytic Services 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.

Analytic Services calculates the blocks using this procedure:

• If you have Intelligent Calculation turned on and if the block

does not need to be calculated (if it is marked as clean), then
Analytic Services skips the block and moves on to the next
block. For a comprehensive discussion of intelligent
calculation, see Optimizing with Intelligent Calculation.
• If the block needs recalculating, Analytic Services checks to
see if the block is a level 0, an input, or an upper level block.
For definitions of level 0, input, and upper level blocks, see
Data Storage in Data Blocks.
• If the block is a level 0 block or an input block, Analytic
Services performs a dense calculation on the block. Each cell
in the block is calculated. For detailed examples of how
Analytic Services calculates cells, see Cell Calculation Order.
 • If the block is an upper level block, Analytic Services either
aggregates 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. Analytic Services
aggregates or calculates the block based on the parent
member's dimension. For example, if the upper level block is for
Product -> Florida from the Sample Basic database, then
Analytic Services chooses the Product dimension.
If the sparse member combination for the block has more than
one parent member, Analytic Services 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,
Analytic Services 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. For an explanation of the order in which
Analytic Services calculates members, see Member Calculation
Order.
Based on the chosen sparse dimension, Analytic Services either
aggregates the values or performs a sparse calculation on the
data block:
o If a formula is applied to the data block member on the
chosen sparse dimension, Analytic Services performs a
formula calculation on the sparse dimension. Analytic
Services 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.
o If the chosen sparse dimension is a default
consolidation, Analytic Services aggregates the values,
taking the values of the previously calculated child data
blocks.

Calculation of Shared
Members
Shared members are those that share data values with other
members. For example, in the Sample Basic database, Diet Cola, Diet
Root Beer, and Diet Cream are consolidated under two different
parents. They are consolidated under Diet. They are also consolidated
under their individual product types-Colas, Root Beer, and Cream
Soda.

Figure 189: Calculating Shared Members

The members under the Diet parent are shared members. For a
comprehensive discussion of shared members, see Understanding
Shared Members.

A calculation on a shared member is a calculation on the real member.

If you use the FIX command to calculate a subset of a database and
the subset includes a shared member, Analytic Services calculates the
real member

Dynamically Calculating
Data Values
This chapter explains how you calculate data values dynamically and
how you benefit from doing so. Dynamically calculating some of the
values in a database can significantly improve the performance of an
overall database calculation.
The information in this chapter assumes that you are familiar with the
concepts of member combinations, dense and sparse dimensions, and
data blocks. For a comprehensive discussion of these concepts, see
Understanding Multidimensional Databases.

This chapter includes the following sections:

• Understanding Dynamic Calculation

• Benefitting from Dynamic Calculation
• Using Dynamic Calculation
• Choosing Values to Calculate Dynamically
• Understanding How Dynamic Calculation Changes Calculation
Order
• Reducing the Impact on Retrieval Time
• Using Dynamic Calculations with Standard Procedures
• Creating Dynamic Calc and Dynamic Calc and Store Members
• Restructuring Databases
• Dynamically Calculating Data in Partitions

Understanding
Dynamic Calculation
When you design the overall database calculation, it may be more
efficient to calculate some member combinations when you retrieve
their data, instead of pre-calculating the member combinations during
a batch database calculation.

In Analytic Services, you can define a member to have a dynamic

calculation. This definition tells Analytic Services to calculate a data
value for the member as users request it. Dynamic calculation
shortens batch database calculation time, but may increase retrieval
time for the dynamically calculated data values. See Reducing the
Impact on Retrieval Time for information on how to analyze and
manage the effect of dynamic calculation.

In Analytic Services you specify dynamic calculations on a per-member

basis. You can define a member in the database outline as one of two
types of a dynamically calculated member:

• Dynamic Calc
 • Dynamic Calc and Store

Use the rest of this section to gain a basic understanding of dynamic

calculation:

• Understanding Dynamic Calc Members

• Understanding Dynamic Calc and Store Members
• Retrieving the Parent Value of Dynamically Calculated Child
Values

Understanding Dynamic Calc Members

For a member that is tagged as Dynamic Calc, Analytic Services does
not calculate its data value during a batch database calculation; for
example, during a CALC ALL. Instead, Analytic Services calculates the
data value upon retrieval; for example, when you retrieve the data
into Spreadsheet Add-in or Spreadsheet Services.

Specifically, Analytic Services calculates a data value dynamically when

you request the data value in either of two ways:

• By retrieving the data value into Spreadsheet Add-in or

Spreadsheet Services
• By running a report script that displays the data value

Analytic Services does not store the calculated value; it recalculates

the value for each subsequent retrieval.

Understanding Dynamic Calc and Store Members

Analytic Services calculates the data value for a member that is tagged
as Dynamic Calc and Store when you retrieve the data, in the same
way as for a Dynamic Calc member. For a Dynamic Calc and Store
member, however, Analytic Services stores the data value that is
calculated dynamically. Subsequent retrievals of that data value do not
require recalculation, unless Analytic Services detects that the value
needs recalculating.

Recalculation of Data
When Analytic Services 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 Analytic Services knows to
recalculate the block on the next retrieval of the data value.

Analytic Services places the indicator on the data block containing the
value and not on the data value itself. In other words, Analytic
Services tracks Dynamic Calc and Store members at the data block
level. For detailed information on data blocks, see Data Blocks and the
Index System.

If the data block needs recalculating, Analytic Services detects the

need and places an indicator on the data block when any of the
following occur:

• You perform a batch calculation.

• You restructure the database.
• You use the CLEARBLOCK DYNAMIC calculation command. For
more information on the CLEARBLOCK command, see the
Technical Reference.

Analytic Services recalculates the indicated data blocks when you next
retrieve the data value.

Effect of Updated Values on Recalculation

Analytic Services does not detect that a data block needs recalculating
and does not place an indicator on the data block when you update the
data; that is, updated blocks are recalculated only during the next
batch calculation. Consider the following two scenarios:

• You do a data load.

• You do a Lock and Send from Spreadsheet Services.

If you load data into the children of a Dynamic Calc and Store member,
and the member is a consolidation of its child members, Analytic
Services 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 need to 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. For
more information on the CLEARBLOCK command, see the Technical
Reference.
Retrieving the Parent Value of Dynamically Calculated Child
Values
If you retrieve a parent value that is calculated from Dynamic Calc or
Dynamic Calc and Store child members, Analytic Services must
dynamically calculate the child member combinations before
calculating the parent value. Analytic Services does not store the child
values, even if they are Dynamic Calc and Store members.

For example, assume that Market is a parent member and that East
and West are Dynamic Calc and Store child members that consolidate
up to Market. When you retrieve a data value for Market, Analytic
Services calculates East and West, even though you have not
specifically retrieved them. However, Analytic Services does not store
the values of East or West.

Benefitting from
Dynamic Calculation
Dynamically calculating some database values can significantly
improve the performance of an overall database calculation.

Calculating some data values dynamically, achieves the following

advantages:

• It reduces the batch calculation time of the database because

Analytic Services has fewer member combinations to
calculate.
• It reduces disk usage because Analytic Services stores fewer
calculated data values. Database size and index size are
reduced.
• It reduces database restructure time. For example, adding or
deleting a Dynamic Calc member in a dense dimension does
not change the data block size, and so Analytic Services does
not need to restructure the database for such additions and
deletions. For an explanation of the relationship between the
use of Dynamic Calc members and database restructures, see
Restructuring Databases.
 • It reduces the time that is required to back up the database.
Because database size is reduced, Analytic Services takes less
time to perform a backup.

Data values that Analytic Services calculates dynamically can take

longer to retrieve. You can estimate the retrieval time for dynamically
calculated members. For information on how to analyze and manage
the effect of dynamic calculation, see Reducing the Impact on Retrieval
Time.

Using Dynamic
Calculation
You can tag any member as Dynamic Calc or Dynamic Calc and Store,
except the following:

• Level 0 members that do not have a formula

• 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. For guidelines on choosing which members to
calculate dynamically, see Choosing Values to Calculate Dynamically.

Outline Editor shows which members are Dynamic Calc and which
members are Dynamic Calc and Store.

Figure 190: Sample Basic Outline Showing Dynamic Calc Members

In Spreadsheet Add-in or Spreadsheet Services, users can display

visual cues to distinguish dynamically calculated values. For more
information, see the Spreadsheet online help.
When developing spreadsheets that include dynamically calculated
values, spreadsheet designers may want to use the spreadsheet
Navigate Without Data option, so that Analytic Services does not
dynamically calculate and store values while test spreadsheets are
being built.

Choosing Values to
Calculate Dynamically
Dynamically calculating some data values decreases calculation time,
lowers disk usage, and reduces database restructure time, but
increases retrieval time for dynamically calculated data values.

Use the guidelines described in the following sections when deciding

which members to calculate dynamically:

• Dense Members and Dynamic Calculation

• Sparse Members and Dynamic Calculation
• Two-Pass Members and Dynamic Calculation
• Parent-Child Relationships and Dynamic Calculation
• Calculation Scripts and Dynamic Calculation
• Formulas and Dynamically Calculated Members
• Dynamically Calculated Children
• Choosing Between Dynamic Calc and Dynamic Calc and Store

Dense Members and Dynamic Calculation

Consider making the following changes to members of dense
dimensions:

• Tag upper level members of dense dimensions as Dynamic

Calc.
• Try tagging level 0 members of dense dimensions with simple
formulas as Dynamic Calc, and assess the increase in retrieval
time.
• Do not tag members of dense dimensions as Dynamic Calc
and Store.

Simple formulas are formulas that do not require Analytic Services to

perform an expensive calculation. Formulas containing, for example,
financial functions or cross-dimensional operators (->) are complex
formulas.

Sparse Members and Dynamic Calculation

Consider making the following changes to members of sparse
dimensions:

• 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 Analytic Services to perform an expensive
calculation. For example, any formula that contains a financial
function is a complex formula. For a discussion of complex
formulas (definition, guidelines for use, and effect on
performance), see Using Complex Formulas.
• 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.

For recommendations in regard to use of Dynamic Calc and Dynamic

Calc And Store, see Choosing Between Dynamic Calc and Dynamic
Calc and Store.

Two-Pass Members and Dynamic Calculation

To reduce the amount of time needed to perform batch calculations,
tag two-pass members as Dynamic Calc. You can tag any Dynamic
Calc or Dynamic Calc and Store member as two-pass, even if the
member is not on an accounts dimension.

For a comprehensive discussion of two-pass calculation, see Using

Two-Pass Calculation. For details about the interaction of members
tagged as two-pass and attribute members, see Comparing Attribute
and Standard Dimensions.
Parent-Child Relationships and Dynamic Calculation
If a parent member has a single child member and you tag the child as
Dynamic Calc, you must tag the parent as Dynamic Calc. Similarly, if
you tag the child as Dynamic Calc and Store, you must tag the parent
as Dynamic Calc and Store. However, if a parent member has a single
child member and the parent is a Dynamic Calc or Dynamic Calc and
Store member, you do not have to tag the child as Dynamic Calc or
Dynamic Calc and Store.

Calculation Scripts and Dynamic Calculation

When Analytic Services calculates, for example, a CALC ALL or CALC
DIM statement in a calculation script, it bypasses the calculation of
Dynamic Calc and Dynamic Calc and Store members.

Similarly, if a member set function (for example, @CHILDREN or

@SIBLINGS) is used to specify the list of members to calculate,
Analytic Services 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. If you want 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 
 

Formulas and Dynamically Calculated Members

You can include a dynamically calculated member in a formula when
you apply the formula to the database outline. For example, if Qtr1 is
a Dynamic Calc member, you can place the following formula on Qtr1
in the database outline:

Qtr1 = Jan + Feb; 
 

You cannot make a dynamically calculated member the target of a

formula calculation in a calculation script; Analytic Services does not
reserve memory space 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, Analytic Services
displays a syntax error if you include the following formula in a
calculation script:

Qtr1 = Jan + Feb; 
 

However, 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 Analytic Services is not assigning a value

to the dynamically calculated member.

Note: When you reference a dynamically calculated member in a

formula in the database outline or in a calculation script, Analytic
Services interrupts the regular calculation to do the dynamic
calculation. This interruption can significantly lower calculation
performance.

Dynamically Calculated Children

If the calculation of a member depends on the calculation of Dynamic
Calc or Dynamic Calc and Store child members, Analytic Services has
to calculate the child members first during the batch database
calculation in order to calculate the parent. Therefore, there is no
reduction in regular calculation time. This requirement applies to
members of sparse dimensions and members of dense dimensions.

For example, consider the following outline:

Figure 191: Sample Basic Outline, Showing Qtr1 as a Dynamic Calc

Member
Qtr1 is a Dynamic Calc member. Its children, Jan, Feb, and Mar, are
not dynamic members, and its parent, Year, is not a dynamic member.
When Analytic Services calculates Year during a batch database
calculation, it must consolidate the values of its children, including
Qtr1. Therefore, it must take the additional time to calculate Qtr1 even
though Qtr1 is a Dynamic Calc member.

Choosing Between
Dynamic Calc and
Dynamic Calc and
Store
In most cases you can optimize calculation performance and lower disk
usage by using Dynamic Calc members instead of Dynamic Calc and
Store members. However, in specific situations, using Dynamic Calc
and Store members is optimal:

• Recommendations for Sparse Dimension Members

• Recommendations for Members with Specific Characteristics
• Recommendations for Dense Dimension Members
• Recommendations for Data with Many Concurrent Users

Recommendations for Sparse Dimension Members

In most cases, when you want to calculate a sparse dimension
member dynamically, tag the member as Dynamic Calc instead of
Dynamic Calc and Store. When Analytic Services calculates data values
for a member combination that includes a Dynamic Calc member,
Analytic Services calculates only the requested values of the relevant
data block. These values can be a subset of the data block.
However, when Analytic Services calculates data values for a member
combination that includes a Dynamic Calc and Store member, Analytic
Services needs to calculate and store the whole data block, even if the
requested data values are a subset of the data block. Thus, the
calculation takes longer and the initial retrieval time is greater.

Analytic Services stores only the data blocks that contain the
requested data values. If Analytic Services needs to calculate any
intermediate data blocks in order to calculate the requested data
blocks, it does not store the intermediate blocks.

Calculating the intermediate data blocks can significantly increase the

initial retrieval time. For example, in the Sample Basic database,
Market and Product are the sparse dimensions. Assume that Market
and the children of Market are Dynamic Calc and Store members.
When a user retrieves the data value for the member combination
Market -> Cola -> Jan -> Actual -> Sales, Analytic Services calculates
and stores the Market -> Cola data block. In order to calculate and
store Market -> Cola, Analytic Services calculates the intermediate
data blocks-East?-> Cola, West -> Cola, South -> Cola, and Central ->
Cola. Analytic Services does not store these intermediate data blocks.

Recommendations for Members with Specific Characteristics

Using Dynamic Calc and Store may slow initial retrieval; however,
subsequent retrievals are faster than for Dynamic Calc members. Use
Dynamic Calc and Store instead of Dynamic Calc for the following
members:

• An upper-level sparse dimension member with children on a

remote database. Analytic Services needs to retrieve the
value from the remote database, which increases retrieval
time. For a detailed explanation of this situation, see
Dynamically Calculating Data in Partitions.
• A sparse dimension member with a complex formula. A
complex formula requires Analytic Services to perform an
expensive calculation. For example, any formula that contains
a financial function or a cross-dimensional member is a
complex formula.
• If users frequently retrieve an upper level member of a sparse
dimension, speedy retrieval time is very important.
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 192: Sample Basic Outline, Market is Dynamic Calc and Store
Member

Recommendations for Dense Dimension Members

Use Dynamic Calc members for dense dimension members. Defining
members as Dynamic Calc and Store on a dense dimension provides
only a small decrease in retrieval time and in batch calculation time. In
addition, database size (disk usage) does not decrease significantly
because Analytic Services reserves space in the data block for the data
values of the member.

Recommendations for Data with Many Concurrent Users

Use Dynamic Calc members for data with concurrent users. If many
users are concurrently retrieving Analytic Services data, the initial
retrieval time for Dynamic Calc and Store members can be significantly
higher than for Dynamic Calc members.

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 lower retrieval times if you use Dynamic Calc members
instead of Dynamic Calc and Store members.

Understanding How
Dynamic Calculation
Changes Calculation
Order
Using dynamically calculated data values changes the order in which
Analytic Services calculates the values and can have implications for
the way you administer a database:

• Calculation Order for Dynamic Calculation

• Calculation Order for Dynamically Calculating Two-Pass
Members
• Calculation Order for Asymmetric Data

Calculation Order for Dynamic Calculation

When Analytic Services dynamically calculates data values, it
calculates the data in an order that is different from the batch
database calculation order. For detailed information on calculation
order when dynamic calculation is not used, see Defining Calculation
Order.

During batch calculations, Analytic Services calculates the database in

this order:

1. Dimension tagged as accounts

2. Dimension tagged as time
3. Other dense dimensions (in the order they appear in the
database outline)
4. Other sparse dimensions (in the order they appear in the
database outline)
5. Two-pass calculations

For dynamically calculated values, on retrieval, Analytic Services

calculates the values by calculating the database in the following
order:

1. Sparse dimensions
o If the dimension tagged as time is sparse and the
database outline uses time series data, Analytic
Services bases the sparse calculation on the time
dimension.
 o Otherwise, Analytic Services 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

Note: If your data retrieval uses attribute members,

the last step in the calculation order is the summation
of the attributes. However, the use of attribute
members in your query causes Analytic Services 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 non-use 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.

Calculation Order for Dynamically Calculating Two-Pass

Members
Consider the following information to ensure that Analytic Services
produces the required calculation result when it dynamically calculates
data values for members that are tagged as two-pass. For a
comprehensive discussion of two-pass calculations, see Using Two-Pass
Calculation.
If more than one Dynamic Calc or Dynamic Calc and Store dense
dimension member is tagged as two-pass, Analytic Services performs
the dynamic calculation in the first pass, and then calculates the two-
pass members in the following order:

1. Two-pass members in the accounts dimension, if any exist.

2. Two-pass members in the time dimension, if any exist.
3. Two-pass members in the remaining dense dimensions in the
order in which the dimensions appear in the outline.

For example, in the Sample Basic database, assume the following:

• Margin% in the dense Measures dimension (the dimension

tagged as accounts) is tagged as both Dynamic Calc and two-
pass.
• Variance in the dense Scenario dimension is tagged as both
Dynamic Calc and two-pass.

Analytic Services calculates the accounts dimension member first. So,

Analytic Services calculates Margin% (from the Measures dimension)
and then calculates Variance (from the Scenario dimension).

If Scenario is a sparse dimension, Analytic Services calculates Variance

first, following the regular calculation order for dynamic calculations.
For a description of calculation order for dynamic calculations, see
Calculation Order for Dynamic Calculation. Analytic Services then
calculates Margin%.

This calculation order does not produce the required result because
Analytic Services 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 Analytic Services still calculates Margin% first.

Calculation Order for Asymmetric Data

Because the calculation order used for dynamic calculations differs
from the calculation order used for batch database calculations, in
some database outlines you may get different calculation results if you
tag certain members as Dynamic Calc or Dynamic Calc and Store.
These differences happen when Analytic Services dynamically
calculates asymmetric data.
Symmetric data calculations produce the same results no matter which
dimension is calculated. Asymmetric data calculations calculate
differently along different dimensions.

Table 25: Example of a Symmetric Calculation

Time -> Accounts Jan Feb Mar Qtr1

Sales 100 200 300 600

COGS 50 100 150 300

Profit 50 100 150 300

(Sales - COGS)

The calculation for Qtr1-> Profit produces the same result whether you
calculate along the dimension tagged as time or the dimension tagged
as accounts. Calculating along the time dimension, add the values for
Jan, Feb, and Mar:

50+100+150=300  
 

Calculating along the accounts dimension, subtract Qtr1 -> COGS from
Qtr1 -> Sales:

600­300=300  
 

Table 26: Example of an Asymmetric Calculation

Market -> Accounts New York Florida Connecticut East

UnitsSold 10 20 20 50

Price 5 5 5 15

Sales 50 100 100 250

(Price * UnitsSold)
The calculation for East -> Sales produces the correct result when you
calculate along the Market dimension, but produces an incorrect result
when you calculate along the accounts dimension. Calculating along
the Market dimension, adding the values for New York, Florida, and
Connecticut produces the correct results:

50+100+100=250  
 

Calculating along the accounts dimension, multiplying the value East

-> Price by the value East -> UnitsSold produces incorrect results:

15 * 50=750 
 

In this outline, East is a sparse dimension, and Accounts is a dense

dimension:

If East and Sales are tagged as Dynamic Calc, then Analytic Services
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, Analytic Services
produces the correct result by calculating as follows:

1. The dense Accounts dimension, calculating the values for

UnitsSold, Price, and Sales for New York, Florida, and
Connecticut.
2. The sparse East dimension, by aggregating 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, Analytic Services

produces an incorrect result by calculating as follows:

1. The sparse East dimension, by aggregating the values for

UnitsSold, Price, and Sales for New York, Florida, and
Connecticut to obtain the values for East.
 2. The values for East -> Sales, by taking 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.

Reducing the Impact

on Retrieval Time
The increase in retrieval time when you dynamically calculate a
member of a dense dimension is not significant unless the member
contains a complex formula. The increase in retrieval time may be
significant when you tag members of sparse dimensions as Dynamic
Calc or Dynamic Calc and Store.

The following sections discuss ways you can analyze and manage the
effect of Dynamic Calc members on a database:

• Displaying a Retrieval Factor

• Displaying a Summary of Dynamically Calculated Members
• Increasing Retrieval Buffer Size
• Using Dynamic Calculator Caches

Note: For a list of functions that have the most significant effect on
query retrieval, see Choosing Between Member Set Functions and
Performance for details.

Displaying a Retrieval Factor

To help you estimate any increase in retrieval time, Analytic Services
calculates a retrieval factor for a database outline when you save the
outline. Analytic Services calculates this retrieval factor based on the
dynamically calculated data block that is the most expensive for
Analytic Services to calculate. The retrieval factor takes into account
only aggregations. It does not consider the retrieval impact of
formulas.
The retrieval factor is the number of data blocks that Analytic Services
must retrieve from disk or from the database in order to calculate the
most expensive block. If the database has Dynamic Calc or Dynamic
Calc and Store members in dense dimensions only (no Dynamic Calc
or Dynamic Calc and Store members in sparse dimensions), the
retrieval factor is 1.

An outline with a high retrieval factor (for example, greater than 2000)
can cause long delays when users retrieve data. However, the actual
impact on retrieval time also depends on how many dynamically
calculated data values a user retrieves. The retrieval factor is only an
indicator. In some applications, using Dynamic Calc members may
reduce retrieval time because the database size and index size are
reduced.

Analytic Services displays the retrieval factor value in the application

log.

To view an estimated retrieval factor, see Viewing the Analytic Server

and Application Logs.

A message similar to this sample indicates a retrieval factor:

[Wed Sep 20 20:04:13 2000] Local/Sample///Info (1012710)
Essbase needs to retrieve [1] Essbase kernel blocks in order
to calculate the top dynamically­calculated block. 
 

This message tells you that Analytic Services needs to retrieve one
block in order to calculate the most expensive dynamically calculated
data block.

Displaying a Summary of Dynamically Calculated Members

When you add Dynamic Calc or Dynamic Calc and Store members to a
database outline and save the outline, Analytic Services provides a
summary of how many members are tagged as Dynamic Calc and
Dynamic Calc and Store. Analytic Services displays the summary in the
application log.

To view a summary of dynamically calculated members, see Viewing

the Analytic Server and Application Logs.
A message similar to this sample is displayed:

[Wed Sep 20 20:04:13 2000]Local/Sample///Info(1007125)
The number of Dynamic Calc Non­Store Members = [ 8 6 0 0 2]

[Wed Sep 20 20:04:13 2000]Local/Sample///Info(1007126)
The number of Dynamic Calc Store Members = [ 0 0 0 0 0] 
 

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.

Increasing Retrieval Buffer Size

When you retrieve data into Spreadsheet Services or use Report Writer
to retrieve data, Analytic Services uses the retrieval buffer to optimize
the retrieval. Analytic Services processes the data in sections.
Increasing the retrieval buffer size can significantly reduce retrieval
time because Analytic Services can process larger sections of data at
one time.

By default, the retrieval buffer size is 10 KB. However, you may speed
up retrieval time if you set the retrieval buffer size greater than 10 KB.
For information about sizing the retrieval buffer, see Setting the
Retrieval Buffer Size.

Use any of the following methods to set the retrieval buffer size:

Tool Topic Location

Administration Setting the Size of Essbase XTD

Services Retrieval Buffers Administration Services
Online Help

MaxL alter database Technical Reference

ESSCMD SETDBSTATEITEM Technical Reference

Using Dynamic Calculator Caches
By default, when Analytic Services calculates a Dynamic Calc member
in a dense dimension (for example, for a query), it writes all blocks
needed for the calculation into an area in memory called the dynamic
calculator cache. When Analytic Services writes these blocks into the
dynamic calculator cache, it expands them to include all Dynamic Calc
members in the dense dimensions.

Using the Analytic Services dynamic calculator cache enables

centralized control of memory usage for dynamic calculations.
Managing data blocks in the dynamic calculator cache also reduces the
overall memory space requirement and can improve performance by
reducing the number of calls to the operating system to do memory
allocations.

Note: The dynamic calculator cache and the calculator cache use
different approaches to optimizing calculation performance.

For details about sizing and reviewing dynamic calculator cache usage,
see Sizing the Calculator Cache.

Reviewing Dynamic Calculator Cache Usage

Analytic Services writes two messages to the application log for each
data retrieval. As shown in the example in Figure?193, the first
message describes the total amount of time required for the retrieval.

Figure 193: Application Log Example of Memory Usage for Data Blocks
Containing Dynamic Calc Members

[Thu Aug 03 14:33:00 
2000]Local/Sample/Basic/aspen/Info(1001065)
Regular Extractor Elapsed Time : [0.531] seconds

[Thu Aug 03 14:33:00 
2000]Local/Sample/Basic/aspen/Info(1001401)
Regular Extractor Big Blocks Allocs ­­ Dyn.Calc.Cache : [30] 
non­Dyn.Calc.Cache : [0] 
 

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 if the dynamic calculator cache is being used effectively,

review both of these messages and consider what your settings are in
the essbase.cfg file. For example, if the message indicates that
blocks were calculated outside as well as in a dynamic calculator
cache, you may need to 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 GETPERFSTATS command in ESSCMD to view a

summary of dynamic calculator cache activity. See the Technical
Reference for information about GETPERFSTATS.

Using Dynamic
Calculations with
Standard Procedures
Using dynamic calculations with standard Analytic Services procedures
affects these processes:

• Clearing data and data blocks

You can use the CLEARBLOCK DYNAMIC command to remove

data blocks for Dynamic Calc and Store member combinations.
You can use the CLEARDATA command to mark Dynamic Calc
and Store data blocks, so that Analytic Services knows to
recalculate the blocks. The CLEARDATA command has no effect
on data values for Dynamic Calc members.
• 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, Analytic Services does not load data into
member combinations that contain a Dynamic Calc or Dynamic
Calc and Store member. Analytic Services skips these members
during data load. Analytic Services does not display an error
message.
To place data into Dynamic Calc and Dynamic Calc and Store
members, after loading data, you need to ensure that Analytic
Services recalculates Dynamic Calc and Store members. For an
explanation of how to ensure that Analytic Services recalculates
Dynamic Calc and Store members, see Effect of Updated Values
on Recalculation.
• Exporting data

Analytic Services does not calculate dynamically calculated

values before exporting data. Analytic Services does not export
values for Dynamic Calc members. Analytic Services exports
values for Dynamic Calc and Store members only if a calculated
value exists in the database from a previous user retrieval of the
data.
• Reporting data

Analytic Services 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. For more information, see
the <SPARSE command in the Technical Reference.
• Including dynamic members in calculation scripts

When calculating a database, Analytic Services skips the

calculation of any Dynamic Calc or Dynamic Calc and Store
members. Analytic Services displays an error message if you
attempt to do a member calculation of a Dynamic Calc or
Dynamic Calc and Store member in a calculation script. For an
 explanation of the relationship of Dynamic Calc and Dynamic
Calc and Store members and calculation passes, see Calculation
Scripts and Dynamic Calculation.

Creating Dynamic Calc

and Dynamic Calc and
Store Members
To create Dynamic Calc and Dynamic Calc and Store members using
Outline Editor, see "Setting Member Storage Properties" in Essbase
XTD Administration Services Online Help.
To create Dynamic Calc and Dynamic Calc and Store members
during a dimension build, in the dimension build data file, use the
property X for Dynamic Calc and the property V for Dynamic Calc and
Store. For information on how to place X and V in the data source, see
Using the Data Source to Set Member Properties.

Restructuring
Databases
When you add a Dynamic Calc member to a dense dimension, Analytic
Services does not reserve space in the data block for the member's
values. Therefore, Analytic Services does not need to restructure the
database. However, when you add a Dynamic Calc and Store member
to a dense dimension, Analytic Services does reserve space in the
relevant data blocks for the member's values and therefore needs to
restructure the database.

When you add a Dynamic Calc or a Dynamic Calc and Store member to
a sparse dimension, Analytic Services updates the index, but does not
change the relevant data blocks. For information on managing the
database index, see Index Manager.
Analytic Services can save changes to the database outline
significantly faster if it does not have to restructure the database.

In the following cases, Analytic Services does not restructure the

database. Analytic Services only has to save the database outline,
which is very fast. Analytic Services does not restructure the database
or change the index when you do any of the following:

• Add, delete, or move a dense dimension Dynamic Calc

member. (But Analytic Services does restructure the database
if the member is Dynamic Calc and Store.)
• Change the storage property of a dense dimension member
from Dynamic Calc and Store member to a non-dynamic
storage property
• Change the storage property of a sparse dimension Dynamic
Calc or Dynamic Calc and Store member to a non-dynamic
storage property
• Rename any Dynamic Calc or Dynamic Calc and Store
member

In the following cases, Analytic Services does not restructure the

database, but does have to restructure the database index.
Restructuring the index is significantly faster than restructuring the
database.

Analytic Services restructures only the database index when you do

either of the following:

• 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 non-dynamic value to Dynamic Calc and Store

However, Analytic Services does restructure the database when you do

any of the following:

• Add, delete, or move a dense dimension Dynamic Calc and

Store member. (But Analytic Services 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
• Change the storage property of a non-dynamic member in a
dense dimension to Dynamic Calc
 • Change the storage property of a dense dimension from
Dynamic Calc member to a non-dynamic value
• Change the storage property of a non-dynamic member in a
sparse dimension Dynamic Calc or Dynamic Calc and Store

For detailed information on the types of database restructuring, see

Types of Database Restructuring.

Dynamically Calculating
Data in Partitions
You can define Dynamic Calc and Dynamic Calc and Store members in
transparent, replicated, or linked regions of the partitions. For a
comprehensive discussion of partitions, see Designing Partitioned
Applications.

For example, you might want to tag an upper level, sparse dimension
member with children that are on a remote database (transparent
database partition) as Dynamic Calc and Store. Because Analytic
Services needs to retrieve the child values from the other database,
retrieval time is increased. You can use Dynamic Calc instead of
Dynamic Calc and Store; however, the impact on subsequent retrieval
time might be too great.

For example, assume that the local database is the Corporate

database, which has transparent partitions to the regional data for
East, West, South, and Central. You can tag the parent member
Market as Dynamic Calc and Store.

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, Analytic Services retrieves the value from the
remote database and does not do the local calculation.

If you are using a replicated partition, then you might want to use
Dynamic Calc members instead of Dynamic Calc and Store members.
When calculating replicated data, Analytic Services does not retrieve
the child blocks from the remote database, and therefore the impact
on retrieval time is not great.
Note: When Analytic Services 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, Analytic
Services replicates the data in the data block. However, for
dynamically calculated data, data blocks and time stamps do not
exist. Therefore Analytic Services always replicates dynamically
calculated data.

Calculating Time Series

Data
This chapter explains how to calculate time series data. For example,
you can do inventory tracking by calculating the first and last values
for a specific time period. You can also calculate period-to-date values.

This chapter includes the following sections:

• Calculating First, Last, and Average Values

• Calculating Period-to-Date Values
• Using Dynamic Time Series Members in Partitions

Calculating First, Last,

and Average Values
Using time balance and variance reporting tags on the dimension
tagged as accounts, you can tell Analytic Services how to perform time
balance calculations on accounts data.

Analytic Services usually calculates a parent in the dimension tagged

as time by?consolidating or calculating the formulas on the parent's
children. However, you?can use accounts tags, such as time balance
and variance reporting tags, to consolidate a different kind of value.
For example, if you tag a parent member in the accounts dimension
with a time balance property of First, Analytic Services calculates the
member by consolidating the value of the member's first child. For
example, in the Sample Basic database, the Opening Inventory
member in the Measures dimension (the accounts dimension) has a
time balance property of First. This member represents the inventory
at the beginning of the time period. If the time period is Qtr1, Opening
Inventory represents the inventory available at the beginning of Jan
(the first member in the Qtr1 branch).

To use accounts tags, you must have a dimension tagged as accounts

and a dimension tagged as time. You use the First, Last, and Average
tags (time balance properties) and the Expense tag (variance reporting
property) only on members of a dimension tagged as accounts. The
dimensions you tag as time and accounts can be either dense or
sparse dimensions.

Note: If you are using Intelligent Calculation, changing accounts

tags in the?database outline does not cause Analytic Services to
restructure the database. You may have to tell Analytic Services
explicitly to recalculate the required data values. For a discussion of
how and why to perform a recalculation, see Changing Formulas
and Accounts Properties.

Specifying Accounts and Time Dimensions

When you tag a dimension as accounts, Analytic Services knows that
the dimension contains members with accounts tags. When you tag a
dimension as time, Analytic Services knows that this dimension is the
one on which to base the time periods for the accounts tags.

In the Sample Basic database, the Measures dimension is tagged as

accounts, and the Year dimension is tagged as time.

Figure 194: Sample Basic Outline Showing Accounts and Time Tags

For information on tagging accounts and time dimensions, see

Creating a Time Dimension and Creating an Accounts Dimension.
Reporting the Last Value for Each Time Period
For an accounts dimension member, you can tell Analytic Services to
move the last value for each time period up to the next level. To report
the last value for each time period, set the member's time balance
property as Last. (In the database outline, the TB Last tag is
displayed.)

For example, in the Sample Basic database, the accounts member

Ending Inventory consolidates the value for the last month in each
quarter and uses that value for that month's parent. For example, the
value for Qtr1 is the same as the value for Mar.

Figure 195: Sample Basic Outline Showing Last Tag

For information on tagging an accounts member as Last, see Setting

Time Balance Properties.

By default, Analytic Services 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.

Reporting the First Value for Each Time Period

For an accounts dimension member, you can tell Analytic Services to
move the first value for each time period up to the next level. To
report the first value for each time period, set the member's time
balance property as First. (The tag displays as TB First in the database
outline.)

For example, in the Sample Basic database, the accounts member

Opening Inventory consolidates the value of the first month in each
quarter and uses that value for that month's parent. For example, the
value for Qtr1 is the same as the value for Jan.

Figure 196: Sample Basic Outline Showing First Tag

For information on tagging an accounts member as First, see Setting

Time Balance Properties.

By default, Analytic Services 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.

Reporting the Average Value for Each Time Period

For an accounts dimension member, you can tell Analytic Services to
average values across time periods and consolidate the average up to
the next level. For example, you can tell Analytic Services to average
the values for Jan, Feb, and Mar and then use that value for the Qtr1
value. To report the average value for each?time period, set the
member's time balance property as Average.

For information on tagging an accounts member as Average, see

Setting Time Balance Properties.

By default, Analytic Services does not skip #MISSING or zero (0)

values when it calculates a parent value. Thus, when it calculates the
average, Analytic Services aggregates the child values and divides by
the number of children, regardless of whether the children have
#MISSING or zero values. You can tell Analytic Services to skip
#MISSING and zero values. For a discussion of how and why to skip
#MISSING values, see Skipping #MISSING and Zero Values.
Skipping #MISSING and Zero Values
You can tell Analytic Services how to treat #MISSING and zero (0)
values when doing time balance calculations. A #MISSING value is a
marker in Analytic Services that indicates that the data in this location
does not exist, does not contain any meaningful value, or was never
entered.

By default, Analytic Services does not skip #MISSING or 0 (zero)

values when calculating a parent value.

You can override this default by setting a skip property. For a

discussion of how skip properties work, see Setting Skip Properties.

For example, if you tag an accounts dimension member as Last and

Skip Missing, then Analytic Services consolidates the last non-missing
child to the parent. Consider the following example:

Accounts -> Time Jan Feb Mar Qtr1

Accounts Member 60 70 #MI 70

(Last, Skip Missing)

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.

Considering the Effects of First, Last, and Average Tags

The following table shows how Analytic Services consolidates the time
dimension based on the time balance (TB) First, Last, and Average
tags on accounts dimension members.

Accounts -> Time Jan Feb Mar Qtr1

Accounts Member1 11 12 13 36 Value of

Jan+Feb+Mar
Accounts Member2 20 25 21 20 Value of Jan
(TB?First)

Accounts Member3 25 21 30 30 Value of Mar

(TB?Last)

Accounts Member4 20 30 28 26 Average of Jan,

(TB?Average) Feb, Mar

Placing Formulas on Time and Accounts Dimensions

If you place a member formula on a time or accounts dimension, it
may be overwritten by a time balance calculation.

Consider the following example from Sample Basic, in which Opening

Inventory is tagged as First:

Measures -> Year Jan Feb Mar Qtr1

Opening Inventory: First 30000 28000 27000 30000

Because Opening Inventory is tagged as First, Analytic Services

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.

Calculating Period-to-
Date Values
You can calculate period-to-date values for data. For example, you can
calculate the sales values for the current quarter up to the current
month. If the current month is May, using a standard calendar quarter,
the quarter total is the total of the values for April and May.
In Analytic Services, you can calculate period-to-date values in two
ways:

• During a batch calculation, using the @PTD function

• 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 period-to-date values. Using Dynamic Time
Series members is the most efficient method in almost all cases. For
an example using the @PTD function to calculate period-to-date
values, see Calculating Period-to-Date Values.

Using Dynamic Time Series Members

In order to calculate period-to-date values dynamically, you need to
use a Dynamic Time Series member for a period on the dimension
tagged as time. See Specifying Accounts and Time Dimensions.

You do not create the Dynamic Time Series member directly in the
database outline. Instead, you enable a predefined Dynamic Time
Series member and associate it with an appropriate generation
number. This procedure creates a Dynamic Time Series member for
you.

For example, if you want to calculate quarter-to-date values, you

enable the Q-T-D member and associate it with the generation to
which you want to apply the Dynamic Time Series member. In Sample
Basic, the generation containing quarters is generation number 2,
which contains the Qtr1, Qtr2, Qtr3, and Qtr4 members. Analytic
Services creates a Dynamic Time Series member called Q-T-D and
associates it with generation 2. The Q-T-D member calculates monthly
values up to the current month in the quarter. For a brief discussion,
see Enabling Dynamic Time Series Members.

Figure 197: Sample Basic Outline Showing Time Dimension

Dynamic Time Series members are not displayed as members in the
database outline. Instead, Analytic Services lists the currently active
Dynamic Time Series members in a comment on the time dimension.
In the following outline, H-T-D (history-to-date) and Q-T-D (quarter-to-
date) are active. H-T-D is associated with generation 1; Q-T-D is
associated with generation 2.

Figure 198: Sample Basic Outline Showing Dynamic Time Series

Analytic Services provides eight predefined Dynamic Time Series

members:

H-T-D 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 eight members provide up to eight levels of period-to-date

reporting. How many members you use 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 might want to report day-to date (D-T-
D), week-to-date (W-T-D), month-to-date (M-T-D), quarter-to-date (Q-
T-D), and year-to-date (Y-T-D) information.

If the database contains monthly data for the past 5 years, you might
want to report year-to-date (Y-T-D) and history-to-date (H-T-D)
information, up to a specific year.

If the database tracks data for seasonal time periods, you might want
to 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,
irrespective of the data. For example, if you choose, you can use the P-
T-D member to report quarter-to-date information. You cannot
associate Dynamic Time Series members with level 0 members of the
time dimension.

Note: We recommend 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.

Enabling Dynamic Time Series Members

To use Dynamic Time Series members, you need to enable them. If
required, you can specify aliases for Dynamic Time Series members.
For a brief discussion, see Specifying Alias Names for Dynamic Time
Series Members.

To enable Dynamic Time Series members, see "Enabling Dynamic

Time Series Members" in the Essbase XTD Administration Services
Online Help.

Note: The number of generations displayed depends on the number

of generations in the time 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, Analytic Services adds a comment to the dimension tagged as
time. Figure?199 shows the Sample Basic database with H-T-D and Q-
T-D defined.

Figure 199: Sample Basic Outline Showing Dynamic Time Series

Members

Year Time (Active Dynamic Time Series Members: H­T­D, Q­T­D) 
(Dynamic Calc) 
 
Disabling Dynamic Time Series Members
To disable a Dynamic Time Series member, tell Analytic Services not to
use the predefined member.

To disable Dynamic Time Series members, see "Disabling Dynamic

Time Series Members" in the Essbase XTD Administration Services
Online Help.

Specifying Alias Names for Dynamic Time Series Members

You can specify alias names for predefined Dynamic Time Series
members, such as QtrToDate, for the Q-T-D Dynamic Time Series
member. You can then use the alias names to retrieve the Dynamic
Time Series members in Spreadsheet Services, Spreadsheet Add-in, or
in a report.

You can create up to eight alias names for each Dynamic Time Series
member. Analytic Services saves each alias name in the Dynamic Time
Series alias table that you specify.

To create aliases for Dynamic Time Series members, see "Creating

Aliases for Dynamic Time Series Members" in the Essbase XTD
Administration Services Online Help.

For information on specifying and displaying alias names, see Setting

Aliases.

Applying Predefined Generation Names to Dynamic Time Series

Members
When you enable a Dynamic Time Series member and associate it with
a generation number, Analytic Services creates a predefined
generation name for that generation number. For information on
creating generation names, see Naming Generations and Levels.

To display generation and level names, see "Naming Generations and

Levels" in the Essbase XTD Administration Services Online Help.

The following table shows the Dynamic Time Series members and their
corresponding generation names:
Member Generation Name Member Generation Name

H-T-D History Q-T-D Quarter

Y-T-D Year M-T-D Month

S-T-D Season W-T-D Week

P-T-D Period D-T-D Day

These member and generation names are reserved for use by Analytic
Services. If you use one of these generation names to create a
generation name on the time dimension, Analytic Services
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, Analytic Services creates and enables a
Dynamic Time Series member called Q-T-D.

Retrieving Period-to-Date Values

When you retrieve a Dynamic Time Series member, you need to tell
Analytic Services the time period up to which you want to calculate the
period-to-date value. This time period is known as the latest time
period and must be a level 0 member on the time dimension.

Use the following methods to specify the latest time period:

• For a specific member, in Spreadsheet Services or
Spreadsheet Add-in, 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:
o Use the <LATEST command in Report Writer.
o Specify the Latest Time Period option in the
Essbase?Options dialog box in Spreadsheet Add-in or
the Essbase Spreadsheet Preferences Dialog Box in
 Spreadsheet Services. For more information, see the
relevant spreadsheet online help.

The member-specific setting-for example, Q-T-D(May)-takes

precedence over the <LATEST or Latest Time Series option setting.

The following example shows Sample Basic data. 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 200: Spreadsheet Showing Period-To-Date Value for May

Using Dynamic Time

Series Members in
Partitions
If Dynamic Time Series members are part of the shared area between
databases, define the Dynamic Time Series members in both
databases, just as you would for regular members. For example, if the
partition definition includes Qtr1, Qtr2, Qtr3, Qtr4, and the Dynamic
Time Series member Q-T-D, define the Q-T-D member in both the
source database and the target database.

If a Dynamic Time Series member is not part of the shared area

between databases, Analytic Services gets the data for that member
from the source database. You do not need to define the Dynamic
Time Series member in both databases. However, this configuration is
generally less efficient than including the Dynamic Time Series
member in the partition definition.
For a comprehensive discussion of partitioning, see Creating and
Maintaining Partitions.

Developing Calculation
Scripts
This chapter explains how to develop calculation scripts and how to
use them to control the way Analytic Services calculates a database.
This chapter provides some examples of calculation scripts, which you
may want to adapt for your own use. This chapter also shows you how
to create and execute a simple calculation script.

This chapter includes the following sections:

• Understanding Calculation Scripts

• Understanding Calculation Script Syntax
• Planning Calculation Script Strategy
• Reviewing the Process for Creating Calculation Scripts

For a comprehensive discussion of developing formulas, which may be

used in calculation scripts or in an outline, see Developing Formulas.
For more examples, see Reviewing Examples of Calculation Scripts.

For information about copying, renaming, locking, and deleting

calculation scripts, see Using Analytic Services to Manage Objects.

Understanding
Calculation Scripts
A calculation script contains a series of calculation commands,
equations, and formulas. You use a calculation script to define
calculations other than the calculations that are defined by the
database outline.

Calculation scripts are ASCII text. Using Calculation Script Editor, you
can create calculation scripts by:
 • Typing the contents of the calculation script directly into the
text area of the script editor
• Using the user interface features of the script editor to build
the script
• Creating the script in the text editor of your choice and
pasting it into Calculation Script Editor.

When you save a calculation script, it is given a .csc extension by

default. If you run a calculation script from Essbase XTD
Administration Services or from Essbase XTD Spreadsheet Services, it
must have a .csc extension. However, since a calculation script is
basically a text file, you can use MaxL or ESSCMD to run any text file
as a calculation script.

For more information about Calculation Script Editor, see "About

Calculation Script Editor" in Essbase XTD Administration Services
Online Help.

For example, the following calculation script calculates the Actual

values in the Sample Basic database.

FIX (Actual)
CALC DIM(Year, Measures, Market, Product);
ENDFIX 
 

You can use a calculation script to specify exactly how you want
Analytic Services to calculate a database. For example, you can
calculate part of a database or copy data values between members.
You can design and run custom database calculations quickly by
separating calculation logic from the database outline.

Analytic Services allows you to perform a default calculation (CALC

ALL) or a calculation of your own choosing that you specify in a
calculation script to control how Analytic Services calculates a
database.

For example, you need to write a calculation script if you want to do

any of the following:

• Use the FIX command to calculate a subset of a database. For

more information, see Using the FIX Command and the
Technical Reference.
 • 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. For?a comprehensive discussion of two-pass
calculation, see Using Two-Pass Calculation.
• Perform a currency conversion. For a comprehensive
discussion of currency conversion, see Designing and Building
Currency Conversion Applications.
• 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, if you
want to use the IF?...?ELSE?...?ENDIF or the
LOOP?...?ENDLOOP commands.
• Clear or copy data from specific members. For an example of
copying data, see Copying Data.
• Define temporary variables for use in a database calculation.
For a discussion on how to declare temporary variables, see
Declaring Data Variables.
• Force a recalculation of data blocks after you have changed a
formula or an?accounts property on the database outline.
• Control how Analytic Services uses the Intelligent Calculation
feature when calculating a database. For a comprehensive
discussion of intelligent calculation, see Optimizing with
Intelligent Calculation.

Understanding
Calculation Script
Syntax
Analytic Services provides a flexible set of commands that you can use
to control how a database is calculated. You can construct calculation
scripts from commands and formulas. In Calculation Script Editor, the
different elements of the script are color-coded to aid in script
readability.

Computation, control of flow, and data declarations are discussed in

the following sections. For a full list of calculation script commands,
see the Technical Reference.

• Understanding the Rules for Calculation Script Syntax

• Understanding Calculation Commands
• Controlling the Flow of Calculations
• Declaring Data Variables
• Specifying Global Settings for a Database Calculation
• Adding Comments

Understanding the Rules for Calculation Script Syntax

When you create a calculation script, you need to apply the following
rules:

• End each formula or calculation script command with a

semicolon (;), as shown in these examples.
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;
You do not need to end the following commands with
semicolons-IF, ENDIF, ELSE, ELSEIF, FIX, ENDFIX, LOOP, and
ENDLOOP.
Although ending ENDIF statements with a semicolon (;) is not
required, it is good practice to follow each ENDIF statement in a
formula with a semicolon.
• Enclose a member name in double quotation marks (" ") if
that member name meets any of the following conditions:
o Contains spaces; for example,

"Opening Inventory" = "Ending Inventory" ­ Sales + 
Additions; 
o Is the same as an operator or function name. For a list
of operator and functions names, see Understanding the
Rules for Naming Dimensions and Members.
o Includes any non-alphanumeric character; for example,
hyphen (-), asterisk (*), and slash (/ ). For a complete
list of special characters, see Understanding the Rules
for Naming Dimensions and Members.
o Contains only numerals or starts with a numeral; for
example, "100" or "10Prod".
o Begins with an ampersand (&). The leading ampersand
(&) is reserved for substitution variables. If a member
name begins with &, enclose it in quotation marks. Do
not enclose substitution variables in quotation marks in
a calculation script.
o Contains a dot (.); for example, 1999.Jan or .100.
• If you are using an IF statement or an interdependent
formula, enclose the formula in parentheses to associate it
with the specified member. For example, the following formula
is associated with the Commission member in the database
outline:
• Commission 
• (IF(Sales < 100)
•    Commission = 0;
• ENDIF;)
• End each IF statement in a formula with an ENDIF statement.
For example, the previous formula contains a simple
IF...ENDIF statement.
 • If you are using an IF statement that is nested within another
IF statement, end each IF with an ENDIF statement; 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
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 in between) rather

than ELSEIF (one word) in a formula, you must supply an
ENDIF for the IF statement.

• End each FIX statement with an ENDFIX statement; for

example:
• FIX(Budget,@DESCENDANTS(East))
• CALC DIM(Year, Measures, Product);
ENDFIX 

When you write a calculation script, you can use the Calculation Script
Editor syntax checker to check the syntax. For a brief discussion of the
syntax checker, see Checking Syntax.
Note: For detailed information on calculation script syntax, see the
Technical Reference.

Understanding Calculation Commands

You can use the following calculation commands to perform a database
calculation that is based on the structure and formulas in the database
outline.

Note: For a complete list of calculation commands and syntax, see

the Technical Reference.

Calculation Command

The entire database, based on the outline CALC ALL

A specified dimension or dimensions CALC DIM

All members tagged as two-pass on the CALC

dimension tagged as accounts TWOPASS

The formula applied to a member in the membername

database outline, where membername is the
name of the member to which the formula is
applied

All members tagged as Average on the CALC AVERAGE

dimension tagged as accounts

All members tagged as First on the dimension CALC FIRST

tagged as accounts

All members tagged as Last on the dimension CALC LAST

tagged as?accounts

Currency conversions CCONV

Controlling the Flow of Calculations
You can use the following commands to manipulate the flow of
calculations. For detailed information on these commands, see the
Technical Reference.

Calculation Commands

Calculate a subset of a database FIX?...?ENDFIX

Specify the number of times that LOOP?...?ENDLOOP

commands are iterated

You can also use the IF and ENDIF commands to specify conditional
calculations.

Note: You cannot branch from one calculation script to another

calculation script.

Declaring Data Variables

You can use the following commands to declare temporary variables
and, if required, to set their initial values. Temporary variables store
the results of intermediate calculations.

You can also use substitution variables in a calculation script. For a

discussion where, why, and how to use substitution variables, see
Using Substitution Variables in Calculation Scripts.

Calculation Commands

Declare one-dimensional array variables ARRAY

Declare a temporary variable that contains a single VAR

value

For detailed information on the these commands, see the Technical

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

• Alphabetic letters: a through z

• Numerals: 0 through 9
• Special characters: $(dollar sign), # (pound sign), and _
(underscore)

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. You can use more than one array at
a time.

ARRAY Discount[Scenario]; 
 

Specifying Global Settings for a Database Calculation

You can use the following commands to define calculation behavior. For
a detailed discussion of each specific command, see the Technical
Reference.

Calculation Command

To specify how Analytic Services SET AGGMISSG

treats #MISSING values during a
calculation

To adjust the default calculator cache SET CACHE

size

To enable parallel calculation (see SET CALCPARALLEL

Using Parallel Calculation)

To increase the number of SET CALCTASKDIMS

dimensions used to identify tasks for
parallel calculation (see Using Parallel
Calculation)

To optimize the calculation of sparse SET FRMLBOTTOMUP

dimension formulas in large database
outlines (see Optimizing Formulas on
Sparse Dimensions in Large Database
Outlines)

To display messages to trace a SET MSG

calculation. SET NOTICE

To turn on and turn off Intelligent SET UPDATECALC

Calculation (see Turning Intelligent
Calculation On and Off)

To control how Analytic Services SET CLEARUPDATESTATUS

marks data blocks for the purpose of
Intelligent Calculation (see Using the
SET CLEARUPDATESTATUS
Command)

To specify the maximum number of SET LOCKBLOCK

blocks that Analytic Services can lock
concurrently when calculating a
sparse member formula

To turn on and turn off the Create SET CREATEBLOCKEQ

Blocks on Equation setting. This
setting controls creation of blocks
when you assign non-constant values
to members of a sparse dimension
(see Non-Constant Values Assigned
to Members in a Sparse Dimension

To enable calculations on potential SET

data blocks and save these blocks CREATENONMISSINGBLK
when the result is not #MISSING.

For currency conversions, to restrict SET UPTOLOCAL

aggregations to parents that have
the same defined currency (see
Calculating Databases)

A SET command in a calculation script stays in effect until the next

occurrence of the same SET command.

Consider the following calculation script:

SET MSG DETAIL;
CALC DIM(Year); 
 SET MSG SUMMARY;
CALC DIM(Measures); 
 

Analytic Services displays messages at the detail level when

calculating the Year dimension. However, when calculating the
Measures dimension, Analytic Services displays messages at the
summary level.

Some SET calculation commands trigger additional passes through the

database. Consider this calculation script:

SET AGGMISSG ON;
Qtr1; 
 SET AGGMISSG OFF;
East; 
 

Analytic Services calculates member combinations for Qtr1 with SET

AGGMISSG (aggregate missing values) turned on. Analytic Services
then does a second calculation pass through the database and
calculates member combinations for East with SET AGGMISSG turned
off. For more information on the setting for aggregating missing
values, see the SET AGGMISSG command in the Technical Reference.
For more information on calculation passes, see Using Two-Pass
Calculation.
Adding Comments
You can include comments to annotate calculation scripts. Analytic
Services ignores these comments when it runs the calculation script.

To include a comment, start the comment with /* and end the

comment with */. Consider the following comment:

/*   This is a calculation script comment
     that spans two lines.*/ 
 

Planning Calculation
Script Strategy
You can type a calculation script directly into the text area of
Calculation Script Editor, or you can use the user interface features of
Calculation Script Editor to build the calculation script.

• Using Formulas in a Calculation Script

• Using a Calculation Script to Control Intelligent Calculation
• Grouping Formulas and Calculations
• Calculating a Series of Member Formulas
• Calculating a Series of Dimensions
• Using Substitution Variables in Calculation Scripts
• Clearing Data
• Copying Data
• Calculating a Subset of a Database
• Enabling Calculations on Potential Blocks
• Writing Calculation Scripts for Partitions
• Controlling Calculation Order for Partitions

Using Formulas in a Calculation Script

You can place member formulas in a calculation script. When you place
formulas in a calculation script, they override any conflicting formulas
that are applied to members in the database outline.
In a calculation script, you can perform both of the following
operations:

• Calculate a member formula on the database outline

• Define a formula

To calculate a formula that is applied to a member in the database

outline, simply use the member name followed by a semicolon (;); for
example:

Variance; 
 

This command calculates the formula applied to the Variance member

in the database outline.

To override values that result from calculating an outline, manually

apply a formula that you define in a calculation script, using
Calculation Script Editor or by creating a .txt file. 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. This 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.

For more information about formulas, see Developing Formulas.

Basic Equations
You can use equations in a calculation script to assign value to a
member, as follows:

Member = mathematical expression; 
 

In this equation, Member is a member name from the database

outline, and mathematical expression is any valid mathematical
expression. Analytic Services evaluates the expression and assigns the
value to the specified member.

For example, the following formula causes Analytic Services to cycle

through the database, subtracting the values in COGS from the values
in Sales and placing the result in Margin:

Margin = Sales ­ COGS; 
 

To cycle through a database means that Analytic Services takes a

calculation pass through the database. For more information on
calculation passes, see Using Two-Pass Calculation.

The next formula 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; 
 

Conditional Equations
When you use an IF statement as part of a member formula in a
calculation script, you need to perform both of the following tasks:

• Associate the IF statement with a single member

• Enclose the IF statement in parentheses

A sample IF statement is illustrated in the following example:

Profit 
(IF (Sales > 100)
   Profit = (Sales ­ COGS) * 2;
ELSE
  Profit = (Sales ­ COGS) * 1.5;
ENDIF;) 
 

Analytic Services cycles through the database and performs the

following calculations:
 1. The IF statement checks to see if the value of Sales for the
current member combination is greater than 100.
2. If Sales is greater than 100, Analytic Services 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, Analytic Services
subtracts the value in COGS from the value in Sales,
multiplies the difference by 1.5, and places the result in
Profit.

The whole of the IF?...?ENDIF statement is enclosed in parentheses

and associated with the Profit member, Profit (IF(...)...).

Interdependent Formulas
When you use an interdependent formula in a calculation script, the
same rules apply as for the IF statement. You need to perform both of
the following tasks:

• Associate the formula with a single member

• Enclose the formula in parentheses

Consider the interdependent formula discussed earlier. If you place the

formula in a calculation script, you enclose the whole formula in
parentheses and associate it with the Opening Inventory member, as
follows:

"Opening Inventory" 
(IF(NOT @ISMBR (Jan))"Opening Inventory" =
    @PRIOR("Ending Inventory"));
    ENDIF;
"Ending Inventory" = "Opening Inventory" ­ Sales + 
Additions;) 
 

Using a Calculation Script to Control Intelligent Calculation

Assume that you have a formula on a sparse dimension member and
the formula contains either of the following:

• A relationship function (for example, @PRIOR or @NEXT)

 • A financial function (for example, @NPV or @INTEREST)

Analytic Services always recalculates the data block that contains the
formula, even?if the data block is marked as clean for the purposes of
Intelligent Calculation. For more information, see Calculating Data
Blocks. For more information about Intelligent Calculation, see
Optimizing with Intelligent Calculation.

Grouping Formulas and Calculations

You may achieve significant calculation performance improvements by
carefully grouping formulas and dimensions in a calculation script. For
a discussion of the appropriate use of parentheses and for examples,
see Calculating a Series of Member Formulas and Calculating a Series
of Dimensions.

When you run a calculation script, Analytic Services automatically

displays the calculation order of the dimensions for each pass through
the database so that you can tell how many times Analytic Services
has cycled through the database during the calculation. Analytic
Services writes these information messages in the application log. The
messages can also be viewed during your session in the following
ways:

• In the Messages Panel of Administration Services Console

• In the standard output (command-line window) of MaxL Shell
or ESSCMD
To display the application log, see Viewing the Analytic Server and
Application Logs.

Calculating a Series of Member Formulas

When you calculate formulas, avoid using parentheses unnecessarily.
The following formulas cause Analytic Services to cycle through the
database once, calculating both formulas in one pass:

Profit = (Sales ­ COGS) * 1.5;
Market = East + West; 
 
Similarly, the following configurations cause Analytic Services to cycle
through the database only once, calculating the formulas on the
members Qtr1, Qtr2, and Qtr3:

Qtr1;
Qtr2;
Qtr3; 
 

or

(Qtr1;
Qtr2;
Qtr3;) 
 

However, the inappropriately placed parentheses in the following

example causes Analytic Services to perform two calculation passes
through the database, once calculating the formulas on the members
Qtr1 and Qtr2 and once calculating the formula on Qtr3:

(Qtr1;
Qtr2;)
Qtr3; 
 

Calculating a Series of Dimensions

When you calculate a series of dimensions, you can optimize
performance by grouping the dimensions wherever possible.

For example, the following formula causes Analytic Services to cycle

through the?database only once:

CALC DIM(Year, Measures); 
 

However, the following syntax causes Analytic Services to cycle

through the database twice, because Analytic Services cycles through
once for each CALC DIM command:
CALC DIM(Year);
CALC DIM(Measures); 
 

Using Substitution Variables in Calculation Scripts

You can use substitution variables in calculation scripts. Substitution
variables are useful, for example, when you reference information or
lists of members that change frequently.

When you include a substitution variable in a calculation script,

Analytic Services replaces the substitution variable with the value you
specified for the substitution variable.

You create and specify values for substitution values in Essbase

Administration Services. For a comprehensive discussion of
substitution variables, see Using Substitution Variables.

You can create variables at the server, application, and database

levels. When you use a substitution variable in a calculation script, it
must be available to the calculation script. For example, if you create a
substitution variable at the database level, it is only available to
calculation scripts within the database. However, if you create a
variable at the server level, it is available to any calculation script on
the server.

Add the ampersand (&) character before a substitution variable in a

calculation script. Analytic Services treats any string that begins with a
leading ampersand as a substitution variable, replacing the variable
with its assigned value before parsing the calculation script.

For example, &CurQtr; becomes Qtr1; if you have given the

substitution variable &CurQtr the value Qtr1.

Consider an example in which you want to calculate Sample Basic data

for the current quarter. You can use the following calculation script to
perform this calculation:

FIX(&CurQtr)
CALC DIM(Measures, Product);
ENDFIX 
 
You then define the substitution variable CurQtr as the current
quarter; for example, Qtr3. Analytic Services replaces the variable
CurQtr with the value Qtr3 when it runs the calculation script.

Clearing Data
You can use the following commands to clear data. If you want to clear
an entire database, see "Clearing Data" in the Essbase XTD
Administration Services Online Help.

Calculation Command

Changes the values of the cells you specify to CLEARDATA

#MISSING. The data blocks are not removed.
You can use the FIX command with the
CLEARDATA command to clear a subset of a
database.

Removes the entire contents of a block, CLEARBLOCK

including all the dense dimension members.
Analytic Services removes the entire block,
unless CLEARBLOCK is inside a FIX command
on members within the block.

Removes blocks for Dynamic Calc and Store CLEARBLOCK

member combinations. For more information, DYNAMIC
see Dynamically Calculating Data Values.

The following examples are based on the Sample Basic database. If

the Scenario dimension is dense, the following example removes all
the data cells that do not contain input data values and intersect with
member Actual from the Scenario dimension.

FIX(Actual)
CLEARBLOCK NONINPUT;
ENDFIX 

If the Scenario dimension is sparse, the following formula removes

only the blocks whose Scenario dimension member is Actual. The other
blocks remain:
FIX(Actual)
CLEARBLOCK NONINPUT;
ENDFIX 
 

For example, the following formula clears all the Actual data values for
Colas:

CLEARDATA Actual?­>?Colas; 
 

Copying Data
You can use the DATACOPY calculation command to copy 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, in the Sample Basic database, 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, in the Sample Basic database, the following formula

copies Actual values to Budget values for the month of January only:

FIX (Jan)
DATACOPY Actual TO Budget;
ENDFIX 
 

For more information about the DATACOPY command, see the

Technical Reference. For more information about the FIX command,
see Using the FIX Command.

Calculating a Subset of a Database

To calculate a subset of a database, use either of the following
methods:
 • Create a formula using member set functions to calculate lists
of members.
• Use the FIX?...?ENDFIX commands to calculate a range of
values.

For information about using member lists, see Calculating Lists of

Members. For examples of use of the FIX command, see Using the FIX
Command.

Note: When you have Intelligent Calculation 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 Analytic Services
recalculates the database as efficiently as?possible using Intelligent
Calculation. For a comprehensive discussion of Intelligent
Calculation, see Optimizing with Intelligent Calculation.

Calculating Lists of Members

You can use a member set function to generate a list of members that
is based on?a member you specify. For example, you can use the
@IDESCENDANTS function to generate a list of all the descendants of
a specified member.

In the Sample Basic database, @IDESCENDANTS("Total Expenses"); 

generates the following list of members-Total Expenses, Marketing,
Payroll, and Misc.

When you use a member set function in a formula, Analytic Services

generates a list of members before calculating the formula.

For detailed information on these and other member set functions, see
the Technical Reference.

Using the FIX Command

The FIX ... ENDFIX commands are particularly useful to calculate a
carefully defined subset of the values in a database. For example, the
following calculation script calculates only the Budget values for only
the descendants of East (New York, Massachusetts, Florida,
Connecticut, and New Hampshire) in the Sample Basic database:
FIX(Budget,@DESCENDANTS(East))
CALC DIM(Year, Measures, Product);
ENDFIX 
 

The next example fixes on member combinations for the children of

East that have a user-defined attribute (UDA) of New Mkt. For
information on defining UDAs, see Creating and Changing Database
Outlines.

FIX(@CHILDREN(East) AND @UDA(Market,"New Mkt"))
Marketing = Marketing * 1.1;
ENDFIX 
 

The next example uses a wildcard match to fix on member names that
end in the characters -10. In Sample Basic, this example fixes on the
members 100-10, 200-10, 300-10, and 400-10.

FIX(@MATCH(Product, "???­10"))
Price = Price * 1.1;
ENDFIX 
 

When you use the FIX command only on a dense dimension, Analytic
Services retrieves the entire block that contains the required value or
values for the member or members that you specify. Thus, I/O is not
affected, and the calculation performance time is improved.

When you use the FIX command on a sparse dimension, Analytic

Services retrieves the block for the specified sparse dimension
member or members. Thus, I/O may be greatly reduced.

Analytic Services 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,
the following calculation script causes Analytic Services to cycle
through the database only once, calculating both the Actual and the
Budget values:

FIX(Actual,Budget)
CALC DIM(Year, Measures);
ENDFIX 
 

However, this calculation script causes Analytic Services to cycle

through the database twice, once calculating the Actual data values
and once calculating the data values for Budget:

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

For detailed information on using the FIX command, see the Technical
Reference.

Enabling Calculations on Potential Blocks

When you use a formula on a dense member in a dense dimension, if
the resultant values are from a dense dimension and the operand or
operands are from a sparse dimension, Analytic Services does not
automatically create the required blocks.

Consider an example from Sample Basic, in which 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 
 

Note that Sales and Expenses, the results of the equations, are dense
dimension members, and the operand, Actual, is in a sparse
dimension. Because Analytic Services executes dense member
formulas only on existing data blocks, the calculation script above 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, each with its
own advantages and disadvantages:

• Using DATACOPY to Copy Existing Blocks

• Using SET CREATENONMISSINGBLK to Calculate All Potential
Blocks

Using DATACOPY to Copy Existing Blocks

You can use the DATACOPY command to create a new block for each
existing block, and then perform calculations on the new blocks, as
shown in the following example:

DATACOPY Sales?­>?Actual TO Sales?­>?Budget;
DATACOPY Expenses?­>?Actual TO Expenses?­>?Budget;
FIX(Budget)
      (Sales = Sales?­>?Actual * 1.1;
       Expenses = Expenses?­>?Actual *  .95;)
ENDFIX 
 

Analytic Services creates blocks that contain the Budget values for
each corresponding Actual block that already exists. After the
DATACOPY commands are finished, the remaining part of the script
changes the values.

Using DATACOPY works well in the following circumstances:

• 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.
• None of the blocks that are copied contain only #MISSING
values. It is possible that blocks will be written that contain
only #MISSING values. Unneeded #MISSING blocks require
Analytic Services resource and processing time.

Caution: DATACOPY creates the new blocks with identical values in

ALL cells from the source blocks. If the formula only performs on a
portion of the block, these copied cells will remain at the end of
calculation, potentially resulting in unwanted values.

Using SET CREATENONMISSINGBLK to Calculate

All Potential Blocks
If you are concerned about unwanted values, instead of using the
DATACOPY approach described above, you can use the SET
CREATENONMISSINGBLK ON calculation command. The SET
CREATENONMISSINGBLK ON calculation command calculates all
potential blocks in memory and then stores only the calculated blocks
that contain data values.

The following example script demonstrates using the SET

CREATENONMISSINGBLK ON calculation command 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)
SET CREATENONMISSINGBLK ON
      (Sales = Sales?­>?Actual * 1.1;
       Expenses = Expenses?­>?Actual * .95;)
ENDFIX 
 

The SET CREATENONMISSINGBLK calculation command can be useful

when calculating values on dense or sparse dimensions. For additional
information about this command, see the Technical Reference.

Note: If the Create Blocks on Equations setting for sparse

dimensions is ON, the SET CREATENONMISSINGBLK ON temporarily
overrides the Create Blocks on Equations setting until a SET
CREATENONMISSINGBLK OFF command is encountered or the
calculation script is completed. For more information about the
Create Blocks on Equations setting, see Non-Constant Values
Assigned to Members in a Sparse Dimension or the SET
CREATEBLOCKONEQ calculation command in the Technical
Reference.

The advantage to using the SET CREATENONMISSINGBLK command is

that, when applied on dense members, only data cells that are
affected by the member formula are saved. The disadvantage is that
too many potential blocks may be materialized in memory, possibly
affecting calculation performance. When you use this command, limit
the number of potential blocks; for example, by using FIX to restrict
the scope of the blocks to be calculated.

For additional information about using the SET

CREATENONMISSINGBLK ON calculation command, see the Technical
Reference.

Writing Calculation Scripts for Partitions

A partitioned application can span multiple servers, processors, or
computers. For a comprehensive discussion of partitioning, see
Designing Partitioned Applications and Creating and Maintaining
Partitions.

You can achieve significant calculation performance improvements by

partitioning applications and running separate calculations on each
partition.

However, when you use partitioning, you need to perform both of the
following tasks:
 • Consider carefully the performance impact on the overall
database calculation. You might choose to use any of the
following methods to improve performance:
o Redesign the overall calculation to avoid referencing
remote values that are in a transparent partition in a
remote database.
o Dynamically calculate a value in a remote database. See
Dynamically Calculating Data in Partitions.
o Replicate a value in the database that contains the
applicable formula. For example, if you are replicating
quarterly data for the Eastern region, replicate only the
values for Qtr1, Qtr2, Qtr3, and Qtr4, and calculate the
parent Year values locally.
• Ensure that a referenced value is up-to-date when Analytic
Services retrieves it. Choose one of the options previously
discussed (redesign, dynamically calculate, or replicate) or
calculate the referenced database before calculating the
formula.

Controlling Calculation Order for Partitions

You need to calculate databases in a specific order to ensure that
Analytic Services calculates the required results. For example, consider
the following partitions in which you view information from the West,
Central, and East databases transparently from the Corporate
database.

Figure 201: Calculating Partitions

West, Central, and East contain only actual values. Corporate contains
actual and budgeted values. Although you can view the West, Central,
and East data in the Corporate database, the data exists only in the
West, Central, and East databases; it is not duplicated in the Corporate
database.

Therefore, when Analytic Services calculates Corporate, it needs to

take the latest values from West, Central, and East. To obtain the
required results, you need to calculate West, Central, and East before
you calculate Corporate.

Reviewing the Process

for Creating Calculation
Scripts
Use this process to create a calculation script:

1. Create a new calculation script or open an existing calculation

script.
See "Creating Scripts or Opening Scripts" in Essbase XTD
Administration Services Online Help.
2. Enter or edit the contents of the calculation scripts.
In the Essbase XTD Administration Services Online Help, see
"About Calculation Script Editor." This may include some or all of
the following tasks:
o Associating a script with an outline
o Searching an outline tree for members
o Inserting dimensions, members, and aliases in a script
from an outline tree
o Inserting functions and commands in a script from a
tree
o Checking script syntax
o Executing scripts
o Viewing color-coded script elements
o Searching for text in a script
o Changing fonts
3. Validate the calculation script.
 See Checking Syntax and "Checking Script Syntax" in the
Essbase XTD Administration Services Online Help.
4. Save the calculation script.
See Saving Calculation Scripts and "Saving Scripts" in the
Essbase XTD Administration Services Online Help.
5. Execute the calculation script.
See Executing Calculation Scripts, Checking the Results of
Calculations, and "Executing Calculation Scripts" in the Essbase
XTD Administration Services Online Help.
6. If necessary, perform other operations on the calculation
script.
In the Essbase XTD Administration Services Online Help, see the
following topics:
o "Locking and Unlocking Objects"
o "Copying Scripts"
o "Renaming Scripts"
o "Deleting Scripts"
o "Printing Scripts"

For more information on calculation scripts, see Understanding

Calculation Scripts.

Checking Syntax
Analytic Services includes a syntax checker that tells you about any
syntax errors in a calculation script. For example, Analytic Services
tells you if you have typed a function name incorrectly. The syntax
checker cannot tell you about semantic errors in a calculation script.
Semantic errors occur when a calculation script does not work as you
expect. To find semantic errors, always run the calculation, and check
the results to ensure they are as you expect.

Analytic Services displays the syntax checker results in the messages

panel in Essbase Administration Services Console. If Analytic Services
finds no syntax errors, that is indicated in the messages panel. One
error is displayed at a time.

If Analytic Services finds one or more syntax errors, it usually displays

the number of the line that includes the error and a brief description of
the error. For example, if you do not include a semicolon end-of-line
character at the end of a calculation script command, Analytic Services
displays a message similar to the following:

Error: line 1: invalid statement; expected semicolon 
 

When you reach the first or last error, Analytic Services displays the
following message:

No more errors 
 
To check the syntax of a calculation script in Calculation Script Editor,
see "Checking Script Syntax" in the Essbase XTD Administration
Services Online Help.

Saving Calculation Scripts

Calculation scripts created using Administration Services are given a
.csc extension by default. If you run a calculation script from
Administration Services or from Essbase XTD Spreadsheet Services, it
must have a .csc extension. However, a calculation script is a text file,
and 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. You can

access this string via the API on an Analytic Services client or an
Analytic Server. Thus, from dialog boxes, you can dynamically create a
calculation script that is based on user selections.

You can save a calculation script in the following locations:

• As a file on a client machine.

• As an object on an Analytic Server. If you want other users to
have access to the calculation script, save it on an Analytic
Server. You can associate the script with the following
objects:
o 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 Analytic
Server computer. ARBORPATH is the Analytic Services
 install directory, and appname is the application with
which you have associated the calculation script.
o 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 Analytic Server computer.
ARBORPATH is the Analytic Services install directory,
appname is the application containing the database,
and dbname is the database with which you have
associated the calculation script.
To save a calculation script using Calculation Script Editor, see
"Saving Scripts" in Essbase XTD Administration Services Online Help.

Executing Calculation Scripts

Before you can execute a calculation script in Administration Services,
you must save it as an object on the Analytic Server, on a client
computer, or on a network. See Saving Calculation Scripts.

When you use Administration Services to execute a calculation script,

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 has
completed. For more information, see "Executing Calculation Scripts"
in Essbase XTD Administration Services Online Help.

To execute a calculation script, use any of the following methods:

Tool Topic Location

Administration Executing Essbase XTD

Services Calculation Scripts Administration Services
Online Help

MaxL execute Technical Reference

calculation

ESSCMD RUNCALC Technical Reference

Essbase ESSBASE > Essbase XTD

Spreadsheet Add- CALCULATION Spreadsheet Add-in
in User's Guide
Essbase Calculating with a Essbase XTD
Spreadsheet Script Spreadsheet Services
Services Online Help

Checking the Results of Calculations

After you execute a calculation script, you can check the results of the
calculation in the Spreadsheet Add-in or other appropriate tool.

When you execute a calculation using Administration Services or

Spreadsheet Services, you can view the calculation messages in the
application log. When you use ESSCMD to execute a calculation script,
you can view the messages in the ESSCMD window. When you use
MaxL or ESSCMD to execute a calculation script, Analytic Services
displays the messages to the standard output (command-line window),
depending on the level of messages you have set to display in MaxL
Shell or ESSCMD.

To display the application log, see Viewing the Analytic Server and
Application Logs.

Analytic Services provides the following information:

• The calculation order of the dimensions for each pass through

the database
• The total calculation time

You can use these messages to understand how the calculation is

performed and to tune it for the next calculation. To display more
detailed information, you can use the SET MSG SUMMARY, SET MSG
DETAIL, and SET NOTICE commands in a calculation script. For more
information, see Specifying Global Settings for a Database Calculation.

Copying Calculation Scripts

You can copy calculation scripts to applications and databases on any
Analytic Server, according to your permissions. You can also copy
scripts across servers as part of application migration.

To copy a calculation script, use any of the following methods:

Tool Topic Location

Administration Copying Scripts Essbase XTD Administration

Services Services Online Help

MaxL create Technical Reference

calculation as

ESSCMD COPYOBJECT Technical Reference

Reviewing Examples of
Calculation Scripts
The examples in this chapter illustrate different types of calculation
scripts, which you may want to adapt for your own use.

This chapter includes the following examples:

• Calculating Variance
• Calculating Database Subsets
• Loading New Budget Values
• Calculating Product Share and Market Share Values
• Allocating Costs Across Products
• Allocating Values Within or Across Dimensions
• Goal Seeking Using the LOOP Command
• Forecasting Future Values

For examples that use the Intelligent Calculation commands SET

UPDATECALC and SET CLEARUPDATESTATUS in calculation scripts, see
Reviewing Examples That Use SET CLEARUPDATESTATUS and
Reviewing Examples and Solutions for Multiple-Pass Calculations.

Calculating Variance
The Sample Basic database includes a calculation of the percentage of
variance between Budget and Actual values.
Figure 202: Calculating Variance and Variance %

During a default calculation of the Sample Basic database, Analytic

Services aggregates the values on the Market and Product dimensions.
Percentage values do not aggregate correctly. Therefore, the Variance
% formula needs to be recalculated after the default calculation.

In the Sample Basic outline, Variance % is tagged as a Dynamic Calc,

two-pass member. Thus, Analytic Services 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 script to recalculate
Variance %. For a comprehensive discussion of Dynamic Calc
members, see Dynamically Calculating Data Values. See Using Two-
Pass Calculation for information about calculation of two-pass
members.

Assuming that Intelligent Calculation is turned on (the default), the

following calculation script performs a default calculation and then
recalculates the formula on Variance %:

CALC ALL;
SET UPDATECALC OFF;
SET CLEARUPDATESTATUS AFTER;
"Variance %"; 
 

Analytic Services performs the following actions:

1. Analytic Services uses the CALC ALL command to perform a

default calculation of the database.

Note: Alternatively, run a default calculation of the database

outline without using a calculation script.

2. The SET UPDATECALC OFF command turns off Intelligent

Calculation.
 3. The CLEARUPDATESTATUS AFTER command tells Analytic
Services to mark the calculated blocks calculated by the
variance formula of the calculation script as clean, even
though the variance calculation is a partial calculation of the
database (by default, data blocks are marked as clean only
after a full calculation of the database).
4. Analytic Services cycles through the database calculating the
formula for Variance %.

For information on calculating statistical variance, see the Technical

Reference.

For information on using a calculation script for two-pass calculations,

see Choosing Two-Pass Calculation Tag or Calculation Script. For a
comprehensive discussion on developing and using formulas to
calculate a database, see Developing Formulas.

Calculating Database
Subsets
In this example, based on the Sample Basic database, the Marketing
managers of the regions East, West, South, and Central need to
calculate their respective areas of the database.

Figure 203: Market Dimension from the Sample Basic Database

The marketing manager of the region East uses the following

calculation script to calculate the data values for East:. Notice how
@DESCENDENTS(East) is used to limit the calculations to the Eastern
region.

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

The script calculates the Year, Measures, and Product dimensions for
each child of East.

Analytic Services performs the following actions:

1. Analytic Services fixes on the Budget values of the

descendants of East.
2. The Year, Measures, and Product dimensions are calculated in
one pass of the database for all Budget values of the
descendants of East.
3. Analytic Services fixes on the Budget values for all members
on the other dimensions.
4. Analytic Services aggregates the descendants of East and
places the result in East.

Loading New Budget

Values
This example calculates the Budget values of the Sample Basic
database and then recalculates the Variance and Variance % members
of the database:

/* Calculate all Budget values */
FIX(Budget)
CALC DIM(Year, Product, Market, Measures);
ENDFIX

/* Recalculate the Variance and Variance % formulas, which
      require two passes */
Variance;
"Variance %"; 
 

Analytic Services performs the following actions:

1. Analytic Services fixes on the Budget values.

2. Analytic Services calculates all Budget values. The CALC DIM
command is used to calculate all the dimensions except for
the Scenario dimension, which contains Budget.
3. Analytic Services calculates the formula applied to Variance in
the database outline.
4. Analytic Services calculates the formula applied to Variance %
in the database outline.

Calculating Product
Share and Market
Share Values
This example, based on the Sample Basic database, calculates product
share and market share values for each market and each product.

The product and market share values are calculated as follows:

• Each member as a percentage of the total

• Each member as a percentage of its parent

Assume that you add four members to the Measures dimension-Market

Share, Product Share, Market %, and Product %.

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

Analytic Services performs the following actions:

1. Analytic Services fixes on the Sales values and consolidates

all the Sales values. The CALC DIM command is used to
calculate the Year, Market, and Product dimensions. The
Measures dimension contains the Sales member and therefore
is not consolidated. The Scenario dimension is label only and
therefore does not need to be consolidated.
2. Analytic Services cycles through the database and calculates
Market Share. It takes the Sales value for each product in
each market for each month. It calculates this Sales value as
a percentage of total Sales in all markets for each product
(Sales -> Market).
3. Analytic Services calculates Product Share. It takes the Sales
value for each product in each market for each month. It
calculates this Sales value as a percentage of total Sales of all
products in each market (Sales -> Product).
4. Analytic Services calculates Market %. It takes the Sales
value for each product in each market for each month. It
 calculates this Sales value as a percentage of the Sales value
of the parent of the current member on the Market
dimension. It uses the @PARENTVAL function to obtain the
Sales value of the parent on the Market dimension.
5. Analytic Services calculates Market %. It takes the Sales
value for each product in each market for each month. It
calculates this Sales value as a percentage of the Sales value
of the parent of the current member on the Product
dimension. It uses the @PARENTVAL function to obtain the
Sales value of the parent on the Product dimension.

Allocating Costs Across

Products
The following example is based on the Sample Basic database. It
allocates overhead costs to each product in each market for each
month.

The overhead costs are allocated based on each product's Sales value
as a percentage of the total Sales for all products.

Assume that you add two members to the Measures dimension-

OH_Costs for the allocated overhead costs and OH_TotalCost for the
total overhead costs.

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

Analytic Services performs these calculations:

1. Analytic Services creates a one-dimensional array called

ALLOCQ. The size of ALLOCQ is based on the number of
members in the Year dimension. Analytic Services uses
ALLOCQ to store the value of Sales as a percentage of total
Sales temporarily for each member combination.
2. The SET AGGMISSG OFF; command means that #MISSING
values are not aggregated to their parents. Data values
stored at parent levels are not overwritten. If this is your
system default, you can omit this line. For information on
setting the default for aggregating #MISSING values, see
Aggregating #MISSING Values.
o Analytic Services fixes on the Actual values.
o Analytic Services cycles through the member
combinations for Actual and calculates OH_Costs.
o It then takes the Sales value for each product in each
market for each month. It calculates this Sales value as
a percentage of total Sales for all products in each
market (Sales -> Product). It places the result in
ALLOCQ.
o It then takes the total overhead costs for all products
(OH_TotalCost -> Product) and multiplies it by the value
it has just placed in ALLOCQ. It places the result in
OH_Costs.
Notice that both of the equations are enclosed in
parentheses ( ) and associated with the OH_Costs
member, OH_Costs (equation1; equation2;).
3. Analytic Services calculates and consolidates the Measures
dimension.
Allocating Values
Within or Across
Dimensions
Using the @ALLOCATE and @MDALLOCATE functions, you can allocate
values to members in the same dimension or to members in multiple
dimensions.

Allocating Within a Dimension

The following example uses the @ALLOCATE function to allocate
budgeted total expenses across expense categories for two products.
The budgeted total expenses are allocated based on the actual values
for the prior year.

The following example is based on the Sample Basic database. Assume

that you have made the following changes to Sample Basic:

• Added a child, Lease, under Total Expenses in the Measures

dimension
• Added a child, PY Actual, to the Scenario dimension
• Removed the Dynamic Calc tag from the Total Expenses
member

Figure 204: Modified Measures and Scenario Dimensions from the

Sample Basic Database
 For this example, assume that data values of 1000 and 2000 are
loaded into Budget?-> Total Expenses for Colas and Root Beer,
respectively. These values need to be allocated to each expense
category, evenly spreading the values based on the non-missing
children of Total Expenses from PY Actual. The allocated values need to
be rounded to the nearest dollar.

This calculation script defines the allocation:

/* Allocate budgeted total expenses based on prior year */

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

This table shows the results:

. Budget PY Actual
Colas Marketing 334* 150

Payroll #MI #MI

Lease 333 200

Misc 333 100

Total Expenses 1000 450

Root Beer Marketing 500 300

Payroll 500 200

Lease 500 200

Misc 500 400

Total Expenses 2000 1100

* Rounding errors are added to this value. See Step 5 for more information.

Analytic Services cycles through the database, performing the

following calculations:

1. Analytic Services fixes on the children of Total Expenses.

Using a FIX statement with @ALLOCATE may improve
calculation performance.
2. For Budget -> Colas -> Marketing, Analytic Services divides 1
by the count of non-missing values for each expense category
in PY Actual -> Colas for each month. In this case, 1 is
divided by 3, because there are 3 non-missing expense values
for Budget -> Colas.
3. Analytic Services takes the value from step 2 (.333),
multiplies it by the value for Budget -> Colas -> Total
Expenses (1000), and then rounds to the nearest dollar
(333). This value is placed in Budget -> Colas -> Marketing.
4. Analytic Services repeats steps 2-3 for each expense category
for Budget -> Colas and then for Budget -> Root Beer.
5. As specified in the calculation script, the allocated values are
rounded to the nearest whole dollar. Analytic Services 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 the
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).

Allocating Across Multiple Dimensions

The following example uses the @MDALLOCATE function to allocate a
loaded value for budgeted total expenses across three dimensions. The
budgeted total expenses are allocated based on the actual values of
the prior year.

The following example is based on the Sample Basic database. Assume

that you have made the following modifications:

• Added a child, PY Actual, to the Scenario dimension

• Copied data from Actual into PY Actual
• Cleared data from Budget

For this example, a value of 750 (for Budget -> Total Expenses ->
Product -> East?-> Jan) needs to 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.

This calculation script defines the allocation:

/* 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 
 
This table shows the values for PY Actual:

Jan

PY Actual
Total
Marketing Payroll Misc
Expenses

100- New York 94 51 0 145

10
Massachusetts 23 31 1 55

Florida 27 31 0 58

Connecticut 40 31 0 71

New 15 31 1 47
Hampshire

100- New York 199 175 2 376

20
Massachusetts #MI #MI #MI #MI

Florida #MI #MI #MI #MI

Connecticut 26 23 0 49

New #MI #MI #MI #MI

Hampshire

100- New York #MI #MI #MI #MI

30
Massachusetts 26 23 0 49

Florida #MI #MI #MI #MI

Connecticut #MI #MI #MI #MI

New #MI #MI #MI #MI

Hampshire
100 New York #MI #MI #MI #MI

Massachusetts 12 22 1 35

Florida 12 22 1 35

Connecticut 94 51 0 145

New 23 31 1 55
Hampshire

East 237 220 3 460

Analytic Services cycles through the database, performing these

calculations:

1. Analytic Services fixes on East, the children of 100, and Total

Expenses. Using a FIX statement with @MDALLOCATE may
improve calculation performance.
2. Before performing the allocation, Analytic Services needs to
determine what share of 750 (the value to be allocated) each
expense category should receive, for each product-state
combination. To determine the share, Analytic Services uses
the shares of each expense category from PY Actual. Starting
with PY Actual -> 100-10 -> New York, Analytic Services
divides the value for the first expense category, Marketing, by
the value for PY Actual-> 100-10 -> East -> Total Expenses
to calculate the percentage share of that category. For
example, Analytic Services divides the value for PY Actual ->
100-10 -> New York -> Marketing (94) by the value for PY
Actual -> 100-10 -> East -> Total Expenses (460), which
yields a percentage share of approximately 20.4% for the
Marketing category.
3. Analytic Services repeats step?2 for each expense category,
for each product-state combination.
4. During the allocation, Analytic Services uses the percentage
shares calculated in step?2 to step?3 to determine what share
of 750 should be allocated to each child of Total Expenses
from Budget, for each product-state combination. For
example, for Marketing, Analytic Services uses the 20.4%
figure calculated in step?2, takes 20.4% of 750
 (approximately 153), and places the allocated value in Budget
-> 100-10 -> New York -> Marketing (see the next table).
5. Analytic Services repeats step 4 for each expense category
and for each product-state combination, using the percentage
shares from PY Actual calculated in step?2 to step?3.
6. Analytic Services consolidates the expense categories to yield
the values for Total Expenses.

This table shows the results of the allocation for Budget:

Jan Budget

Total
Marketing Payroll Misc
Expenses

100- New York 153.26 83.15 0 236.41

10
Massachusetts 37.50 50.54 1.63 89.67

Florida 44.02 50.54 0 94.56

Connecticut 65.22 50.54 0 115.76

New 24.46 50.54 1.63 76.63

Hampshire

100- New York #MI #MI #MI #MI

20
Massachusetts #MI #MI #MI #MI

Florida 42.39 37.50 0 79.89

Connecticut #MI #MI #MI #MI

New #MI #MI #MI #MI

Hampshire
100- New York #MI #MI #MI #MI
30
Massachusetts #MI #MI #MI #MI

Florida #MI #MI #MI #MI

Connecticut #MI #MI #MI #MI

New 19.57 35.87 1.63 57.07

Hampshire

100 New York 153.26 83.15 0 236.41

Massachusetts 37.50 50.54 1.63 89.67

Florida 86.41 88.04 0 174.46

Connecticut 65.22 50.54 0 115.76

New 44.02 86.41 3.26 133.70

Hampshire

East 386.41 358.70 4.89 750

Goal Seeking Using the

LOOP Command
The following example is based on the Sample Basic database.
However, the example assumes that no members are tagged as
Dynamic Calc and that the Profit per Ounce member (under Ratios in
the Scenario dimension) is not included in the calculation. For an
explanation of how you calculate values dynamically and how you
benefit from doing so, see Dynamic Calc members, see Dynamically
Calculating Data Values.

You want to know what sales value you have to reach in order to
obtain a certain profit on a specific product.
This example adjusts the Budget value of Sales to reach a goal of
15,000 Profit for Jan. The results are shown for product 100-10.

Figure 205: Measures Dimension from the Sample Basic Database

Assume that the data values before running the goal-seeking

calculation script are as follows:

Product, Market, Budget Jan

Profit 12,278.50
????????Margin 30,195.50
????????????????Sales 49,950.00
????????????????COGS 19,755.00
????????Total Expenses 17,917.00
????????????????Marketing 3,515.00
????????????????Payroll 14,402.00
????????????????Misc 0

Inventory Label Only member

Ratios Label Only member

????????Margin % 60.45
????????Profit % 24.58

This calculation script produces the goal-seeking results:

/* 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 and 
base it 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 
 

Analytic Services performs the following calculations:

1. It declares the required temporary variables using the VAR

command. Where appropriate, the initial values are set.
2. Analytic Services declares a one-dimensional array called
Rollback. The size of Rollback is based on the number of
members in the Measures dimension. Analytic Services uses
Rollback to store the Budget values.
3. Analytic Services fixes on the Jan -> Budget values for all
Product and Market members.
4. The LOOP command ensures that the commands between
LOOP and ENDLOOP are cycled through 35 times for each
member combination. However, if the Quit variable is set to 1,
 then the LOOP is broken and the calculation continues after
the ENDLOOP command.
5. Analytic Services cycles through the member combinations,
performing the following calculations:
a. Analytic Services places the Budget -> Sales value in
the Rollback temporary array variable.
b. It calculates the acceptable error. It multiplies the
Target value (15000) by the AcceptableErrorPercent
value (0.001) and places the result in the
AcceptableError variable.
c. It retains the current Sales value. It places the Sales
value for the current member combination in the
PriorVar temporary variable.
d. It retains the current Profit value. It places the Profit
value for the current member combination in the
PriorTar temporary variable.
e. It calculates a new Sales value. It multiplies the
PctNewVarChange value (0.1) by the current Sales
value, adds the current Sales value, and places the
result in Sales.
f. Analytic Services calculates and consolidates the
Measures dimension.
g. It subtracts the PriorTar value from the PriorVar value
and places the result in the DependencyCheck
temporary variable.
h. The IF command checks that DependencyCheck is not 0
(zero).
 If DependencyCheck is not 0, then Analytic
Services subtracts the Target value (15000) from
the current Profit and places the result in the
CurTarDiff temporary variable.
The IF command checks to see if the absolute value
(irrespective of the + or - sign) of CurTarDiff is
greater than the absolute value of the acceptable
error (AcceptableError). If it is, Analytic Services
calculates the Slope, NxtVar, and PctNewVarChange
temporary variables.
If it is not greater than AcceptableError, Analytic
Services breaks the LOOP command by setting the
value of Quit to 1. The calculation continues after the
ENDLOOP command.
  If DependencyCheck is 0, Analytic Services places
the value in the Rollback array into Budget.
Analytic Services breaks the LOOP command by
setting the value of Quit to 1. The calculation
continues after the ENDLOOP command.
6. Analytic Services calculates and consolidates the Measures
dimension.

The results are shown in this table:

Product, Market, Budget Jan

Profit 15,000.00
????????Margin 32,917.00
????????????????Sales 52,671.50
????????????????COGS 19,755.00
????????Total Expenses 17,917.00
????????????????Marketing 3,515.00
????????????????Payroll 14,402.00
????????????????Misc 0

Inventory Label Only member

Ratios Label Only member

????????Margin % 28.47839913
????????Profit % 62.49489762

Forecasting Future
Values
The following example uses the @TREND function to forecast sales
data for June through December, assuming that data currently exists
only up to May. Using the linear regression forecasting method, this
example produces a trend, or line, that starts with the known data
values from selected previous months and continues with forecasted
values based on the known values. In addition, this example
demonstrates how to check the results of the trend for "goodness of
fit" to the known data values.

The following example is based on the Sample Basic database. Assume

that the Measures dimension contains an additional child, ErrorLR. The
goodness-of-fit results are placed in this member. This calculation
script defines the forecasting:

Sales
(@TREND(@LIST(Jan,Mar,Apr),@LIST(1,3,4),,
  @RANGE(ErrorLR,@LIST(Jan,Mar,Apr)),
    @LIST(6,7,8,9,10,11,12),
      Jun:Dec,LR);); 
 

This table explains each parameter:

Parameter Desccription

@LIST(Jan,Mar,Apr) Represents the Ylist, or the members

that contain the known data values.
The @LIST function is needed to
group the three members as a
comma-delimited list and to keep the
list separate from other parameters.

@LIST(1,3,4) Represents the Xlist, or the

underlying variable values. Since Feb
and May are skipped, Analytic
Services needs to number the Ylist
values accordingly (1,3,4).

, The extra comma after the Xlist

parameter indicates that a parameter
has been skipped, in this case, the
weightList parameter. The default
weight of 1 is used for this example.

@RANGE(ErrorLR, Represents the errorList, or the

@LIST(Jan,Mar,Apr) 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 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 Jun
through Dec, so the values are
simply 6,7,8,9,10,11,12.

Jun:Dec Represents the YforecastList, or the

member list into which the forecast
values are placed. In this example,
values are forecast for Jun through
Dec based on the values for Jan, Mar,
and Apr.

LR Specifies the Linear Regression

method.

This table shows the results of the calculation script:

100 West Actual

.
Sales ErrorLR

Jan 2339 4.57

Feb 2298 #MI

Mar 2313 -13.71

Apr 2332 9.14

May 2351 #MI

Jun 2315.14 #MI

Jul 2311.29 #MI

Aug 2307.49 #MI

Sep 2303.57 #MI

Oct 2299.71 #MI

Nov 2295.86 #MI

Dec 2292 #MI

Analytic Services cycles through the database, performing the

following calculations:

1. Analytic Services finds the known data values on which to

base the trend (Sales for Jan, Mar, Apr), as specified for the
Ylist and Xlist parameters in the calculation script.
2. Analytic Services calculates the trend line using Linear
Regression and places the results in Sales for Jun through
Dec, as specified for the YforecastList parameter in the
calculation script.
3. Analytic Services calculates the goodness of fit of the trend
line to the data values for Jan, Mar, and Apr and places the
results in ErrorLR for those months. For example, the value in
ErrorLR for Jan (4.57) means that after Analytic Services
calculates the trend line, the difference between the Sales
value for Jan (2339) and the Jan value on the trend line is
4.57. The ErrorLR values for Feb and May are #MISSING
since these months were not part of Ylist.
Developing Custom-
Defined Calculation
Macros
This chapter explains how to develop custom-defined macros and how
to use them in calculation scripts and formulas. Custom-defined
macros are written with calculator functions and special macro
functions. Macros enable you to combine multiple calculation functions
into a single function.

For more details about the macro language syntax and rules, and
examples of the use of the macro language, see the Technical
Reference.

This chapter includes the following sections:

• Understanding Custom-Defined Macros

• Viewing Custom-Defined Macros
• Creating Custom-Defined Macros
• Using Custom-Defined Macros
• Updating Custom-Defined Macros
• Removing Custom-Defined Macros

Understanding Custom-
Defined Macros
Custom-defined macros use an internal macro language that enables
you to combine calculation functions and operate on multiple input
parameters.

When developing and testing custom-defined macros, make sure to

create and test new macros locally within a test application. You should
register custom-defined macros globally only after you have tested
them and are ready to use them as part of a production environment.
Analytic Services requires that you have a security level of database
designer or higher to create and manage custom-defined macros.

Viewing Custom-
Defined Macros
View a custom-defined macro to determine whether a macro has been
successfully created or whether a custom-defined macro is local or
global.

To view a custom-defined macro, use either of the following

methods:

Tool Topic Location

Administration Viewing Custom- Essbase XTD

Services Defined Macros Administration Services
Online Help

MaxL display macro Technical Reference

Creating Custom-
Defined Macros
When you create a custom-defined macro, Analytic Services records
the macro definition and stores it for future use. Create the macro
once, and then you can use it in formulas and calculation scripts until
the macro is updated or removed from the catalog of macros.

Use these sections to understand more about creating custom-defined

macros and to find instructions for creating them:

• Understanding Scope
• Naming Custom-Defined Macros
 • Creating Macros
• Refreshing the Catalog of Custom-Defined Macros

Understanding Scope
You can create custom-defined macros locally or globally. When you
create a local custom-defined macro, the macro is only available in the
application in which it was created. When you create a global custom-
defined macro, the macro is available to all applications on the server
where it was created.

When you create a global custom-defined macro, all Analytic Services

applications can use it. Be sure you test custom-defined macros in a
single application (and create them only in that application) before
making them global macros.

Caution: When testing macros, do not create the macros as global

(using a macro name without the AppName. prefix), because global
macros are difficult to update. For information about the methods
for updating custom-defined macros, see Updating Custom-Defined
Macros.

For rules about naming custom-defined macros, see Naming Custom-

Defined Macros.

Naming Custom-Defined Macros

Remember these requirements when you create macro names:

• The names of custom-defined macro must start with an "@"

symbol; for example, @MYMACRO. The rest of a macro name
can contain letters, numbers, and the following symbols: @,
#, $, and _. Macro names can not contain spaces.
• The names of custom-defined macros which are only called by
other macros should start with "@_" to distinguish them from
general use macros and functions.
• Macros must have unique names. Macro names must be
different from each other, from the names of custom-defined
functions, and from the names of existing calculation
functions. If an application contains a local macro that has the
same name as a global macro, the local macro takes
precedence and is used for calculation.
Creating Macros
To create a custom-defined macro, use either of the following
methods:

Tool Topic Location

Administration Creating Custom- Essbase XTD

Services Defined Macros Administration Services
Online Help

MaxL create macro Technical Reference

Be sure to add the application name plus a period (.) as a prefix before
the name of the local macro. In this example, Sample is the prefix for
the local macro name. This prefix assigns the macro to an application,
so the macro is only available within that application.

For example, use the following MaxL statement to create a local macro
named @COUNTRANGE used only in the Sample application:

create macro Sample.'@COUNTRANGE'(Any) AS 
'@COUNT(SKIPMISSING, @RANGE(@@S))'
spec '@COUNTRANGE(MemberRange)'
comment 'counts all non­missing values';  
 

For example, use the following MaxL statement to create a global

macro named @COUNTRANGE:

create macro'@COUNTRANGE'(Any) AS 
'@COUNT(SKIPMISSING, @RANGE(@@S))'
spec '@COUNTRANGE(MemberRange)'
comment 'counts all non­missing values';  
 

Refreshing the Catalog of Custom-Defined Macros

To refresh the catalog of custom-defined macros for all applications
on a server, restart the server.
 To refresh the catalog of custom-defined macros for a single
application, use the refresh custom definitions MaxL statement.

For example, use the following MaxL statement to refresh the catalog
of custom-defined macros for the Sample application:

refresh custom definition on application sample;  
 

Using Custom-Defined
Macros
After creating custom-defined macros, you can use them like native
calculation commands. Local macros-created using the AppName.
prefix on the macro name-are only available for use in calculation
scripts or formulas within the application in which they were created.
Global macros-created without the AppName. prefix-are available to all
calculation scripts and formulas on the server where they were
created.

For a comprehensive discussion of creating custom-defined macros,

see Creating Custom-Defined Macros.

To use a custom-defined macro follow these steps:

1. Create a new calculation script or formula, or open an existing
calculation script or formula.
o If the custom-defined macro was registered locally-
within a specific application-you must use a calculation
script or formula within that application.
o If the custom-defined macro was registered globally,
you can use any calculation script or formula on any
application on the server.
2. Add the custom-defined macro to a new or existing
calculation script or formula. To use the custom-defined
macro shown earlier in this chapter, type 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.
3. Save the calculation script or formula, and then run it as
usual.

For information about creating and running calculation scripts, see

Developing Calculation Scripts. For information about creating and
running formulas, see Developing Formulas.

Updating Custom-
Defined Macros
When you update a custom-defined macro, you must determine
whether the macro is registered locally or globally. Local custom-
defined macros are created using an AppName. prefix in the macro
name and can be used only within the application where they were
created. For a review of the methods used to determine whether a
custom-defined macro is local or global, see Viewing Custom-Defined
Macros. For a review of the methods used to update the catalog of
macros after you change a custom-defined macro, see Refreshing the
Catalog of Custom-Defined Macros.

To update a custom-defined macro, use either of the following

methods:

Tool Topic Location

Administration Editing Custom- Essbase XTD Administration

Services Defined Macros Services Online Help

MaxL create or Technical Reference

replace macro

For example, use the following MaxL statement to change the local
macro @COUNTRANGE which is used only in the Sample application:

create or replace macro Sample.'@COUNTRANGE'(Any)
as '@COUNT(SKIPMISSING, @RANGE(@@S))';  
 

For example, use the following MaxL statement to change the global
macro @COUNTRANGE:

create or replace macro '@COUNTRANGE'(Any) 
as '@COUNT(SKIPMISSING, @RANGE(@@S))';  
 

Copying Custom-
Defined Macros
You can copy custom-defined macros to any Analytic Server and
application to which you have appropriate access.

To copy a custom-defined macro, use either of the following

methods:

Tool Topic Location

Administration Copying Custom- Essbase XTD

Services Defined Macros Administration Services
Online Help

MaxL create macro Technical Reference

Removing Custom-
Defined Macros
When removing a custom-defined macro, you must first determine
whether the macro is registered locally or globally. The procedure for
removing global custom-defined macros is more complex than that for
removing local custom-defined macros and should only be performed
by a database administrator. For a review of methods used to
determine whether a custom-defined macro is local or global, see
Viewing Custom-Defined Macros.

Before removing custom-defined macros, verify that no calculation

scripts or formulas are using them. Global custom-defined macros can
be used in calculation scripts and formulas across a server, so verify
that no calculation scripts or formulas on the server are using a global
custom-defined macro before removing it.

For a review of methods used to update the catalog of macros after

you remove a custom-defined macro, see Refreshing the Catalog of
Custom-Defined Macros.

To remove a custom-defined macro, use either of the following

methods:

Tool Topic Location

Administration Deleting Custom- Essbase XTD

Services Defined Macros Administration Services
Online Help

MaxL drop macro Technical Reference

For example, use the following MaxL statement to remove the local
macro @COUNTRANGE which is used only in the Sample application:

drop macro Sample.'@COUNTRANGE';  
 

For example, use the following MaxL statement to remove the global
macro @COUNTRANGE:

drop macro '@COUNTRANGE';  
Developing Custom-
Defined Calculation
Functions
This chapter explains how to develop custom-defined functions and
use them in Analytic Services formulas and calculation scripts.
Custom-defined functions are written in the JavaTM programming
language and enable you to create calculation functions not otherwise
supported by the Analytic Services calculation scripting language.

Analytic Services does not provide tools for creating Java classes and
archives. This chapter assumes that you have a compatible version of
the Java Development Kit (JDK) and a text editor installed on the
computer you use to develop custom-defined functions. For
information on compatible versions of Java, see the Essbase XTD
Analytic Services Installation Guide.

For additional examples of custom-defined functions, see the Technical

Reference.

Use these sections to create and use custom-defined functions:

• Viewing Custom-Defined Functions

• Creating Custom-Defined Functions
• Using Registered Custom-Defined Functions
• Updating Custom-Defined Functions
• Removing Custom-Defined Functions
• Considering How Custom-Defined Functions Affect
Performance and Memory

Viewing Custom-
Defined Functions
You can view custom-defined functions to determine whether a
function has been registered successfully and whether it is registered
locally or globally. No custom-defined functions are displayed until they
have been created and registered. Analytic Services does not supply
sample custom-defined functions.

To view a custom-defined function, use either of the following

methods:

Tool Topic Location

Administration Viewing Custom- Essbase XTD

Services Defined Functions Administration Services
Online Help

MaxL display function Technical Reference

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.

Creating Custom-
Defined Functions
There are several steps required to create a custom-defined function:

1. Learn the requirements for custom-defined functions.

See the following sections for more information:
 o Understanding Java Requirements for Custom-Defined
Functions
o Understanding Method Requirements for Custom-
Defined Functions
o Understanding Security and Custom-Defined Functions
o Understanding Scope and Custom-Defined Functions
o Naming Custom-Defined Functions
2. Write a public Java class that contains at least one public,
static method to be used as a custom-defined function.
For instructions, see Creating and Compiling the Java Class.
3. Install the Java class created in step 2.
For instructions, see Installing Java Classes on Analytic Server.
4. Register the custom-defined function as a local or global
function.
For instructions, see Registering Custom-Defined Functions.

Understanding Java Requirements for Custom-Defined

Functions
The basis of a custom-defined function is a Java class and method
created by a database administrator or Java programmer to perform a
particular type of calculation. Creating and testing these Java classes
and methods is the first step toward creating a custom-defined
function.

You can create more than one method in a class for use as a custom-
defined function. In general, it is recommended that you create all the
methods you want to use as custom-defined functions in a single class.
However, if you want to add new custom-defined functions that are not
going to be used across all applications on the Analytic Server, create
them in a new class and add them to the Analytic Server in a separate
.jar file.

When creating multiple Java classes that contain methods for use as
custom-defined functions, verify that each class name is unique.
Duplicate class names cause methods in the duplicate class not to be
recognized, and you cannot register those methods as custom-defined
functions.
After creating the Java classes and methods for custom-defined
functions, test them using test programs in Java. When you are
satisfied with the output of the methods, install them on Analytic
Server and register them in a single test application. Do not register
functions globally for testing, because registering functions globally
makes it more difficult to update them if you find problems.

Understanding Method Requirements for Custom-Defined

Functions
Methods in custom-defined functions can have any combination of the
following supported data types as input parameters:

Table 27: Data Types Allowed As Input Parameters

Type Type

boolean byte

char java.lang.String

short, int, long com.hyperion.essbase.calculator.CalcBoolean

float, double arrays of any of these types

CalcBoolean is an Analytic Services-specific data type that can include

three values-TRUE, FALSE, and #MISSING. For more information about
the other listed data types, see the documentation for the Java
Development Kit.

The method return data type can be void or any of the preceding data
types. Returned data types are converted to Analytic Services-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.

Note: Double variables returned with infinite or Not-a-Number

values are not supported by Analytic Services. If these values are
returned from a Java program, they may not be recorded or
displayed correctly in Analytic Services. Double variables should be
checked for infinite or Not-a-Number values and set to finite values
before being returned to Analytic Services. For more information,
see the entry for the class, Double, in the documentation for the
Java Development Kit.

For additional examples of Java custom-defined functions, see the

MaxL statement create function in the Technical Reference.

Understanding Security and Custom-Defined Functions

Analytic Services requires that you have these security permissions:

• To create, delete, and manage local (application-wide)

custom-defined functions, you must have security permission
of application designer or higher.
• To create, delete, and manage global (server-wide) custom-
defined functions, you must have security permission of
supervisor.

Understanding Scope and Custom-Defined Functions

Custom-defined functions are registered as either local (application-
wide) or global (Analytic Server-wide) in scope. When you register a
local custom-defined function, it is available only in the application in
which it was registered. When you register a global custom-defined
function, it is available to all applications on the Analytic Server on
which it was registered.

When developing and testing custom-defined functions, make sure to

register and test new functions locally within a test application. You
should never register custom-defined functions globally until you have
thoroughly tested them and are ready to use them as part of a
production environment.

Naming Custom-Defined Functions

When you register a custom-defined function in Analytic Services, you
give the function a name. This name is used in calculation scripts and
formulas and is distinct from the Java class and method name used by
the function.

Remember these requirements when you create function names:

• Custom-defined function names must start with an @ symbol;

for example, @MYFUNCTION. The rest of a function name can
 contain letters, numbers, and the following symbols: @, #, $,
and _. Function names cannot contain spaces.
• The names of custom-defined functions which are called only
by custom-defined macros should start with "@_" to
distinguish them from general use functions and macros.
• 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 Analytic Services application contains a local function
that has the same name as a global function, the local
function is used for calculation.

For information about and instructions for registering custom-defined

functions, see Registering Custom-Defined Functions.

Creating and Compiling the Java Class

To create a Java class for a custom-defined function, use this
procedure:
1. Start a text editor and create a Java class. For example, open
a text editor and create this class:
2. public class CalcFunc {
3.   public static double sum (double[] data) {
4.     int i, n = data.length;
5.     double sum = 0.0d;
6.     for (i=0; i<n; i++) {
7.       double d = data [i];
8.       sum = sum + d;
9.     }
10.    return sum;
11.  }
12.}
13. Save the Java class as a .java file; for example,
CalcFunc.java.
14. Compile the Java class using the JDK javac tool. At the
operating system command prompt, move to the directory
containing the class you want to compile and use the javac
 tool. For example, to compile the CalcFunc.java class, type
this command:
15.>javac CalcFunc.java 
16. Resolve any compiling errors and repeat steps 2 and 3 until
the compiler creates a new .class file; for example,
CalcFunc.class.

Installing Java Classes on Analytic Server

When you install Java classes on Analytic Server, you must first
compile the classes into a Java Archive (.jar) file, and then copy the
.jar file to a specific location on the computer running Analytic Server.

Note: You must either stop and restart Analytic Services

applications or stop and restart Analytic Server when you install
new .jar files.

To create a .jar file from a .class file and install it on an Analytic

Server:
1. At the operating system command prompt, move to the
directory containing the class you want to add to a .jar file
and use the JDK jar tool. To add CalcFunc.class to a .jar 
file, type this command:
2. >jar cf CalcFunc.jar CalcFunc.class 
3. Copy the .jar file to one of the following locations on the
computer running Analytic Server:
o The ARBORPATH\java\udf\ directory. This location is
recommended for .jar files containing global custom-
defined functions. If this directory does not exist, create
the directory.
o The ARBORPATH\app\AppName\udf\ directory where
AppName is the name of the application where the local
custom-defined function will be used. If this directory
does not exist, create the directory. Use this location if
you want the code in the .jar file to only be used with
a specific application.
If the .jar file is placed in another location, you must
modify the CLASSPATH variable to include the full path and
file name for the .jar file.
 4. If the functions will only be used by specific applications,
restart those applications in Analytic Services. Otherwise,
restart Analytic Server.

Registering Custom-Defined Functions

After you have compiled the Java classes for custom-defined functions
into .jar files and installed the .jar files on Analytic Server, you must
register the custom-defined functions before you can use them in
calculation scripts and formulas. For rules about naming custom-
defined functions, see Naming Custom-Defined Functions.

When you register a global custom-defined function, all Analytic

Services applications on the Analytic Server can use it. Be sure you
test custom-defined functions in a single application (and register
them only in that application) before making them global functions.

Use the same process for updating the catalog of functions as you do
for updating the catalog of macros. After you register a custom-
defined function, see Refreshing the Catalog of Custom-Defined
Macros.

Caution: Do not register global functions for testing, because

registering them globally makes it more difficult to change them if
you find problems.

To register a custom-defined function, use either of the following

methods:

Tool Topic Location

Administration Creating Custom- Essbase XTD

Services Defined Functions Administration Services
Online Help

MaxL create function Technical Reference

To register a custom-defined function with local scope, include the

application name as a prefix. For example, use the following MaxL
statement to register the local custom-defined function in the class
CalcFunc from Creating and Compiling the Java Class to be used 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, use the following MaxL
statement to register as a global function the custom-defined function
in the class CalcFunc from Creating and Compiling the Java Class:

create function '@JSUM' 
as 'CalcFunc.sum';
spec '@JSUM(memberRange)'
comment 'adds list of input members';  
 

The AppName. prefix is not included in the name of the function. The
lack of a prefix makes a function global.

Note: Specifying input parameters for the Java method is optional.

If you do not specify input parameters, Analytic Services reads
them from the method definition in the Java code. However, if you
are registering two or more 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.

Using Registered
Custom-Defined
Functions
After registering custom-defined functions, you can use them like
native Analytic Services calculation commands. Functions you
registered locally-using the AppName. prefix on the function name-are
only available for use in calculation scripts or formulas within the
application in which they were registered. If you registered the
custom-defined functions globally, then the functions are available to
all calculation scripts and formulas on the Analytic Server where the
functions are registered.

For information and instructions for registering custom-defined

functions, see Registering Custom-Defined Functions.

To use a registered custom-defined function:

1. Create a new calculation script or formula, or open an existing
calculation script or formula.
o If the custom-defined function was registered locally-
within a specific application-then you must use a
calculation script or formula within that application.
o If the custom-defined function was registered globally,
then you can use any calculation script or formula on
Analytic Server.
2. Add the custom-defined function to a new or existing
calculation script or formula. To use the custom-defined
function shown earlier in this chapter, use this calculation
script:
"New York" = @JSUM(@LIST(2.3, 4.5, 6.6, 1000.34));

Use this calculation script with the Sample Basic sample

database, or replace "New York" with the name of a member in a
test database.
3. Save the calculation script or formula, and then run it as
usual.

For a comprehensive discussion of creating and running calculation

scripts, see Developing Calculation Scripts. For a comprehensive
discussion of creating and running formulas, see Developing Formulas.

Updating Custom-
Defined Functions
When you update a custom-defined function, there are two major
issues to consider:
 • Is the function registered locally or globally?
• Have the class name, method name, or input parameters
changed in the Java code for the custom-defined function?

The answers to these questions determine the procedure for updating

the custom-defined function.

For a review of methods to determine whether a custom-defined

function is local or global, see Viewing Custom-Defined Functions.

To update a custom-defined function, in most cases, you must replace

the .jar file that contains the code for the function, and then re-
register the function. However, if the signature of the custom-defined
function-the Java class name, method name and input parameters-
have not changed and the function has only one set of input
parameters (it is not an overloaded method), you can simply replace
the .jar file that contains the function. In either situation, you must
stop and restart the Analytic Services application or Analytic Server
where the custom-defined function is registered, depending on
whether it is a local or global function.

Note: The following procedure is effective only if the signature of

the custom-defined function-the Java class name, method name,
and input parameters for the custom-defined function-has not
changed.

To update a custom-defined function whose signature has not

changed:
1. Make the changes to the Java class for the custom-defined
function and use Java test programs to test its output.
2. Compile the Java classes and encapsulate them in a .jar file,
using the same name as the previous .jar file. Make sure to
include any other classes and methods for custom-defined
functions that were included in the previous .jar file.
3. Perform one of the following steps:
o If the function is registered locally, shut down the
application in which it was registered.
o If the function is registered globally, shut down all
running applications.
4. Copy the new .jar file to Analytic Server over the existing
.jar file with the same name.
5. Restart the applications you shut down in step 3.
Updating Local Custom-Defined Functions
Local custom-defined functions are registered with an AppName. prefix
on the function name and can be used only within the application
where they were registered. To update a local custom-defined function,
you must stop and restart the Analytic Services application where the
function is registered.

To update a local custom-defined function:

1. Make the changes to the Java class for the custom-defined
function and use Java test programs to test its output.
2. Compile the Java classes and encapsulate them in a .jar file,
using the same name as the previous .jar file. Make sure to
include any other classes and methods for custom-defined
functions that were included in the previous .jar file.
3. Perform one of the following steps:
o If the .jar file contains local custom-defined functions
only, shut down any Analytic Services applications that
use these functions.
o If the .jar file contains any global custom-defined
functions, shut down all Analytic Services applications.
o If you are unsure as to which Analytic Services
applications use which functions in the .jar file you are
replacing, shut down all Analytic Services applications.
4. Copy the new .jar file to Analytic Server over the existing
.jar file with the same name.
5. Use MaxL or Essbase Administration Services to replace the
custom-defined function.
o In MaxL, use the create or replace function
statement to replace the custom-defined function; for
example, type this statement:
o create or replace function sample.'@JSUM' 
o as 'CalcFunc.sum'; 
o In Essbase Administration Services, see "Editing
Custom-Defined Functions" in Essbase XTD
Administration Services Online Help.

Updating Global Custom-Defined Functions

Global custom-defined functions are registered without an AppName.
prefix on the function name and are available in any application
running on the Analytic Server where they are registered. To update a
global custom-defined function, you must stop and restart all
applications on Analytic Server.

Global custom-defined functions can be used in calculation scripts and

formulas across Analytic Server, so you should verify that no
calculation scripts or formulas are using a global custom-defined
function before updating it.

Caution: Only a database administrator should update global

custom-defined functions.

To update a global custom-defined function:

1. Make the changes to the Java class for the custom-defined
function and use Java test programs to test its output.
2. Compile the Java classes and encapsulate them in a .jar file,
using the same name as the previous .jar file. Make sure to
include any other classes and methods for custom-defined
functions that were included in the previous .jar file.
3. Shut down all running Analytic Services applications.
4. Copy the new .jar file to Analytic Server over the existing
.jar file with the same name.
5. Use MaxL or Essbase Administration Services to replace the
custom-defined function.
o In MaxL, use the create or replace function
statement to replace the custom-defined function; for
example, type this statement:
o create or replace function '@JSUM' 
as 'CalcFunc.sum';
o In Essbase Administration Services, see "Editing
Custom-Defined Functions" in Essbase XTD
Administration Services Online Help.

Removing Custom-
Defined Functions
When removing a custom-defined function, you must first determine
whether the function is registered locally or globally to identify the
security permissions required:

• To remove a custom-defined function with global scope, you

must have supervisor permission.
• To remove a custom-defined function with local scope, you
must have application designer 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
Analytic Server, so you must verify that no calculation scripts or
formulas on Analytic Server are using a global custom-defined function
before removing it.

For a review of methods to determine whether a custom-defined

function is local or global, see Viewing Custom-Defined Functions.

Removing Local Custom-Defined Functions

Local custom-defined functions are registered with an AppName. prefix
on the function name and can only be used within the application
where they are registered.

When you remove a local custom-defined function, be sure to stop and

restart the Analytic Services application where the function is
registered to update the catalog.

To remove a custom-defined function, use either of the following

methods:

Tool Topic Location

Administration Deleting Custom- Essbase XTD

Services Defined Functions Administration Services
Online Help

MaxL drop function Technical Reference

For example, use the following MaxL statement to remove the @JSUM
function from the Sample application:

drop function Sample.'@JSUM';  
 

Removing Global Custom-Defined Functions

Global custom-defined functions are registered without an AppName.
prefix on the function name and are available in any application
running on Analytic Server where they are registered.

Be sure to stop and restart all running Analytic Services applications

when you remove a global custom-defined function.

Global custom-defined functions can be used in calculation scripts and

formulas across Analytic Server, so you should verify that no
calculation scripts or formulas are using a global custom-defined
function before removing it.

Caution: Only a database administrator with supervisor permission

can remove global custom-defined functions. Removal of global
custom-defined functions should only be performed when no users
are accessing Analytic Services databases and no calculation
routines are being performed.

To remove a global custom-defined function, use either of the

following methods:

Tool Topic Location

Administration Deleting Custom- Essbase XTD

Services Defined Functions Administration Services
Online Help

MaxL drop function Technical Reference

For example, use the following MaxL statement to remove the global
@JSUM function:

drop function '@JSUM';  
 

Copying Custom-
Defined Functions
You can copy custom-defined functions to any Analytic Server and
application to which you have appropriate access.

To copy a custom-defined macro, use either of the following methods:

Tool Topic Location

Administration Copying Custom- Essbase XTD

Services Defined Functions Administration Services
Online Help

MaxL create function Technical Reference

Considering How
Custom-Defined
Functions Affect
Performance and
Memory
The ability to create and run custom-defined functions is provided as
an extension to the Analytic Services calculator framework. When you
use custom-defined functions, consider how their use affects memory
resources and calculator performance.
Performance Considerations
Because custom-defined functions are implemented as an extension of
the Analytic Services calculator framework, you can expect custom-
defined functions to operate less efficiently than functions that are
native to the Analytic Services calculator framework. In tests using a
simple addition function running in the Java Runtime Environment 1.3
on the Windows NT 4.0 platform, the Java function ran 1.8 times
(about 80%) slower than a similar addition function performed by
native Analytic Services calculation commands.

To optimize performance, limit use of custom-defined functions to

calculations that you cannot perform with native Analytic Services
calculation commands, particularly in applications where calculation
speed is a critical consideration.

Memory Considerations
Use of the Java Virtual Machine (JVM) and Java API for XML Parsing
has an initial effect on the memory required to run Analytic Services.
The memory required to run these additional components is
documented in the memory requirements for Analytic Services. For
more information about memory requirements, see the Essbase XTD
Analytic Services Installation Guide.

Beyond these start-up memory requirements, the Java programs you

develop for custom-defined functions sometimes require additional
memory. When started, the JVM for Win32 operating systems
immediately allocates 2 MB of memory for programs. This allocation is
increased according to the requirements of the programs that are then
run by the JVM. The default upper limit of memory allocation for the
JVM on Win32 operating systems is 64 MB. If the execution of a Java
program exceeds the default upper limit of memory allocation for the
JVM, the JVM generates an error. For more information about JVM
memory management and memory allocation details for other
operating systems, see the Java Development Kit documentation.

Considering the default memory requirements of the JVM and the

limitations of the hardware on which you run servers, carefully monitor
your use of memory. In particular, developers of custom-defined
functions should be careful not to exceed memory limits of the JVM
when creating large objects within custom-defined functions.
Understanding Report
Script Basics
An Analytic Services report enables you retrieve formatted summaries
from an Analytic Services database. This chapter provides fundamental
information about working with report scripts created by Report Writer.
This chapter contains the following sections:

• Creating a Simple Report Script

• Understanding How Report Writer Works
• Planning Reports
• Considering Security and Multiple-User Issues
• Reviewing the Process for Creating Report Scripts
• Creating Report Scripts
• Saving Report Scripts
• Executing Report Scripts
• Developing Free-Form Reports

For a comprehensive discussion of creating complex report scripts, see

Developing Report Scripts.

Creating a Simple
Report Script
When you combine report commands that include page, row, and
column dimension declarations with selected members, you have all
the elements of a simple report script.

The following step-by-step example of a report script specifies these

elements, dimensions, and member selection commands. It includes
comments, which document the behavior of the script, and the !
output command. This example is based on the Sample Basic
database, which is supplied with the Analytic Server installation.

1. Create a report.
For more information, see "Creating Scripts" in the Essbase XTD
Administration Services Online Help.
2. Type the following information in the report, with the
exception of the commented (//) lines, which are for your
reference:
3. // This is a simple report script example 
4. // Define the dimensions to list on the current 
page, as below 
5. <PAGE (Market, Measures) 
6.
7. // Define the dimensions to list across the page, as 
below 
8. <COLUMN (Year, Scenario)
9.
10.// Define the dimensions to list down the page, as 
below 
11.<ROW (Product)
12.
13.// Select the members to include in the report 
14.Sales 
15.<ICHILDREN Market 
16.Qtr1 Qtr2 
17.Actual Budget Variance 
18.<ICHILDREN Product
19.
20.// Finish with a bang 
21.    ! 
22.Save the report script.
For more information, see "Saving Scripts" in the Essbase XTD
Administration Services Online Help.
23.Execute the report script.
For information, see "Executing Report Scripts" in the Essbase
XTD Administration Services Online Help.
When you execute this report against the Sample Basic database, the
script produces the following report:

                                      East Sales 

                             Qtr1 
Qtr2 
                  Actual   Budget  Variance   Actual  Budget 
Variance 
                ======== ======== ======== ======== 
======== ======== 
100                9,211    6,500    2,711   10,069    6,900 
3,169 
200                6,542    3,700    2,842    6,697    3,700 
2,997 
300                6,483    4,500    1,983    6,956    5,200 
1,756 
400                4,725    2,800    1,925    4,956    3,200 
1,756 
  Product         26,961   17,500    9,461   28,678   19,000 
9,678 

                                      West Sales 

                             Qtr1 
Qtr2 
                  Actual   Budget  Variance   Actual  Budget 
Variance 
                ======== ======== ======== ======== 
======== ======== 
100                7,660    5,900    1,760    7,942    6,500 
1,442 
200                8,278    6,100    2,178    8,524    6,200 
2,324 
300                8,599    6,800    1,799    9,583    7,600 
1,983 
400                8,403    5,200    3,203    8,888 
6,300    2,588 
  Product         32,940   24,000    8,940   34,937   26,600 
8,337 

                                     South Sales 

                             Qtr1 
Qtr2 
                  Actual   Budget  Variance   Actual  Budget 
Variance 
                ======== ======== ======== ======== 
======== ======== 
100                5,940    4,100    1,840    6,294    4,900 
1,394 
200                5,354    3,400    1,954    5,535    4,000 
1,535 
300                4,639    4,000      639    4,570    3,800 
770 
400             #Missing #Missing #Missing #Missing 
#Missing #Missing 
  Product         15,933   11,500    4,433   16,399   12,700 
3,699 

                                    Central Sales

                             Qtr1 
Qtr2
                  Actual   Budget  Variance   Actual  Budget 
Variance 
                ======== ======== ======== ======== 
======== ======== 
100                9,246    6,500    2,746    9,974    7,300 
2,674 
200                7,269    6,800      469    7,440    7,000 
440 
300               10,405    6,200    4,205   10,784    6,800 
3,984 
400               10,664    5,200    5,464   11,201    5,800 
5,401 
  Product         37,584   24,700   12,884   39,399   26,900 
12,499 

                                     Market Sales 

                             Qtr1 
Qtr2 
                  Actual   Budget  Variance   Actual  Budget 
Variance 
                ======== ======== ======== ======== 
======== ======== 
100               32,057   23,000    9,057   34,279   25,600 
8,679 
200               27,443   20,000    7,443   28,196   20,900 
7,296 
300               30,126   21,500    8,626   31,893   23,400 
8,493 
400               23,792   13,200   10,592   25,045   15,300 
9,745 
  Product        113,418   77,700   35,718  119,413   85,200 
34,21 
 

Understanding How
Report Writer Works
The Report Writer consists of three main components:
 • Report Script Editor is a text editor that you use to write the
report script. In Report Script Editor, you use report
commands to define formatted reports, export data subsets
from a database, and produce free-form reports. You can then
execute the script to generate a report. Report Script Editor
features a text editing window, a customized right-click menu,
a toolbar, and a message panel. Saved report scripts have the
file extension .rep.
• Report Extractor retrieves the data information from the
Analytic Services database when you run a report script.
• Report Viewer displays the complete report. Saved reports
have the file extension .txt.

Figure 206: Report Writer Components

Report Extractor
The Report Extractor processes the report script and retrieves data in
the following order:

1. Composes the member list, based on all possible member

combinations. For example, the following command retrieves
member East and all of its descendants:
 2. <IDESCENDANTS East 
3. Applies member restrictions. For example, the following
command refines the member selection:
4. <LINK 
5. Orders the member output. For example, the following
command determines the order in which members are sorted:
6. <SORT 
7. Extracts data from the following areas:
o Local regions
o Partitioned regions
o Dynamically calculated data
8. Restricts data. For example, the following command
suppresses the display of all rows that contain only missing
values:
9. {SUPMISSINGROWS} 
10.Sorts data. For example, the following command returns rows
with the highest values of a specified data column:
11.<TOP 
12.Formats output. For example, the following command skips
one or more lines in the final output report:
{SKIP} 

The order in which the Report Extractor retrieves data is important

when using 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, the 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 207: Elements of a Typical Report

A typical report is composed of the following parts:

• 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 more than one dimension,
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 more than one level
within a dimension or from more than one dimension. The
rows are indented below the dimension name.
<ROW (Product)
• Titles contain user-defined text, date and time stamp, the
user ID 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, whereas
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"
 •        C "The Electronics Club"
•       65 "*PAGESTRING"
• TEXT  65 "*DATE"
• SKIP 
• ENDHEADING }
• 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.

Parts of a Report Script

A report script consists of a series of Report Writer commands,
terminated by the bang (!) report output command.

You can enter one or more report scripts in a report script file. A report
script file is an ASCII text file that you create with Report Script Editor
or any text editor.

To build a report script, enter or select commands that define the

layout, member selection, and format in Report Script Editor. The
different elements of a script are color-coded to aid in readability.

The commands in Report Writer perform two functions, data extraction

and formatting:

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

See the Technical Reference for detailed information about the various
report commands that you can use.

Planning Reports
Report design is an important part of presenting information.
Designing a report is easy if you include the proper elements and
arrange information in an attractive, easy-to-read layout.

To plan a report, perform the following tasks:

1. Consider the reporting needs and the time required to
generate the report.
2. Make a rough sketch of the report. Be sure to include the
following items:
o Report layout
o Number of columns
o Members to include
o Titles, if applicable
o Format of the data values
3. Review the sketch; if you need to add additional data or
formatting to the report, it is often apparent at this stage.
4. Determine ways to optimize the run time of the report.
See 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.
To avoid ambiguity, give the rows names that describe their
content.
Considering Security
and Multiple-User
Issues
You must use Essbase Administration Services in order to use Report
Script Editor to create or modify a report script. You can also use any
text editor to create script files. If you use Report Script Editor, it lets
you create and modify report scripts stored on your desktop machine,
as well as the Analytic Server. To modify report scripts stored on the
server, you must have Application Designer or Database Designer
access.

Analytic Services supports concurrent, multiple-user database access.

As in most multiple-user environments, Analytic Services protects
critical data with a security system. Users can read or update data only
if they have the correct permissions.

When you execute a report script, the Analytic Services security

system verifies that you have Read or higher access level to all data
members specified in the report. In a filtering process identical to the
one for retrieving members into a spreadsheet, Analytic Services filters
any member from the output for which you have insufficient
permissions.

To users who are only reporting data, locks placed by other users are
transparent. Even if a user has locked and is updating part of the data
required by the report, the lock does not interfere with the report in
any way. The data in the report reflects the data in the database at the
time you run the report. Running the same report later reflects any
changes made after the last report ran.

See Managing Security for Users and Applications for a comprehensive

discussion of the Analytic Services security system.
Reviewing the Process
for Creating Report
Scripts
This section describes the process for creating a report script.

1. Create the report script. See Creating Report Scripts.

2. Check the report script syntax. See "Checking Script Syntax"
in the Essbase XTD Administration Services Online Help.
3. Save the report script. See Saving Report Scripts.
4. Run the report script. See Executing Report Scripts.
5. If desired, save the report. See "Saving Reports" in the
Essbase XTD Administration Services Online Help.

Creating Report Scripts

You can report on the data in a database using any of the following
methods:

• Report Script Editor. Use Report Script Editor to create large-

scale reports consisting of 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
Analytic Services database, and produce free-form reports. To
create a report script using Report Script Editor, see "Creating
Scripts" in the Essbase XTD Administration Services Online
Help.
• A text editor.
• Through a spreadsheet. You can use report commands in a
spreadsheet in free-form mode or in template retrieval mode.
For information on reporting through the spreadsheet
interface, see Essbase XTD Spreadsheet Add-in User's Guide.
• Analytic Services APIs. See Generating Reports Using the C,
Visual Basic, and Grid APIs for more information about using
 report APIs or see the API Reference for syntax and technical
descriptions.
• Third-party reporting tools.

For more information about creating and editing report scripts in

Essbase Administration Services, see "About Report Script Editor" in
Essbase XTD Administration Services Online Help.

Saving Report Scripts

You can save a report script in the following locations:

• As a file on a client machine or network.

• As an object on Analytic Server. If you want other users to
have access to the report script, save it on Analytic Server.
You can associate the script object with the following objects:
o An application and all the databases within the
application, which lets you run the script against any
database in the application.
o 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 Essbase Administration Services, the script must have a
.rep extension.

To save a report script using Report Script Editor, see "Saving Report
Scripts" in Essbase XTD Administration Services Online Help.

Executing Report
Scripts
When you execute a report script using Essbase Administration
Services, you can send the results to the Report Viewer window, to a
printer, and/or to a file. From the Report Viewer window, you can print,
save, and copy the report.
Using Essbase Administration Services, you can execute a report in the
background so that you can continue working as the report processes.
You can then check the status of the background process to see when
the report has completed.

For more information, see "Executing Report Scripts" in Essbase XTD

Administration Services Online Help.

Copying Report Scripts

You can copy report scripts to applications and databases on any
Analytic Server, according to your permissions. You can also copy
scripts across servers as part of application migration.

To copy a report script, use any of the following methods:

Tool Topic Location

Administration Copying Essbase XTD Administration

Services Scripts Services Online Help

MaxL alter object Technical Reference

ESSCMD COPYOBJECT Technical Reference

Developing Free-Form
Reports
Free-form reports are often easier to create than structured reports.
The free-form reporting style is ideal for ad hoc reporting in the Report
Script Editor window.

A free-form report does not include PAGE, COLUMN, or ROW

commands and instead gathers this information from a series of
internal rules that are applied to the report script by the Report
Extractor when you run the report.
The following example script and report illustrate free-form reporting:

Sales Colas
Jan Feb Mar 
Actual Budget
Illinois
Ohio
Wisconsin
Missouri
Iowa
Colorado
{UCHARACTERS}
Central
     ! 
 

This example produces the following report:

                               Sales 100

                 Jan               Feb 
Mar 
           Actual   Budget   Actual  Budget   Actual 
Budget 
          =======  =======   ======  ======   ====== 
====== 
Illinois      829      700      898     700      932 
700 
Ohio          430      300      397     300      380 
300 
Wisconsin     490      300      518     400      535 
400 
Missouri      472      300      470     300      462 
300 
Iowa          161        0      162       0      162 
0 
Colorado      643      500      665     500      640 
500 
========      ===      ===      ===     ===      === 
=== 
 Central    3,025    2,100    3,110   2,200    3,111 
2,200 
 

You can use formatting commands to add specific formats to a free-

form report. The rest of the report is automatically produced in a
format similar to that of any other report. When PAGE, COLUMN, and
ROW commands are omitted, Analytic Services 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 any
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
{UCHARACTERS}
West
    ! 
 

The Report Extractor applies free-form formatting rules to this report

as follows:

1. Because California, Oregon, Washington, Utah, Nevada, and

West are listed last, the Report Extractor treats them as if
ROW (Market) had been specified (according to rule 1).
2. Sales is a single-member selection from dimension Measures.
The Report Extractor treats this member as if PAGE
(Measures) had been specified (according to rule 2).
3. After searching the remaining members, the Report Extractor
finds members of dimensions Year and Scenario, which it
treats as COLUMN (Year, Scenario), according to rule 3.
4. The Report Extractor searches the database outline and finds
that dimension Product is not specified in the report
specification. Since Product is a single-member selection, the
Report Extractor treats this member as if PAGE (Product) had
been specified (according to rule 4).
 5. Finally, the Report Extractor finds that Apr May Jun is from
the same dimension as Jan Feb Mar and is displayed on a
subsequent line of the script. The Report Extractor discards
the first specification (Jan Feb Mar) and uses the second (Apr
May Jun).

As a result, the report example produces the following report:

                              Product Sales

                     Actual                    Budget
               Apr     May     Jun      Apr      May 
Jun
            =======  ======  ======   ======  ====== 
======
California  3,814    4,031    4,319    3,000    3,400 
3,700
Oregon      1,736    1,688    1,675    1,100    1,000 
1,100
Washington  1,868    1,908    1,924    1,500    1,600 
1,700
Utah        1,449    1,416    1,445      900      800 
800
Nevada      2,442    2,541    2,681    1,900    2,000 
2,100
======      =====    =====    =====    =====    ===== 
=====
  West     11,309   11,584   12,044    8,400    8,800 
9,400 
 

Note: You cannot use substitution variables in free-form mode.

Developing Report
Scripts
Once you understand the basics of creating report scripts, you can
create more complex reports. You create a report using extraction
commands which specify member combinations for pages, columns,
and rows. You use formatting commands to determine the visual
design of the report and to control the display of the data values.
Formatted data values are displayed in the report when you run the
script, based on the combined extraction and report commands.

This chapter provides information about creating complex report

scripts:

• Understanding Extraction and Formatting Commands

• Understanding Report Script Syntax
• Designing the Page Layout
• Formatting
• Selecting and Sorting Members
• Restricting and Ordering Data Values
• Converting Data to a Different Currency
• Generating Reports Using the C, Visual Basic, and Grid APIs

For fundamental information about reports and report scripts, see

Understanding Report Script Basics.

For report command syntax and an extensive set of report script

examples, see the Technical Reference.

Understanding
Extraction and
Formatting Commands
Extraction commands perform the following actions:
 • Determine the selection, orientation, grouping, and ordering
of raw data records extracted from the database. Extraction
commands are based on either dimension or member names,
or keywords. Their names begin with the greater-than symbol
(>).
• Apply to the report from the line on which they occur until the
end of the report. If another extraction command occurs on a
subsequent line of the report, it overrides the previous
command.

Formatting commands perform the following actions:

• Let you customize the format and appearance of a report and

create report-time calculations. Formatting commands are
generally enclosed inside left and right braces ({ }), although
there are several formatting commands that begin with the
less-than (<) character.
• Are either applied globally within the report script or are
specific to a member.

Understanding Report
Script Syntax
To build a report, you enter commands that define the layout, member
selection, and format you want in Report Script Editor. The different
elements of a script are color-coded to aid in readability. When you
write a report script, follow these guidelines:

• Separate commands with at least one space, tab, or new line

for readability. Report processing is not affected by extra
blank lines, spaces, or tabs.
• Enter commands in either 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 more than one format command within a single
set of braces. For example, these formats are synonymous:
• {UDATA SKIP}
• {UDATA} {SKIP}
• Enclose member names in quotation marks in the following
cases:
o Names beginning with an ampersand (for example,
"&Product").
o Names containing spaces (for example, "Cost of Goods
Sold").
o Names containing the word Default (for example,
"Default Value").
o Names containing one or more numerals at the
beginning of the name (for example, "100-Blue")
o Names containing any of the following characters:
* asterisks - dashes, hyphens, or minus signs
@ at signs < less than signs
{} braces () parentheses
[ ] brackets + plus signs
, commas ; semicolons
: colons / slashes
o

• If a formatting command is preceded by three or more

underscore, equal sign, or hyphen characters, respectively,
the Report Extractor assumes that the characters are
extraneous underline characters and ignores them. For
example, ==={SKIP 1}.
• Use // (double slash) to indicate a comment. Everything on
the line following a comment is ignored by the Report Writer.
Each line of a comment must start with a double slash, so you
can include multi-line comments.
• Exercise caution if you abbreviate command names.
Remember that many names begin with the same letters, and
the results may be unexpected unless you use a completely
unambiguous abbreviation.
Designing the Page
Layout
Reports are two-dimensional views of multidimensional data. You can
use page layout commands to incorporate additional dimensions that
are defined as nested groups of columns or rows on a page, or
additional pages in the report.

The page layout is composed of headings that make up the columns

and rows of a page. You define the basic layout of a report using page,
row, and column data extraction commands combined with specific
member selections.

Each component of page layout has a different formatting command:

<PAGE????????????<COLUMN????????????<ROW

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.

For information about formatting the page, column, or row headings,

see Formatting Page, Column, and Row Headings.

Creating Page, Column, and Row Headings

To design the report headings, perform the following tasks:
1. Type <PAGE (dimensionname, dimensionname)

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. The following is a valid
<PAGE command:
<PAGE (Measures, Market)
2. Press Enter.
3. Type <COLUMN (dimensionname)

where dimensionname equals the name of each dimension to

display across the page. The following is a valid <COLUMN
command:
 <COLUMN (Year)

You can add dimension names to create nested column

headings.
4. Press Enter.
5. Type <ROW (dimensionname)

where dimensionname equals the name of each dimension to

display down the page. The following is a valid <ROW command:
<ROW (Market)

6. Press Enter.

Note: You can select additional members to associate with the

heading commands. If you type a member name as a parameter for
the PAGE, COLUMN, or ROW commands, Report Extractor
automatically associates the member with the appropriate
dimension.

The following report script is based on the Sample Basic database:

<PAGE (Product, Measures)
<COLUMN (Scenario, Year)
Actual
<ICHILDREN Qtr1
<ROW (Market)
<IDESCENDANTS East
    ! 
 

This script produces the following report:

              Product Measures Actual

                      Jan      Feb      Mar     Qtr1 
                 ======== ======== ======== ======== 
New York              512      601      543    1,656 
Massachusetts         519      498      515    1,532 
Florida               336      361      373    1,070 
Connecticut           321      309      290      920 
New Hampshire          44       74       84      202 
  East              1,732    1,843    1,805    5,380  
 

You can create page, column, and row headings with members of
attribute dimensions. The following report script is based on the
Sample Basic database:

<PAGE (Measures,Caffeinated)
Profit
<COLUMN (Year,Ounces)
Apr May
"12"
<ROW (Market,"Pkg Type")
Can
<ICHILDREN East
    ! 
 

This script produces the following 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:

Report
Task
Command

Create a custom page heading in place of the STARTHEADING

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.

Display the page heading, either the default HEADING

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.

Force the immediate display of the heading IMMHEADING

without waiting for the next unsuppressed
data row, when heading suppression
commands are in use.

Automatically turn on the display of the COLHEADING

column header.

Display the page heading before the next data PAGEHEADING

output row.

For descriptions of the SUPPRESS commands used to suppress

headings, see Suppressing Page, Column, and Row Formatting.

Creating Symmetric and Asymmetric Reports

Analytic Services reports can contain symmetric or asymmetric column
groups. Analytic Services determines the symmetry of column groups
automatically, based on the members you select.

A symmetric report, shown below, is characterized by repeating,

identical groups of members.

            East                           West
   Budget       Actual             Budget      Actual
Q1  Q2  Q3     Q1  Q2  Q3        Q1  Q2  Q3   Q1  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                           West
   Budget        Actual                    Budget
Q1  Q2  Q3      Q1  Q2  Q3               Q1  Q2  Q3 
 
By default, Analytic Services 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
Technical Reference.

The Analytic Services evaluation of symmetry versus asymmetry takes

place prior to any ordering, restriction on columns, or application of
the effects of calculated columns.

Overriding Default Column Groupings

You can override the default column grouping that Analytic Services
selects for reports with the <SYM and <ASYM commands. <SYM and
<ASYM affect the member selection commands that follow them in a
report.

1. Use the <SYM command when the selection of column

members meets the requirements of the rule for asymmetry,
but you want to produce a symmetric report. The <SYM
command always produces a symmetric report, creating all
combinations of each column dimension.
2. Turn off the symmetric format and restore the rules for
asymmetric reports with the <ASYM command.

Changing Column Headings

If you only need to change the column headings rather than the
symmetry of the?report, the <PYRAMIDHEADERS and
<BLOCKHEADERS formatting commands are useful.

• Use the <BLOCKHEADERS formatting command to change the

pyramid-style headers used in symmetric reports to block-
style headers like?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 like?those used in symmetric reports.
An asymmetric report uses the <BLOCKHEADERS mode of
column layout.
Formatting
Formatting commands define the format of data and labels in the final
report. These commands are generally enclosed in left and right braces
({ }).

The two types of formatting commands are global and member-

specific commands.

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

Formatting Report Pages

There are a number of formatting commands that you can use to
design the look of the final report pages.

See the Technical Reference for report formatting examples.

Setting Page Length and Width and Centering

You can set the following page specifications in the report script:

Task Report Command

Specify the column widths in a report. WIDTH

Set the left margin of the report. LMARGIN

Set the center of the page. SETCENTER

Inserting Page Breaks

You can set the following types of page breaks in the report script:

Task Report Command

Set the number of lines for each page. PAGELENGTH

Force a page break regardless of how NEWPAGE

many lines have been generated for the
current page.

Insert a page break whenever a member PAGEONDIMENSION

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.

Enable page breaks in a report when the FEEDON

number of lines on a page is greater than
the current PAGELENGTH setting.

Formatting Page, Column, and Row Headings

Column and row formatting commands make up a special type of
format setting commands.

Specifying Column Formats

Specifications for column formatting commands can precede or follow
the columns to which they apply, depending on the desired format.
For example, in the following script, based on the Sample Basic
database, the first {DECIMAL} command is processed after only two
columns are set up, Actual?and Budget. The {DECIMAL} command,
however, refers to a column three, which does not yet exist. Analytic
Services responds to this command by dynamically expanding the
report to three columns. When the report specification expands to six
columns, the {DECIMAL} formatting applies to columns three and six
(and all multiples of three).

Analytic Services performs this pattern extension on the assumption

that when another dimension is added, causing repetitions of previous
column dimension groups, the formatting should repeat as well. The
second {DECIMAL} formatting command is then applied to columns 1
and 4 only, as it occurs after the creation of six columns.

<PAGE (Measures, Market)
Texas Sales
     <COLUMN (Scenario, Year)
     Actual Budget
{DECIMAL 2 3 }
     Jan Feb Mar
{DECIMAL 1 1 4 }
<ROW (Product)
<DESCENDANTS "100"
    ! 
 

This script produces the following report:

                           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. These examples are based on
the Sample Basic database.

//Script One: Format Columns by Distributing the Formats

<PAGE (Measures, Market)
California Sales
     <COLUMN (Scenario, Year)
     Actual Budget Variance
{DECIMAL 1 1 }
{DECIMAL 2 3 }
     Jan Feb
     //     {DECIMAL 1 1 4 }   These lines are commented; 
the
     //     {DECIMAL 2 3 6 }   Report Extractor ignores 
them.
<ROW (Product)
<DESCENDANTS "100"
    ! 
 
The two {DECIMAL} commands are positioned to format the individual
columns 1, 3, 4, and 6.

//  Script Two: Format Columns by Direct Assignment

<PAGE (Measures, Market)
California Sales
     <COLUMN (Scenario, Year)
     Actual Budget Variance
     //     {DECIMAL 1 1 }     These lines are commented; 
the
     //     {DECIMAL 2 3 }     Report Extractor ignores 
them.
     Jan Feb
{DECIMAL 1 1 4 7 }   
{DECIMAL 2 3 6 9 }
<ROW (Product)
<DESCENDANTS "100"
    ! 
 

Both scripts produce the following report:

                          Sales California

              Actual          Budget 
Variance
           Jan     Feb     Jan       Feb     Jan 
Feb
         =====    ====    ====      ====    ===== 
====
100­10   678.0     645   840.00    800.0    (162) 
(155.00)
100­20   118.0     122   140.00    150.0     (22) 
(28.00)
100­30   145.0     132   180.00    160.0     (35) 
(28.00  
 

Accommodating Long Column Names and Row

Names
Member names that are too long to fit into the column are
automatically truncated; the tilde character (~) signifies that part of
the name is missing. Long member names are common when using
aliases in the report.

There are several ways to modify columns to display the entire

member name.

Report
Task
Command

Define the column width for all row members in NAMEWIDTH

the column.

Change where the row member column is NAMESCOL

displayed, and to shift the remaining columns
left or right to make room fro the long member
names.

Suppressing Page, Column, and Row Formatting

You can suppress the display of page heading, columns, and rows in a
report by using SUPPRESS commands.

Suppress Report Command

The default column heading in the report. SUPCOLHEADING

Rows that have only zero or missing values. SUPEMPTYROWS

All rows that contain missing values. Use SUPMISSINGROWS

INCMISSINGROWS, INCZEROROWS, or
INCEMPTYROWS to display rows that are
empty,?or?have missing data or zeros.

The page member heading whenever a SUPPAGEHEADING

heading is generated.

The page and column headings, all member SUPALL

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.

The default heading (page header and SUPHEADING

column headers) or custom header, if
defined, at the top of each page.

Row member names in the final report. Use SUPNAMES

the NAMESON command to include row
member names in the report.

All output while continuing to process all SUPOUTPUT

operations, such as calculations, format
settings, and so forth.
Use the OUTPUT command to reverse the
actions of SUPOUTPUT.

Currency information when you use the SUPCURHEADING

CURRENCY command to convert the data
values in a report to a specified currency.
Repeating Row Names
To repeat the row member names on every line of the report, use the
<ROWREPEAT command. Use the <NOROWREPEAT command to
prevent row member names from being repeated on each line of the
report if the row member name does not change on the next line.
NOROWREPEAT is enabled by default.

Using Tab Delimiters

You can place tabs between columns rather than spaces in report
scripts, for example, when you want to export report output into
another form.

To replace spaces with tab delimiters, type {TABDELIMIT} anywhere in

the report script.

Adding Totals and Subtotals

Column and row calculations let you create additional calculations that
are not defined as part of the database outline. For example, you can
use column and row calculations to create extra columns or rows in a
report, based upon selected data members, and perform calculations
on these or existing columns and rows.

For examples of report scripts that contain column and row

calculations, see Sample 14, Calculating Columns in the "Example of
Report Scripts" page of the Technical Reference.

Totaling Columns
The CALCULATE COLUMN command lets you create a new report
column, perform on-the-fly calculations, and display the calculation
results in the newly created column.

The following table summarizes column calculation commands:

Task Report Command

Create a new report column, perform CALCULATE

dynamic calculations, and display the COLUMN
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.

Remove all column calculation definitions REMOVECOLCALCS

from the report.

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

mathematical operations. For syntax and parameter descriptions, see
the Technical Reference.

If you use the same name for more than one column, Analytic Services
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 two or more 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 the tilde character (~) 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.

This example is based on the Sample Basic database.

{CALCULATE COLUMN "Year to Date~Actual Total" = 1 : 2}
{CALCULATE COLUMN "Year to Date~Budget Total" = 3 : 4} 
 

The example produces the following 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 not defined.

In cases where there are fewer column header dimensions than the
number of levels that you want, you can create multi-line column
labels. In this case, use TEXT, STARTHEADING, ENDHEADING, and
other formatting commands to create a custom heading.

For the syntax and definitions of column calculation commands, see

the Technical Reference.

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 in the following examples:

• If the first section of a report has 12 columns (including row

name columns), and 3 calculated columns are declared,
column numbers 0-11 are the regular columns, and columns
12-14 are the calculated columns.
• If a second section of the report reduces the number of
regular columns to 6, then the regular columns are columns
0-5, and the same calculated columns are columns 6-8.
• Likewise, 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 looks as
follows:

internal
col # s: 0    1      2      3     4     5     6     7 
            Jan    Feb    Mar   Apr   CC1   CC2   CC3 
            ===    ===    ===   ===   ===   ===   === 
   Sales      1      3      5     3    22    55    26 
   Expense    1      2      5     3    23    65    33 

                 same report­ new section 
internal 
col # s: 0    1      2      3     4     5 
           Qtr1    YTD    CC1   CC2   CC3 
            ===    ===    ===   ===   === 
   Sales      2      9     22    57    36 
   Expense    4      8     56    45    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.

The following table summarizes row calculation commands:

Task Report Command

Create a new row and associate it with a CALCULATE ROW
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.

Temporarily disable row calculations in the OFFROWCALCS

report.?See also CALCULATE ROW and
ONROWCALCS.

Re-enable calculations after using ONROWCALCS

OFFROWCALCS. See also CALCULATE
ROW?and OFFROWCALCS.

Define complex calculations for the row SETROWOP

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.

Immediately display the row specified in PRINTROW

CALCULATE ROW to the report.

Reset the value of the calculated row to CLEARROWCALC

#MISSING. See also CLEARALLROWCALC.

Reset the value of all calculated rows after CLEARALLROWCALC

using the CLEARROWCALC command.

Create a new calculated row with captured SAVEROW

data. See also SAVEANDOUTPUT.

Capture data and output the result after SAVEANDOUTPUT

using the SAVEROW command.

For the syntax and definitions of row calculation commands, see the
Technical Reference.
Commands that designate columns must use valid data column
numbers, as determined by the original order of the columns.

• Precede and follow all operators in an expression with a single

space.
• Analytic Services does not support nested (parenthetical)
expressions.
• Analytic Services supports integer and floating-point
constants in expressions as single entries or members of an
array.

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.

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. For syntax and parameter descriptions, see the Technical
Reference.

This example is based on the Sample Basic database.

{ CALC ROW "Total Sales" = "Sales..Group1"
     + "Sales..Group2" } 
 

The example creates "Total Sales" based on two other calculated rows.

Changing How Data Is Displayed

You can use a variety of formatting commands to customize how data
displays in the final report.

Underlining
Use underlining as a visual aid to break up blocks of information in a
report.
Task Report Command

Set the default underline character to UNDERLINECHAR

display in the report.

Underline all characters that are not UCHARACTERS

blank in the preceding row.

Underline all the columns in the UCOLUMNS

preceding row.

Underline all the data columns for a row, UDATA

while not underlining the row name
columns.

Underline all the row name columns in UNAME

the preceding row while not underlining
the data columns.

Underline the row member names in a UNAMEONDIMENSION

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.

Suppressing Data Formatting

You can suppress data that you do not want to be displayed in the final
report by using SUPPRESS commands.

Report
Suppress
Command

Brackets around negative numbers. Use the SUPBRACKETS

BRACKETS command to re-enable brackets.

Commas in numbers greater than 999. Use SUPCOMMAS

the COMMAS command to re-enable commas.
Rows that have only zero data values. Use SUPZEROROWS
INCZEROROWS or INCEMPTYROWS to re-
enable the?display.

The European method for displaying numbers SUPEUROPEAN

(2.000,01 whereas the non-European
equivalent is 2,000.01). Use the EUROPEAN
command to re-enable European number
display.

The automatic insertion of a page break SUPFEED

whenever the number of lines on a page
exceeds the current PAGELENGTH setting.

Formats that produce output such as SUPFORMATS

underlines and skips. Use INCFORMATS to re-
enable the display.

Text masks that were defined in the report SUPMASK

using the MASK command. Use INCMASK to
re-enable the display.

See Suppressing Page, Column, and Row Formatting for descriptions of

the SUPPRESS commands used to suppress formats.

Indenting
Use indenting to provide visual clues to row levels of the script.

Report
Task
Command

Shift the first row names column in column INDENT

output order by a specified number of characters.

Indent subsequent row members in the row INDENTGEN

names column based on the generation in the
database outline. Use the NOINDENTGEN
command to left-justify row member names
based on generation name.

Inserting Custom Titles

Titles are user-generated and optional, in contrast to the automatically
generated page and column headings and row names, which describe
the data on the report page.

Titles repeat at the top of each report page, and provide the following
information about a report:

• A date and time stamp

• The user ID of the person running the report
• Page numbers
• The name of the source database
• Any other descriptive information

To add a title to the report, use the TEXT command, combined with
any of the following:

• Any of the predefined keywords that automatically display

information in the report
• A text string that you define

Note: You can also use the TEXT command at the bottom of the
report to provide summary information.

See the Technical Reference for the syntax and definitions of Report
Writer commands.

Replacing Missing Text or Zeros with Labels

When you run a report, there are often many empty data cells where
no data was applicable to the retrieval, or cells where the value is zero.

The report displays the default #MISSING label in the data cell when
no data values are found.

To replace the #MISSING label with a text label add the following to
the report script:
At the point in the script where you want to replace the #MISSING
label with a text label, type:

{MISSINGTEXT ["text"]}  
 

where text is any text string that you want to display in the data cells.

You can place the MISSINGTEXT command at any point in the report
script; the command applies throughout the script.

Note: You can also suppress #MISSING labels from appearing in

the report. See Suppressing Data Formatting for descriptions of
SUPPRESS commands used to suppress labels, or see the Technical
Reference for the syntax and definitions of Report Writer
commands.

To replace zeros with a text label add the following to the report
script:

At the point in the script where you want to replace zeros with a text
label, type

{ZEROTEXT ["text"]}  
 

where text is any text string that you want to display in the data cells.

Note: If a value is equal to #MISSING, any string you try to insert

after that value using the AFTER command does not print. AFTER
strings also do not print if you replace #MISSING with some other
value (such as 0).

Adding Blank Spaces

Adding blank spaces in a report draws the reader to key information,
such as totals.

Task Report Command

Add one or more blank lines in the final SKIP

report.
Add a blank line when a member from the SKIPONDIMENSION
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.

Changing How Data Values Display

You can use the following commands to change how data values
display in the final report.

Report
Task
Command
Turn on the display of commas for numbers greater than 999 COMMAS
after commas have been suppressed with either a
SUPCOMMAS or SUPALL command.
Turn on the display of brackets around negative numbers BRACKETS
instead of negative signs, after using the SUPBRACKETS
command earlier in the script.
Include a percentage sign or other character after the data AFTER
values.
Include a dollar sign or other character before the data values. BEFORE

Use the European method for displaying numbers where EUROPEAN

decimal points are used as the thousands separator character
while commas separate the decimal portion of the number from
the integer portion (2.000,01, whereas the non-European
equivalent is 2,000.01).
Overwrite text in each output row with a specified characters MASK
and position.
Selecting and Sorting
Members
The data that is displayed in the final report is based upon the
members that you?select and the order in which you display them. In
addition, you can use conditional retrievals to further refine the
selection and sorting of members.

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.

Report
Task
Command
Select all the members from the same dimension as the ALLINSAMEDIM
dimension member.
Include all the siblings of the specified member. ALLSIBLINGS

Include all the ancestors of the specified member. ANCESTORS

Select a base dimension member based on its attributes. ATTRIBUTE

Select all members in the level immediately below the CHILDREN

specified member.
Include the descendants of the specified member to the DESCENDANTS
report, excluding the dimension top.
Select the level 0 members, that is, the members at the DIMBOTTOM
bottom of the dimension.
Include the top member of the dimension. DIMTOP
Include a member and its ancestors. IANCESTORS

Select the specified member and all members in the ICHILDREN

level immediately below it.
Include the specified member and its descendants. IDESCENDANTS

Include the specified member and its parent. IPARENT

Include all members from the same dimension and OFSAMEGEN

generation as the specified member.
Include all members from the same dimension and on ONSAMELEVELAS
the same level as the specified member.
Include the parent of the specified member to the report. PARENT

Extract data for a specified date or for a time period TODATE

before or after a specific date.
Include base dimension members associated with the WITHATTR
specified attribute dimension.

Selecting Members by Using Generation and Level Names

Generation and level name selection commands identify a specific level
or generation of members based on either of the following items:

• The default generation or level name in the outline

• The user-defined generation or level name in the outline

When you use generation and level names, changes to the outline are
automatically reflected in the report. You can either define your own
generation and level names, or you can use the default names
provided by Analytic Services. For a discussion, including examples, of
generations and levels, see Generations and Levels.

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 do not need to change the report if the
member name is changed or deleted from the database outline.

Note: Generation and level names are stand-alone commands. You

cannot use them in place of member names in report extraction or
formatting commands. For example, you cannot use them with the
<DESCENDANTS or <CHILDREN commands.

To use default level names add the following to the report script:

At the point in the script where you want to select a member by the
default level name, use the following format:

Levn,dimensionName  
 

where n is the level number.

dimensionName is the name of the dimension from which you want to

select the members.

Note: Do not put a space after the comma.

For example, Lev1,Year selects all the level 1 members of the Year
dimension.

To use default generation names add the following to the report

script:

At the point in the script where you want to select a member by the
default generation name, use the following format:

Genn,dimensionName  
 

where n is the generation number.

dimensionName is the name of the dimension from which you want to

select the members.

Note: Do not put a space after the comma.

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 is based on the Sample Basic database. It 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
    ! 
 

The report script produces the following report:

                         Cola Market Scenario
                   Qtr1     Qtr2     Qtr3     Qtr4
                 ======== ======== ======== ======== 
Sales              14,585   16,048   17,298   14,893
    Profit          5,096    5,892    6,583    5,206 
 

Selecting Dynamic Time Series Members

You create and identify dynamic members in the database outline;
they are members that are calculated only during user retrieval
requests, such as generating a report script. The time dimension has
special Dynamic Time Series option. The Dynamic Time Series option
has reserved the following generation names that you can define in the
outline alias table:
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 for information about creating and maintaining Dynamic
Time Series generation names in the database outline.

Note: The database header message for the outline identifies the
number of dynamic members that are enabled in the current
outline.

To select a Dynamic Time Series member add the following to the

report script:

At the point in the script where you want to select a Dynamic Time
Series member, use either of the following formats:

<LATEST memberName  
 

where memberName is the name of the member in the time

dimension.

The <LATEST command is a global command that is applied to the

entire report script, and is an aggregation based on the lowest level
member within the dimension.
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.

Note: You must type the Dynamic Time Series string exactly as it is
displayed in the database outline; you cannot create your own
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.

Selecting Members by Using Boolean Operators

Boolean operators let you specify precise member combinations within
a report, which is particularly useful when dealing with large outlines.
Use the AND, OR, and NOT Boolean operators, combined with
extraction commands, to refine member selections within the report
script.

• Use the AND operator when all conditions must be met.

• Use the OR operator when one condition of several must be
met.
• Use the NOT operator to choose the inverse of the selected
condition.
To create a Boolean expression using operators add the following to
the report script:

At the point in the script where you want to use linking, enter the
following 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: You must select members from the same dimension, and all
extraction command arguments must be enclosed in parentheses,
as in the example above. NOT can only be associated 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. See the Technical Reference for a list of all
valid extraction commands that can be used in conjunction with the
LINK command.

Examples:

<LINK ((<IDESCENDANTS("100") AND <UDA(Product,Sweet)) OR 
ONSAMELEVELAS "100"­10") 
 

selects sweet products 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") 
 

selects products that are not sweet from the "100" subtree, plus all
products on the same level as "100-10.

See the Technical Reference for additional examples of narrowing

member selection criteria.

Selecting Members by Using Substitution Variables

Substitution variables act as global placeholders for information that
changes regularly; you set the substitution variables on the server
through Essbase Administration Services, MaxL, or ESSCMD, and
assign a value to each variable. You can then change the value at any
time, reducing manual changes to a report script. You must have the
role of at least Database Designer to set substitution variables.

For example, many reports are dependent on reporting periods; if you

generate a report based on the current month, you must manually
update the report script every month. With a substitution variable set
on the server, such as CurMnth, you can change the assigned value
each month to the appropriate time period. Analytic Services
dynamically updates the information when you run the final report.

See Using Substitution Variables for a comprehensive discussion of

creating and changing substitution variables in the database outline.
See the Technical Reference for information about the leading &
character.

You can set substitution variables at the following levels:

• 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
• Database, providing access to the specified database
To use a substitution variable add the following to the report script:

The substitution variable must be accessible from the application and

database against which you are running the report.

At the point in the script where you want to use the variable, use the
following format:

&variableName 
 

where variableName is the same as the substitution variable set on the

server.

For example,

<ICHILDREN &CurQtr 
 

becomes

<ICHILDREN Qtr1 
 

Note: The variable name can be an alphanumeric combination whose

maximum size is specified in Limits. You cannot use spaces or
punctuation in the variable name.
When you run the report script, Analytic Services replaces the variable
name with the substitution value and that information is incorporated
into the final report.

Selecting Members by Using Attributes

Using attributes, you can select and report on data based on one or
more characteristics of base members. You can group and analyze
members of base dimensions according to their attributes. You can
also perform crosstab reporting based on two or more 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 flavored
juice and orange flavored juice were sold in New York during the first
quarter.

To select a member based on a specific attribute add the following to

the report script:

At the point in the script where you want to select members based on
a specific attribute, use the following format:

<ATTRIBUTE memberName 
 

where memberName is the name of an attribute-dimension member;

for example:

<ATTRIBUTE Bottle 
 

returns all products packaged in bottles.

There can be cases where attribute dimensions have members with

the same name. For example, the attribute dimension Ounces and the
attribute dimension Age can each have a member named 24. To
ensure that a query returns correct results, you must specify the full
attribute-dimension member name. The following format returns all
products that are packaged in 24 oz. units:

<ATTRIBUTE Ounces_24 
 
Attribute types can be text, numeric, date, and Boolean. For a
description of each attribute type, see Understanding Attribute Types.

Selecting Members by Attribute Association

You can select all the base dimension members associated with one or
more attributes using the <WITHATTR command. For example, you
can display all products associated with a member of the Pkg Type
attribute dimension. At the point in the script where you want to select
the members, enter the following syntax:

<WITHATTR (attributeDimensionName, "Operator", Value) 
 

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

Selecting Members by Date

You can extract attributes data for a specific date, for a period before a
specific date, or for a period after a specific date using the <TODATE
command. For example, you can extract information on all products
that were introduced on December 10, 1996, before December 10,
1996, or after December 10, 1996. The?<TODATE command must be
used within the <WITHATTR command. For?example, the following
format returns data on all products that were introduced on December
10, 1996.

<WITHATTR ("Intro Date", "=", <TODATE ("mm­dd­yyyy", "12­10­
1996") 
 

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 between January 1, 1970 and January 1, 2038
(inclusive).

Selecting Members by Using UDAs

A user-defined attribute (UDA) enables you to select and report on
data based on a common characteristic. These attributes are
particularly useful when performing member selections from an outline
with an unbalanced hierarchy (a hierarchy where the members of a
dimension do not have identical member levels). You can set UDAs on
the server for characteristics such as color, size, gender, flavor, or any
other common member characteristics. You must have Database
Designer permissions to set UDAs on the server.

UDAs are different from attributes. UDAs are member labels that you
create to extract data based on a particular characteristic, but you
cannot use UDAs to group data, to perform crosstab reporting, or to
retrieve data selectively. Hence, for data analysis, UDAs are not as
powerful as attributes.
You can use the UDA command in conjunction with Boolean operators
to refine report queries further. See Selecting Members by Using
Boolean Operators for examples of the UDA command being used with
a Boolean operator.

See Creating UDAs for information about creating and maintaining

UDAs.

To select members based on a UDA add the following to the report

script:

At the point in the script where you want to select members based on
the UDA, use the following format:

<UDA (dimensionName,"UDAstring ") 
 

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, Analytic Services incorporates the UDA
members into the final report.

Note: You must type the UDA string exactly as it is displayed in the
database outline; you cannot create your own UDA string and
incorporate it into the report script.

Selecting Members by Using Wildcards

You can use wildcards to select either members, generation, or level
names in a report script. If you use member names, Analytic Services
searches the member and all descendants of that member. If you
specify a generation or level name, Analytic Services searches only
members of that generation or level.

Using wildcards reduces the amount of member information needed for

a script and simplifies script maintenance.

The following two types of wildcards are supported in Report Writer:

 • Trailing asterisk (*) characters at the end of the string to
search for common member properties
• Pattern-matching question mark (?) characters anywhere in
the string to represent any single-character member property
To select members using a trailing wildcard add the following to the
report script:

At the point in the script where you want to select members using a
trailing wildcard, use the following 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. Using
the Sample Basic database,

<MATCH (Year,"J*") 
 

returns Jan, Jun, and Jul.

To select members using a pattern-matching wildcard add the

following to the report script:

At the point in the script where you want to select members using a
pattern-matching wildcard, use the following format:

<MATCH (memberName,"???characters") 
 

where memberName is the name of the member to select, and

characters are the characters in the following member. Using the
Sample Basic database,

<MATCH (Product,"???­10") 
 

returns 100-10, 200-10, 300-10, and 400-10.

Note: In the Sample Basic database example, three question marks

are used to represent the variable three characters in the string. If
only two question marks were used in the example, no matches are
found. You can place question mark wildcards anywhere in the
match string.

Selecting Members by Using Static Member Names

Static member names are unchanging member names, such as Sales
and COGS, that you enter directly into the report script. Although they
are easy to establish, static member name definitions can be difficult
to maintain if the database outline changes. You must change the
member name in every script that is used with that database.

In general, report scripts are easier to maintain if you use generation

and level names, or member selection commands, rather than static
member names whenever possible. For example, when you remove a
product, such as Widgets, from the dimension, the member selection
command <children Product works, but?a specific list referencing
Widgets as a static member name generates the following error
message:

"Unknown Member [Widgets]." 
 

Static members tend to be particularly difficult to maintain when

dealing with distributed OLAP databases, where both source and target
databases must be consistent.

Note: These user-defined, static member generation and level

names are not displayed in Outline Editor.

The following report script uses a static member called ProductGroups

to select all the Level 1, Product member names from the Sample
Basic database.

<PAGE(Year)
<COLUMN(Product)
<ROW (Measures)
Qtr1
ProductGroups
Sales Profit
    ! 
 
The report script produces the following report:

                        Qtr1 Market Scenario 
                  100      200      300      400 
Diet   
             ======== ======== ======== ======== 
======== 
Sales          25,048   26,627   23,997   20,148 
25,731 
    Profit      7,048    6,721    5,929    5,005 
7,017  
 

When you run a report that includes static member definitions, the
report displays members in order of their definition in the report script
by member name. Sort commands have no effect on static member
definitions. See Sorting Members for a discussion of the effects of
sorting members.

Suppressing Shared Members

You can suppress the display of duplicate shared members when you
extract data for a report. You can only suppress shared member
display in conjunction with the following items:

• Generation names
• Level names
• DIMBOTTOM command
• OFSAMEGEN command
• ONSAMELEVELAS command

Suppressing shared members is useful when you want to eliminate

unnecessary duplication of data within the report.

To suppress shared members add the following to the report script:

At the point in the script from which you want to suppress a shared
member, use

<SUPSHARE  
 

This command suppresses the display of shared members for the

duration of the report script. Use the <SUPSHAREOFF command to
reset the display of shared members in the script.

Selecting Alias Names for Members

Aliases make reports easier to read and help the reader focus on the
data values rather than the meanings of member names. You can
display members in a report by their aliases. For example, you can
display page, column, and row names, such as Diet Cola or Caffeine
Free Cola, rather than the corresponding member names 100-20 and
100-30.

Report
Task
Command
Display the alias set in the current alias table, without the OUTALT
member name.
Display the alias set in the current alias table, followed by OUTALTMBR
the member name.
Display the member name, followed by the alias set in the OUTMBRALT
current alias table.
Display the alias set in the current alias table, without the OUTALTNAMES
member name, for all members in the report.
Reset the default display of member names after using the OUTMBRNAMES
OUTALTNAMES command.
Include several alias tables within one report script. OUTALTSELECT

For a complete listing of alias commands, see the Technical Reference.

To Display 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 lets you
display more descriptive page, column, and row names, such as Diet
Cola 100-20 or 100-30 Caffeine Free Cola.

To display a member name and alias, use the <OUTALTNAMES and

<OUTALTMBR commands together in a report script, as illustrated in
the following example:

<PAGE (Product, Measures)
<COLUMN (Scenario, Year)
{OUTALTNAMES}
<OUTALTMBR
Actual
<ICHILDREN Qtr1
<ROW (Market)
<IDESCENDANTS "300"
    ! 
 

The report script produces the following report:

                 Dark Cream 300­10 Measures Actual 
                      Jan      Feb      Mar     Qtr1 
                 ======== ======== ======== ======== 
Market                800      864      880    2,544 

                 Vanilla Cream 300­20 Measures Actual 
                      Jan      Feb      Mar     Qtr1 
                 ======== ======== ======== ======== 
Market                220      231      239      690 

                 Diet Cream 300­30 Measures Actual 
                      Jan      Feb      Mar     Qtr1 
                 ======== ======== ======== ======== 
Market                897      902      896    2,695 

                    Cream Soda 300 Measures Actual 
                      Jan      Feb      Mar     Qtr1 
                 ======== ======== ======== ======== 
Market              1,917    1,997    2,015    5,929 
 

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

Report
Task
Command
Sort all members alphabetically by the alias name of the SORTALTNAMES
member, if aliases are used in the report script.
Sort all following members in ascending order starting SORTASC
with the lowest generation and moving toward the
highest generation.
Sort all following members in descending order starting SORTDESC
with the highest generation and moving toward the
lowest generation.
Sort all following members according to the generation SORTGEN
of the member in the database outline.
Sort all following members according to the level of the SORTLEVEL
member in the database outline.
Sort all members alphabetically by member name. SORTMBRNAMES

Disable all previous sorting commands so that members SORTNONE

added to the report follow the normal hierarchical order
based on the database outline.

For a list of sorting commands syntax and descriptions, see the

Technical Reference.

Restricting and
Ordering Data Values
Several Report Writer commands let you perform conditional retrieval
and data sorting in reports.

Report
Task
Command
Specify the number of rows to return. These rows must TOP
contain the top values of a specific data column.
Specify the number of rows to return. These rows must BOTTOM
contain the lowest values of a specific data column.
Specify the conditions the columns of a data row must satisfy RESTRICT
before the row is returned.
Specify the ordering of the rows of a report, based on the data ORDERBY
values of data columns.

For the syntax, definitions, and detailed examples of these commands,

see the Technical Reference.

Configurable variables are used during conditional retrievals. For

information about setting the Report Writer configurable variables, see
Changing Buffer Size.

Understanding the Order of Operation

<RESTRICT, <ORDERBY, <TOP, and <BOTTOM can be displayed
anywhere in the report script and in any order. When using these
commands, place all global script formatting commands before a Page
member or a Column member, or before a <PAGE command or
<COLUMN command that expands into Page or?Column members (for
example, IDESCENDANTS, or ICHILDREN).

Analytic Services extracts data and applies restrictions and ordering in

the following order:

• Applies RESTRICT and any existing restrictive option such as

SUPPMISSING, SUPZEROS, and SUPEMPTYROWS.
• Applies TOP or BOTTOM, or both.
• Applies ORDERBY.

Analytic Services then returns rows and displays output.

Using TOP, BOTTOM, and ORDERBY with Sorting Commands

<TOP, <BOTTOM, and <ORDERBY commands sort the output of a
report by its data values. Analytic Services applies <TOP and
<BOTTOM first, followed by <ORDERBY. If the report contains a sort
command, such as <SORTMBRNAMES, which sorts members and not
data, Analytic Services applies the sort command first, followed by
<TOP and <BOTTOM, and then <ORDERBY. <ORDERBY is the final sort
that takes place.

Using RESTRICT
The arguments of the <RESTRICT command let you specify
qualifications for selecting rows. Analytic Services 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.

Analytic Services 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 (... (@DATACOL(1) > 300 AND @DATACOL(2) < 600)...) 
 

Only one <RESTRICT is allowed per report, as terminated by the !

command. If a report script contains more than one report, each
<RESTRICT overwrites the one in the previous report, as illustrated in
the following example:

RESTRICT (@DATACOL(1) > @DATACOL(2) AND 800 < @DATACOL(3) 
OR @DATACOL(4) <> #MISSING) 
 

This <RESTRICT command is equivalent in operation to the following

syntax:

RESTRICT (((@DATACOL(1) > @DATACOL(2)) AND 
(800<@DATACOL(3))) OR (@DATACOL(4) <> #MISSING)) 
 

Using ORDERBY
The <ORDERBY command orders the output rows according to the
data values in the specified columns. You can specify either ascending
<ASC (the default) or descending <DESC.You can specify different
sorting directions in different columns of the same report .

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 more than one report, each
<ORDERBY overwrites the one in the previous report.

Using ORDERBY with Formatting Commands

Follow these guidelines when using the <ORDERBY command in a
report script:

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

Using TOP and BOTTOM

The <TOP and <BOTTOM commands specify the qualified number of
rows with the highest or lowest column values, respectively, within a
row group to be returned in a report. If the row group member is not
specified, the innermost row group dimension is the default row group.

You can use <TOP and <BOTTOM together in the same report, but only
one <TOP and one <BOTTOM is allowed per report. In this case, the
two commands should have the same data column as their argument
in order to prevent confusion. The result of the <TOP and <BOTTOM
command is sorted by the value of the data column specified in the
command in descending order.

<TOP and <BOTTOM work only on the range of rows specified in row
member selection.
Note: If <TOP or <BOTTOM occurs with <ORDERBY, the ordering
column of the <ORDERBY does not have to be the same as the data
column of the <TOP or the <BOTTOM.

If any combination of the <ORDERBY, <TOP, or <BOTTOM commands

exist together in a report script, the row group member
(<rowGroupMember>) should be the same. This restriction removes
any confusion about the sorting and ordering of rows within a row
group.

Caution: Analytic Services 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, @DATACOL(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.

                            Actual              Budget
                       Qtr1       Qtr2       Qtr1 
Qtr2   
Florida     100­10      570       670        570 
650 
            100­20      235       345        321 
432 
            100­30      655       555        455 
865 
            100­40      342       342        432 
234 
Maine       100­10      600       800        800 
750 
            100­20      734       334        734 
534 
            100­30      324       321        235 
278 
            100­40      432       342        289 
310 
New York    100­10     1010      1210       1110     910 
            100­20      960       760        650 
870 
            100­30      324       550        432 
321 
            100­40      880       980        880 
1080 
            100­50      #MI       #MI        #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, @DATACOL(2)) 
 

This command returns the following rows:

New York    100­10     1010     1210     1110     910   
            100­40      880      980      880    1080 
Maine       100­10      600      800      800     750  
 
This example returns two rows with the lowest data values in col2
(Actual, Qtr2) per row group.

3­ BOTTOM ("market", 2, @DATACOL(2)) 
 

This command returns the following rows:

Maine       100­20      734       334       734 
534   
            100­30      324       321       235 
278  
 

Note: <TOP and <BOTTOM put an upper limit on the number of

(qualified) rows returned after all restrictions are applied. This
upper limit is equal to the number of rows in the <TOP plus the
number of rows in the <BOTTOM commands.

Understanding How Other Report Configurations

Affect TOP and BOTTOM
When using the <TOP and <BOTTOM commands, be aware that some
other commands affect their operation. In particular, Analytic Services
treats the <SUPPMISSING, <SUPZEROS, and <SUPEMPTYROWS
options as restrictions and applies them to the extracted rows along
with the <RESTRICT command restrictions. Analytic Services applies
these optional restrictions to the data rows before processing the
<TOP or <BOTTOM commands, and before applying an <ORDERBY
command.

Using TOP and BOTTOM with Formatting Commands

Whenever a formatting command occurs in a report, it is appended to
the member that follows it. For example, in this sequence,
{UCOLUMNS}, the underline columns command is appended internally
to the member that comes next. In Script?1, it is appended to the row
member that can be described as "first child of market, assuming
Florida."

SCRIPT 1                 SCRIPT 2 
....                     .... 
< ROW Market             {UCOL} 
{UCOL }                  < Florida    (row member)   
<ICHILDREN Market
< TOP ....               < BOTTOM ....  
 

Script 2, appends {UCOLUMNS} to the row member Florida. Analytic

Services 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, you should 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.

Converting Data to a
Different Currency
If the database has a currency partition, you can calculate currency
conversions in report scripts. Use the <CURRENCY command to set the
output currency and currency type. Use the <CURHEADING command
to display the currency conversion heading.
Note: Currency conversion is not supported across transparent
partitions.

For information about creating a currency conversion application, see

Building Currency Conversion Applications and Performing
Conversions.

For the syntax and definitions of Report Writer commands, see the
Technical Reference.

Generating Reports
Using the C, Visual
Basic, and Grid APIs
Use the following table to determine the report API calls that you can
make:

Visual Basic API C Grid API

Task C API Function
Function Function
Start sending a ESSBEGINREPORT ESBBEGINREPORT ESSGBEGINREPORT
report
specification to
the active
database.
Mark the end ESSENDREPORT ESBENDREPORT N/A
of a report
specification
being sent to
the active
database.
Send a report ESSREPORT ESBREPORT N/A
specification to
the active
database as a
single string.
Send a report ESSREPORTFILE ESBREPORTFILE ESSGREPORTFILE
specification to
the active
database from a
file.

See the API Reference for syntax and descriptions of these API
functions.

Mining an Analytic Services Database

Data mining is the process of searching through an Analytic Services database for hidden
relationships and patterns in a large amount of data. Using traditional query tools, you
can answer many standard questions about your business, such as "How profitable were
root beer sales in New York in July?" Data mining helps you to search through large
amounts of data and come up with new questions, such as "What will root beer sales look
like in August?"
This chapter describes data mining and explains how to mine Analytic Services
databases.
• Understanding Data Mining
• Essbase XTD Analytic Services Data Mining Framework
• Built-in Algorithms
• Accessing Data Mining Functionality
• Creating New Algorithms

Understanding Data Mining

Data mining tools can sift through data to come up with hidden relationships and
patterns. You may find that people who bought root beer in July also bought ice cream in
July. Then you can use this knowledge to create an advertising campaign around root beer
floats.
You can use data mining to tell you things about existing data, as in the root beer
example. Such data mining is called descriptive. You can also use data mining to forecast
future results based on past performance. For example, you can forecast sales for next
year based on sales for this year. Such data mining is called predictive.

Essbase XTD Analytic Services Data

Mining Framework
Data Mining Framework is a collection of features that enables the performance of data
mining on Analytic Services databases. Data Mining Framework is licensed separately
from Analytic Services.
Note: Data Mining Framework does not currently operate on relational data, that is,
hybrid analysis data. Data mining is also not supported currently for Unicode-mode
applications.
The process of mining an Analytic Services database includes the following tasks:
• Specify a build task.
You implement a build task through a task template. The Mining Wizard,
available with Administration Services, provides a build task template and steps
you through the process of specifying a build task. You can also use MaxL
statements and template files provided with Data Mining Framework.
In the build task, you specify:
• The algorithm to use.
• The database to mine and a representative set of data.
• Parameters that determine how the algorithm is applied.
• Execute the build task to build, or train, a model.
When you execute a build task, the specified algorithm is applied against the the
specified set of data to generate a data mining model. During the training process,
the algorithm discovers and describes the patterns and relationships in the data
that can be used for prediction. Later, the trained model can use these patterns and
relationships to generate new information from a different, but similarly
structured, set of data.
See Training the Model.
• Specify a test task to test the model. This is an optional task to verify the accuracy
of the model you have built.
You implement a test task through a task template using the Mining Wizard or
MaxL statements.
In the test task, you specify:
• The model to use. This is a model that you have built.
• A database and set of data to mine. Specify a set of data with known
results or correlations.
• Execute the test task to generate test results.
After training the model on one set of data, you execute the model against a
different set of data with known results or correlations. You can compare the
results generated by the model with the known results to determine the accuracy
of the model.
See Testing the Model.
• Specify an apply task.
You implement an apply task through a task template using the Mining Wizard or
MaxL statements.
In the apply task, you specify:
• The model to use. This is a model that you have built.
• A database and set of data to mine
• Execute the apply task to generate result records.
When you execute an apply task, the model is executed against the specified set
of data to generate result records. Data Mining Framework writes results back to
the Analytic Services cube.
 See Applying the Model.
• Query the result records.
Query the result records to view the data mining results.

The following sections describe the data mining process in more detail.

Creating Data Mining Models

The first step in building a data mining model is to understand the business situation or
problem and choose the appropriate algorithm to use for analysis or prediction.
Algorithms determine how you search through data.
Data Mining Framework provides a set of powerful algorithms that can be used for a
broad range of business applications. See Built-in Algorithms for a description of the
available algorithms. The description of each algorithm provides information about the
type of problem that it is best suited for.
Note: Data Mining Framework also enables you to easily register and use new algorithms
created by Hyperion or third-party vendors.
For example, suppose you want to determine how sales of televisions, DVDs, and VCRs
in the East region correspond to sales of cameras in the same region. You can use the
regression algorithm to model sales of cameras as a function of sales of TVs, VCRs, and
DVDs.
The regression algorithm predicts the value of a dependent (target) variable based on the
value of one or more independent (predictor) variables.
Using an Algorithm
All data mining algorithms require training, or learning. Training is the process of
executing an algorithm against a representative set of data to discover and describe the
patterns and relationships in the data that can be used for prediction. Once a model has
been trained against a representative set of data, it can then be applied to a wider set of
data to derive useful information.
Learning can be either supervised or unsupervised. Supervised learning discovers
patterns and relationships in the data by comparing the resulting data to a set of known
data. Unsupervised learning discovers patterns and relationships in the data without
comparing the data to a known set of data.
The algorithm vendor determines the specific information that you must provide to use
the algorithm. The regression algorithm employs supervised learning. Therefore, the
model requires both input data and output data.
To use an algorithm, you need to enter its settings, parameters and accessors.
Settings are actually determined by the Data Mining Framework, and as such are the
same for all algorithms, but they do influence the operation of the algorithm. For
example, the framework provides a setting to define how missing values are treated by
the algorithm.
Parameters are specific to each algorithm and determine how the algorithm operates on
the data. For example, the clustering algorithm provides a parameter to specify the
maximum number of clusters to return.
Accessors specify the input and output data for the algorithm. In a build task, supervised
algorithms such as regression have two accessors, a predictor to define the independent or
input data, and a target to define the dependent or expected output data. Unsupervised
algorithms, such as clustering, have a predictor accessor only.
Test and apply tasks generally have both predictor accessors to define the input and target
accessors to define the output.
Accessors consist of domains, which are typically MaxL DML expressions that define
components of the accessor. For example, the predictor accessor for the regression
algorithm contains the following domains:
• Predictor.Predictor
Defines the member or member set combination that determines the predictor
domain.
• Predictor.Sequence
Defines the sequence to be traversed for the predictor variable. Sequence is
generally a time dimension.
• Predictor.External
Defines the scope of the predictor. It is optional.
• Predictor.Anchor
Defines restrictions from additional dimensions. It is optional.

The target accessor has the same set of domains as the predictor. You write MaxL DML
expressions to define the predictor and target accessors.
For example, consider this sample data mining problem:
Given the number of TVs, DVDs, and VCRs sold during a particular period, in the East
region, how many cameras were sold in the same period in the East? Restrict sales data to
prior year actual sales.
Using the regression algorithm, the predictor and target accessors to define the model for
this problem are as follows:

Predictor.Predictor {[Television], [DVD], [VCR]}

Predictor.Sequence {[Jan 1].Level.Members}
Predictor.External {[East].Children}
Predictor.Anchor {([2001], [Actual], [Sales])}
Target.Target {[Camera]}
Target.Sequence {[Jan 1].Level.Members}
Target.External {[East].Children}
Target.Anchor {([2001], [Actual], [Sales])}

Note: In this example, the target accessor is the same with regard to all the predictor
attributes except the target domain ({[Camera]} ). However, the domain expressions for
different accessors are not required to be the same. The only requirement is that a
predictor component (for example predictor.sequence) and the corresponding target
component (target.sequence) must be the same size.
For each city in the East ({[East].Children}), the algorithm models camera sales as a
function of TV, DVD, and VCR sales. The Data Mining Framework creates, under the
same name, a family of results, or models; a separate result for each city in the East.
Training the Model
The final step of specifying a build task is to execute the algorithm against the data
specified by the accessors to build or train the model. During the training process, the
algorithm discovers and describes the patterns and relationships in the data that can be
used for prediction.
Internally, the algorithm represents the patterns and relationships it has discovered as a
set of mathematical coefficients. Later, the trained model can use these patterns and
relationships to generate new information from a different, but similarly structured, set of
data.
Note: If you cancel a data mining model while you are training it, the transaction is rolled
back.

Applying the Model

After the model is trained, it is ready to use on a new set of data. To apply a model to a
new set of data, you specify an apply task. In the apply task you specify a build model
you trained and a set of accessors. Generally, the values are the same for the predictor and
sequence domains for a build task and its related apply task. You change the external or
anchor domain to apply the model to a different set of data. For example, you could
change the external domain to specify a different region or country. Or you could use the
anchor domain to specify a different year.
In the apply task, the target result data is not known, but is to be predicted by the model.
The apply task applies the model coefficients it generated to the new set of data and
generates a set of output data. The Data Mining Framework writes the result data back to
the Analytic Services cube. The apply task generates a result record that you can use to
query the result data.
Testing the Model
Data mining models are built using known data to train the algorithm so it can be applied
to a similar data set. To test a model, you create a test task. In the test task, you specify a
model you have trained and a set of accessors. In addition to the predictor and target
accessors, you specify test accessors that reference a known set of results.
The test task compares the results of the trained model to the set of known results you
specify. The test task determines if the results match within a specified range of expected
error. If the results do not match, you can do any of the following:
• Verify the homogeneity of the known data. If the structure of the known data does
not match the structure of the test data, the results will not match.
• Verify the integrity of the known data. Corrupt or incomplete data can cause the
test model to fail.
• Verify the integrity of the test input data.
• Consider changing the stringency of the settings. At very least, a less stringent
setting that returns a positive test gives you an idea of how closely the trained
model compares to known data.

See "Creating or Modifying a Test Task" in Essbase Administration Services Online Help
for information about creating a test task.
Viewing Data Mining Results
Data Mining Framework writes mining results back to the Analytic Services cube. Data
Mining Framework creates a result record, in XML format, that contains accessors that
specify the location of the result data in the cube.
You can view data mining results through the Data Mining node in Administration
Services or by using MaxL statements.
Preparing for Data Mining
The one essential prerequisite for performing data mining is that you understand your
data and the problem you are trying to solve. Data mining is a powerful tool and can yield
new insights. However, if you already have a strong hunch about your data, then data
mining can be particularly useful in confirming or denying your hunch, and giving you
some additional insights and directions to follow.
Before you mine an Analytic Services database, make sure that the database is loaded and
calculated.

Built-in Algorithms
Hyperion supplies the following basic algorithms:
• Regression. Identifies dependencies between a specific value and other values.
For example, multilinear regression can determine how the amount of money
spent on advertising and payroll affects sales values.
• Clustering. Arranges items into groups with similar patterns. You use the
clustering algorithm for unsupervised classification. The algorithm examines data
and determines itself how to split the data into groups, or clusters, based on
specific properties of the data. The input required to build the model consists of a
collection of vectors with numeric coordinates. The algorithm organizes these
vectors into clusters based on their proximity to each other. The basic assumption
is that the clusters are relatively smaller than the distance between them, and,
therefore, can be effectively represented by their respective centers. Hence the
model consists of coordinates of center vectors.
Sequential runs on the same training set may produce slightly different results due
to the stochastic nature of the method. You specify the number of clusters to
generate, but it is possible the algorithm will find fewer clusters than requested.
Clusters can provide useful information about market segmentation and can be
used with other predictive tools. For example, clusters can determine the kinds of
users most likely to respond to an advertising campaign and then target just those
users.
• Neural network. Generalizes and learns from data. For example, neural networks
can be used to predict financial results.
You can use the neural net algorithm for both prediction and classification. This
algorithm is much more powerful and flexible than linear regression. For
example, you can specify multiple targets as well multiple predictors.
On the other hand, the model generated by the neural net algorithm is not as easy
to interpret as that from linear regression.
 One use of neural nets is binary classification. A series of inputs (predictors)
produces a set of results (targets) normalized to values between zero and one. For
example, a set of behaviors results in values between 0 and 1, with 1 being risky
and 0 being risk free. Values in between require interpretation; for example, 0.4 is
the high end of safe and 0.6 is the low end of risky.
• Decision tree. Determines simple rules for making decisions. The algorithm
results are the answers to a series of yes and no questions. A yes answer leads to
one part of the tree and a no answer to another part of the tree. The end result is a
yes or no answer. Decision trees are used for classification and prediction. For
example, a decision tree can tell you to suggest ice cream to a particular customer
because that customer is more likely to buy ice cream with root beer.
Use the decision tree algorithm to organize a collection of data belonging to
several different classes or types. In the build phase, you specify a set of data
vectors and provide the class of each. In the apply phase, you provide a set of
previously unknown vectors and the algorithm deduces their classes from the
model.
The algorithm constructs a series of simple tests or predicates to create a tree
structure. To determine the class of a data vector, the algorithm takes the input
data and traverses the tree from the root to the leaves performing a test at each
branch.
• Association Rules. Discovers rules in a series of events. The typical application
for this algorithm is market basket analysis: people who buy particular items also
buy which other items. For example, the result of a market basket analysis might
be that men who buy beer also buy diapers.
You define support and confidence parameters for the algorithm. The algorithm
selects sufficiently frequent subsets selected from a predefined set of items. On
input it reads a sequence of item sets, and looks for an item set (or its subset),
whose frequency in the whole sequence is greater than support level. Such item
sets are broken into antecedent-consequent pairs, called rules. Rule confidence is
the ratio of its item set frequency to the antecedent frequency in all the item sets.
Rules with confidence greater than the given confidence level are added to the list
of "confident" rules.
Although the algorithm uses logical shortcuts during computations, thus avoiding
the need to consider all the combinations of the item sets, whose number can be
practically infinite, the speed with which the algorithm executes depends on the
number of attributes to consider and the frequency with which they occur.
• Naive Bayes. Predicts class membership probabilities. Naive Bayes is a light-
weight classification algorithm. It is fast, takes small memory and in a good
number of applications behaves quite satisfactory, so you can use it first before
going to the decision tree or fully fledged clustering schemes.
The algorithm treats all the attributes of the case vector as if they were
independent of each other. It uses a training sequence of vectors and the
theoretical definition of the conditional probability to calculate the probabilities or
likelihoods that an attribute with a certain value belongs to a case with a certain
class. The model stores these probabilities. In the apply mode the case attributes
 are used to calculate the likelihood of the case for each class. Then a class with
the maximal likelihood is assigned to the case.

Accessing Data Mining Functionality

Data Mining Framework is supported by the MaxL and Administration Services
interfaces.
MaxL provides a set of statements explicitly for data mining. With MaxL you can
perform all data mining functions, including creating, training, testing, and applying a
data mining model.
Sample model templates for each of the algorithms are available through the
Administration Services interface. A model template provides an outline of the accessors
needed for that algorithm that you can fill in. It also sets some parameters required by the
algorithm.
Administration Services enables you to manage data mining models, templates,
transformations, and results. It provides a mining wizard that steps you through the
process of creating and training a build model, and creating and applying apply and test
models. See "Mining an Analytic Services Database" in Essbase Administration Services
Online Help.

Creating New Algorithms

You can create your own algorithms using Java and register them with Data Mining
Framework. In order to be recognized by Data Mining Framework, an algorithm must
implement certain interfaces and have a specific signature. These requirements are
described in detail in the Algorithm Vendor's Guide shipped as part of the Data Mining
Framework SDK.
After a new algorithm is registered, it appears in the list of supplied algorithms and you
can use the new algorithm to create build and apply tasks. Data Mining Framework reads
the instructions for each parameter in the algorithm from the algorithm signature. The
instructions appear in the Build and Apply Wizards in the panels where the user sets the
algorithm parameters, just like the instructions for the supplied algorithms.

Copying Data Subsets

and Exporting Data to
Other Programs
You can move data between Analytic Services databases or to another
program by extracting an output file of the data you want to move. For
example, you can copy a subset of an Analytic Services database from
an Analytic Server to Personal Essbase.

In order to meet the import format specifications of most other

programs, use the Report Writer to create a text file.

This chapter contains information about the following topics:

• Copying a Database Subset

• Process for Creating a Database Subset
• Exporting Data Using Report Scripts
• Importing Data Into Other Databases
• Exporting Data

Copying a Database
Subset
You can install both the Analytic Server and client on a Windows NT or
Windows 2000 workstation using Personal Essbase. Personal Essbase
is a one-port license and has its own license number. For information
about installing and configuring Personal Essbase on a computer, see
the Essbase XTD Analytic Services Installation Guide.

Once you have installed Personal Essbase, you can copy the outline file
(dbname.otl) and a data subset from the Analytic Server and load
them into Personal Essbase. The Personal Essbase server does not
communicate with the OLAP Server.

Figure 208: Analytic Services and Personal Essbase Interaction

Note: Do not create more than one application and two databases
on the Personal Essbase server.

Process for Creating a

Database Subset
This section describes the process for copying a database subset to
Personal Essbase.

1. On the Personal Essbase server, create a new application and

database to contain the database subset.
See Creating a New Application and Database.
2. Copy the outline file (for example, source_dbname.otl) from
the source database to the new database on Personal
Essbase.
You may need to rename the outline file to match the name of
the Personal Essbase database (for example,
target_dbname.otl), overwriting the existing target database
outline file.
See Copying the Outline File from the Source Database.
3. Create an output file (for example, an plain text file)
containing the required data subset.
See Creating an Output File Containing the Required Data
Subset.
4. Load the output file into the new database that you have
created.
For instructions, see Loading the Output File Into the New
Database.

If required, you can repeat steps 3 and 4 to create an output file from
the database on the Personal Essbase server and load the data back
into the main Analytic Services database on a different computer.

The example in the following sections is based on the Sample Basic

database. The data subset in the example is the Actual, Measures data
for the West market. The example copies the data subset to a Personal
Essbase server and the West Westmkts database.

Creating a New Application and Database

Create a new application and database on the Personal Essbase server.
You will?copy the required subset of data into this new database. You
can give this application and database any name.

To create the application and database, see "Creating Applications

and Creating Databases" in the Essbase XTD Administration Services
Online Help.

Ensure that the new, empty database is not running.

To stop a database, see "Stopping Databases" in the Essbase XTD

Administration Services Online Help.

Copying the Outline File from the Source Database

Copy the outline file (.otl) of the source database to the new
database that you have created. In this example, you copy the
basic.otl outline file from the Sample Basic database and rename it
to wesmkts.otl on Personal Essbase.

How you copy the outline file depends on whether you can connect to
the source Analytic Services database from the Personal Essbase
computer.

• If you can connect, use any of the following methods to copy

the outline:

Tool Topic Location

Administration Copying Essbase XTD Administration

Services Outlines Services Online Help

MaxL create Technical Reference

database

ESSCMD COPYDB Technical Reference

 • If you cannot connect (for example, if the Personal Essbase
computer is a laptop computer that has no network
connection), use the operating system to copy the outline file.
a. Use the operating system to copy the source outline
file; for example, copy basic.otl to westmkts.otl.
b. Give the copied outline exactly the same name as the
new database.
c. Save the outline file in the
\ARBORPATH\App\appname\dbname directory on the
Personal Essbase computer, where ARBORPATH is the
directory in which you installed Analytic Services, 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
c:\essbase\app\west\westmkts\westmkts.otl on the
Personal Essbase computer. It is safe to overwrite the
existing, empty westmkts.otl file.

Note: Ensure that the new outline file overwrites the

existing, empty outline file, which Analytic Services
created automatically when you created the new
application and database.

d. Stop and then restart the new database.

See "Starting Databases and Stopping Databases" in the
Essbase XTD Administration Services Online Help.

You now have a copy of the database outline on the Personal Essbase
server.

Creating an Output File Containing the Required Data Subset

Create an output file that contains the required data subset. The
output file can be a text file or a spreadsheet file. Use either of the
following methods to create a data subset.

To create an output file using the Report Writer, see "Executing

Report Scripts" in the Essbase XTD Administration Services Online
Help.
To create an output file using the Retrieval Wizard, see the Essbase
XTD Spreadsheet Add-in User's Guide.
The following example shows how to create a subset of the Westmkts
database.

To create a text file that contains the required data subset, follow
these steps:
1. Select the source database. For example, select West
Westmkts.
See "Navigating and Selecting Objects" in the Essbase XTD
Administration Services Online Help.
o If you can connect to the main Analytic Services
database from the Personal Essbase computer, you can
select the source database from the Personal Essbase
computer.
o If you cannot connect, use a different computer from
the Personal Essbase computer to select the source
database.
2. Create a new report.
See "Creating Scripts" in the Essbase XTD Administration
Services Online Help.
3. Write a report script that selects the required data subset. For
fundamental information on writing report scripts, see
Understanding Report Script Basics.
For example, the following report script selects the Actual,
Measures data for the West market from Sample Basic:

Figure 209: Sample Basic Report Script

{TABDELIMT}
<QUOTEMBRNAMES
Actual
<IDESC West
<IDESC Measures
o Use TABDELIMIT to place tab stops between data,
instead of spaces to ensure that no member names or
data values are truncated.
o Use QUOTEMBRNAMES to place quotation marks (" ")
around member names that contain blank spaces.
 Analytic Services then recognizes the member names
when it loads the data.
4. Execute the report script.
See "Executing Report Scripts" in the Essbase XTD
Administration Services Online Help.
5. Save the report script with a .txt extension; for example,
westout.txt.

To load the data, the output file needs to be in the

\ARBORPATH\App\appname\dbname directory on the Personal
Essbase server, where ARBORPATH is the directory in which you
installed Analytic Services, and appname and dbname are the
new application and database directories that you have created.
If you are using the Personal Essbase computer, you can save
the output file directly into the
\ARBORPATH\app\appname\dbname directory, for example,
c:\essbase\app\west\westmkts\westout.txt.

If you are not using the Personal Essbase computer, save the
output file anywhere on the current computer. By default,
Analytic Services saves the file on the Analytic Services 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 the Personal
Essbase server. For example, use a disk to copy the file.
If you are not using the Personal Essbase computer, remember
to download and copy the file from the Analytic Server client
directory to the \ARBORPATH\app\appname\dbname directory on
the Personal Essbase server. For example, copy the output file to
c:\essbase\app\west\westmkts\westout.txt.

You are now ready to load the text file into the new database.

Loading the Output File Into the New Database

Load the output file into the new database on the Personal Essbase
computer.

To load a file into a database, see "Loading Data" in the Essbase XTD
Administration Services Online Help.
The following example illustrates how to load data into the Westmkts
database:

1. Select the new database. For example, select Westmkts.

2. Start the data load using the text file you have just created,
for example, westout.

Note: If westout is not displayed, check that you gave it a

.txt extension and placed it in the
\ARBORPATH\App\West\Westmkts directory. See Creating an
Output File Containing the Required Data Subset for
instructions for naming an output file.

For detailed information on loading data and any errors that may
occur, see Performing and Debugging Data Loads or Dimension Builds.

You can now view the data on the Personal Essbase computer. You
might need to recalculate the database subset. Because you are
viewing a subset of the database, a percentage of the data values will
be #MISSING.

If required, you can copy report scripts and other object files to the
Personal Essbase computer to use with the database subset you have
created.

Exporting Data Using

Report Scripts
You can use report scripts to export Analytic Services data to other
programs in text format. Report Writer enables you to create text files
that meet the import format specifications of most other programs.

For information about exporting databases using other methods, see

Exporting Data.

Before you can import data into some programs, you must separate,
or delimit, the data with specific characters.

If you plan to import Analytic Services data into a program that

requires special delimiters, use the MASK command.
Note: You cannot export data generated by Dynamic Calc
members. Because attributes are Dynamic Calc members, you
cannot export data generated by attributes.

When you export data to a program that uses a two-dimensional,

fixed-field format, you do not need to specify page or column
dimensions. To create a two-dimensional report, you can specify every
dimension as a row dimension. Use the ROWREPEAT command to add
the name of each member specified to each row (rather than the
default, nested style). The following script example and report
illustrate this situation for a five-dimensional database:

<ROW (Year, Measures, Product, Market, Scenario)
{ROWREPEAT}
<ICHILDREN Year
Sales
<ICHILDREN "400"
East
Budget
    ! 
 

This script produces the following report:

Qtr1          Sales        400­10       East 
Budget      900 
Qtr1          Sales        400­20       East 
Budget    1,100 
Qtr1          Sales        400­30       East 
Budget      800 
Qtr1          Sales          400        East 
Budget    2,800 
Qtr2          Sales        400­10       East 
Budget    1,100 
Qtr2          Sales        400­20       East 
Budget    1,200 
Qtr2          Sales        400­30       East 
Budget      900 
Qtr2          Sales          400        East 
Budget    3,200 
Qtr3          Sales        400­10       East 
Budget    1,200 
Qtr3          Sales        400­20       East 
Budget    1,100 
Qtr3          Sales        400­30       East 
Budget      900 
Qtr3          Sales          400        East 
Budget    3,200 
Qtr4          Sales        400­10       East 
Budget    1,000 
Qtr4          Sales        400­20       East 
Budget    1,200 
Qtr4          Sales        400­30       East 
Budget      600 
Qtr4          Sales          400        East 
Budget    2,800 
  Year        Sales        400­10       East 
Budget    4,200 
  Year        Sales        400­20       East 
Budget    4,600 
  Year        Sales        400­30       East 
Budget    3,200 
  Year        Sales          400        East 
Budget   12,000    
 

If you want to create a two-dimensional report that contains only

bottom-level (level 0) data, use CHILDREN or DIMBOTTOM to select
level 0 members.
 • To list only level 0 data for specific members, use the
CHILDREN command with the level 1 member as a parameter
above the data 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 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
     ! 
 

This script produces the following report:

Jan      Sales    100­10     East       Budget 
1,600.00 
Jan      Sales    100­20     East       Budget 
400.00 
Jan      Sales    100­30     East       Budget 
200.00 
Jan      Sales    200­10     East       Budget 
300.00 
Jan      Sales    200­20     East       Budget 
200.00 
Jan      Sales    200­30     East       Budget 
#Missing 
Jan      Sales    200­40     East       Budget 
700.00 
Jan      Sales    300­10     East       Budget 
#Missing 
Jan      Sales    300­20     East       Budget 
400.00 
Jan      Sales    300­30     East       Budget 
300.00 
Jan      Sales    400­10     East       Budget 
300.00 
Jan      Sales    400­20     East       Budget 
400.00 
Jan      Sales    400­30     East       Budget 
200.00 
Feb      Sales    100­10     East       Budget 
1,400.00 
Feb      Sales    100­20     East       Budget 
300.00 
Feb      Sales    100­30     East       Budget 
300.00 
Feb      Sales    200­10     East       Budget 
400.00 
Feb      Sales    200­20     East       Budget 
200.00 
Feb      Sales    200­30     East       Budget 
#Missing 
Feb      Sales    200­40     East       Budget 
700.00 
Feb      Sales    300­10     East       Budget 
#Missing 
Feb      Sales    300­20     East       Budget 
400.00 
Feb      Sales    300­30     East       Budget 
300.00 
Feb      Sales    400­10     East       Budget 
300.00 
Feb      Sales    400­20     East       Budget 
300.00 
Feb      Sales    400­30     East       Budget 
300.00 
Mar      Sales    100­10     East       Budget 
1,600.00 
Mar      Sales    100­20     East       Budget 
300.00 
Mar      Sales    100­30     East       Budget 
400.00 
Mar      Sales    200­10     East       Budget 
400.00 
Mar      Sales    200­20     East       Budget 
200.00 
Mar      Sales    200­30     East       Budget 
#Missing 
Mar      Sales    200­40     East       Budget 
600.00 
Mar      Sales    300­10     East       Budget 
#Missing 
Mar      Sales    300­20     East       Budget 
400.00 
Mar      Sales    300­30     East       Budget 
300.00 
Mar      Sales    400­10     East       Budget 
300.00 
Mar      Sales    400­20     East       Budget 
400.00 
Mar      Sales    400­30     East       Budget 
300.00    
 
For an additional example of formatting for data export, see Sample
12 on the Examples of Report Scripts page in the Report Writer
Commands section of the Technical Reference.

Importing Data Into

Other Databases
Before you import data into some programs, you must delimit the data
with specific characters. If you plan to import Analytic Services data
into a program that requires special delimiters, use the MASK
command.

Exporting Data
To export data from a database, use any of the following methods:

Tool Topic Location

Administration Exporting Essbase XTD Administration

Services Data Services Online Help

MaxL export Technical Reference

data

ESSCMD EXPORT Technical Reference

For more information see Export Backups.

Learning to Write Queries With MaxL Data

Manipulation Language
This chapter describes MaxL DML, the data manipulation language for Analytic
Services.
MaxL DML is based on MDX, a joint specification of the XML for Analysis founding
members. For more information about XML for Analysis, please visit
http://www.xmla.org. For more details on the syntax and grammar of MaxL DML, refer
to the MaxL DML section of the Technical Reference.
The goal of this chapter is to familiarize you with MaxL DML and develop simple
queries based on the Sample Basic database.
To complete the exercises in this chapter, use the MaxL Shell. Before continuing, please
start Analytic Services, and log in to the MaxL Shell. Additionally, be prepared to use a
text editor to create the sample queries as presented in this chapter.
This chapter contains the following sections:
1. Understanding Elements of a Query
1. Using Functions to Build Sets
1. Working with Levels and Generations
1. Using a Slicer Axis to Set Query Point-of-View
1. Common Relationship Functions
1. Performing Set Operations
1. Creating and Using Named Sets and Calculated Members
1. Using Iterative Functions
1. Suppressing Missing Data
1. Querying for Properties

Understanding Elements of a Query

In this section you will create a template to use as a basis for developing simple queries.
Most queries can be built upon the following grammatical framework:
SELECT
{}
ON COLUMNS
FROM Sample.Basic

SELECT in line 1 is the keyword that begins the main body of all MaxL DML
statements.
The curly braces {} in line 2 are a placeholder for a set. In the above query, the set is
empty, but the curly braces remain as a placeholder.
Exercise 1: Creating a Query Template

To complete this exercise,

• Create a folder to store sample queries which can be run against the Sample Basic
database. For example, create a folder called "queries" under the
Essbase\Apps\Sample\Basic directory of the Analytic Services installation.
• Using a text editor, type the following code into a blank file:
 SELECT
{}
ON COLUMNS
FROM Sample.Basic
4. Save the file as qry_blank.txt to your queries folder.

Introduction to Sets and Tuples

A set is an ordered collection of one or more tuples that have the same dimensionality
(see Rules for Specifying Sets for an explanation of dimensionality).
A tuple is a way to refer to a member or a member combination from any number of
dimensions. For example, in the Sample Basic database, Jan is a tuple, and so is (Jan,
Sales), and so is ([Jan],[Sales],[Cola],[Utah],[Actual]).
The member name can be specified in the following ways:
5. By specifying the actual name or the alias; for example, Cola, Actual, COGS, and
[100].
If the member name starts with number or contains spaces, it should be within
braces; for example, [100]. Braces are recommended for all member names, for
clarity and code readability.
For attribute members, the long name (qualified to uniquely identify the member)
should be used; for example, [Ounces_12] instead of just [12].
6. 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 is a recommended practice for all member names, as it
eliminates ambiguity and enables you to refer accurately to shared members.
Note: Use no more than one ancestor in the member name qualification. Analytic
Services returns an error if multiple ancestors are included. For example,
[Market].[New York] is a valid name for New York, and so is [East].[New
York]. However, [Market].[East].[New York] returns an error.
5. By specifying the name of a calculated member defined in the WITH section.
Recall that the curly braces {} in line 2 of your query template are a placeholder for a set.
In this exercise, we will add a set to the query and run it.
Exercise 2: Running Your First Query

To complete this exercise,

6. Open qry_blank.txt.
7. Recalling that a set can be as simple as one tuple, let us add Jan as a set to the
query template. We must retain the curly braces, because these are required for all
set specifications (except for sets that are produced by a function call).
Type Jan inside the curly braces in line 2, as shown:
SELECT
 {Jan}
ON COLUMNS
FROM Sample.Basic
8. Save the query as ex2.txt.
• Make sure that Analytic Services is started (the essbase.exe process is running).
• In order for Analytic Services to receive MaxL DML statements, you must pass
the statements to Analytic Services using the MaxL Shell. Start the MaxL Shell
and log in 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
the Enter key yet.
• Type a semicolon at the end, anywhere after Basic but before pressing the Enter
key. The semicolon is not part of MaxL DML syntax requirements, but it is
required by MaxL Shell to indicate the end of a statement that is ready to execute.
• Press the Enter key. You should see results similar to the following.
Jan
8024

Rules for Specifying Sets

As described in the previous section, a set is an ordered collection of one or more tuples.
For example, in the following query, {[100-10]} is a set consisting of one tuple.
SELECT
{[100-10]}
ON COLUMNS
FROM Sample.Basic

In the following query, {([100-10], [Actual])} is a also a set consisting of one tuple,
though in this case, the tuple is not a single member name. Rather, ([100-10], [Actual])
represents a tuple consisting of members from two different dimensions, Product and
Scenario.
SELECT
{[100-10], [Actual]}
ON COLUMNS
FROM Sample.Basic

When a set has more than one tuple, 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, the following set consists of two tuples of the same dimensionality.
{(West, Feb), (East, Mar)}

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

A set can also be a collection of sets, and it can also be empty (containing no tuples).
A set must be enclosed in curly brackets {} except in some cases where the set is
represented by a MaxL DML function which returns a set.

Introduction to Axis Specifications

An axis is a specification determining the layout of query results from a database. Axes
fit into DML queries as follows:
SELECT <axis> [, <axis>...]
FROM <database>

There must be at least one axis specified in any DML query.

Up to 64 axes may be specified, beginning with AXIS(0) and continuing with
AXIS(1)...AXIS(63). It is uncommon to use more than three axes. The order of axes is
not important. However, when a set of axes 0 through n are specified, no axis between 0
and n should be skipped. Additionally, a dimension cannot appear on more than one axis.
The first five axes have keyword aliases:

ON COLUMNS can be used in place of AXIS(0)

ON ROWS may replace AXIS(1)
ON PAGES may replace AXIS(2)
ON CHAPTERS may replace AXIS(3)
ON SECTIONS may replace AXIS(4)

For example, in the MaxL DML query

SELECT {Jan} ON COLUMNS FROM Sample.Basic

the axis specification is {Jan} ON COLUMNS.

Exercise 3: Running A Two-Axis Query

To complete this exercise,

• Open qry_blank.txt.
 • Add a placeholder for a second axis, by adding the text shown in bold:
SELECT
{}
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
Note: Remember to add the comma after ON COLUMNS.
• Save the new query template as qry_blank_2ax.txt.
• As the set specification for the column axis, enter the Product members 100-10
and 100-20. These member names contain special characters, so you will need to
use braces. For example, add the text shown in bold:
SELECT
{[100-10],[100-20]}
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
Note: In this chapter, the convention will be to enclose all member names in
braces, even if they do not contain special characters. This convention 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
• Save the query as ex3.txt.
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
You should see results similar to the following.

100-10 100-20
Qtr1 5096 1359
Qtr2 5892 1534
Qtr3 6583 1528
Qtr4 5206 1287
Exercise 4: Querying Multiple Dimensions on a Single Axis

To complete this exercise,

• Open qry_blank_2ax.txt.
• On the column axis, specify two tuples, each of which is a member combination
rather than a single member. You will need to enclose each tuple in parentheses,
because there is more than one member 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])}
ON COLUMNS,
{
([Qtr1],[Profit]), ([Qtr2],[Profit]),
([Qtr3],[Profit]), ([Qtr4],[Profit])
}
ON ROWS
FROM Sample.Basic
• Save the query as ex4.txt.
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
You should see results similar to the following.

100-10 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 MaxL DML query that determines which database
is being queried. The cube specification fits into a DML query as follows:
SELECT <axis> [, <axis>...]
FROM <database>

The <database> section follows the FROM keyword and should consist of delimited or
non delimited identifiers that specify an application name and a database name.
The first identifier should be an application name and the second one should be a
database name. For example, all of the following are valid cube specifications:
1. FROM Sample.Basic
1. FROM [Sample.Basic]
1. FROM [Sample].[Basic]
1. FROM'Sample'.'Basic'

Using Functions to Build Sets

As an alternative to creating sets member-by-member or tuple-by-tuple, you can use a
function that returns a set. MaxL DML includes several functions that return sets, and
also several functions that return other values. For a complete reference of functions, see
the MaxL DML section of the online Technical Reference.
Exercise 5: Using the MemberRange Function
The MemberRange function returns a range of members inclusive of and between two
specified members of the same generation. Its syntax is as follows:
MemberRange (member1, member2)

where the first argument you provide is the member that begins the range, and the second
argument is the member that ends the range.
Note: An alternate syntax for MemberRange is to use a colon between the two members,
instead of using the function name: member1 : member2.

To complete this exercise,

• Open qry_blank.txt.
• Delete the curly braces {}. Curly braces are not necessary 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 2:
Running Your First Query.
Qtr1, Qtr2, Qtr3, and Qtr4 are returned.
 • Use the MemberRange function to select the same member range, Qtr1 through
Qtr4.
SELECT
MemberRange([Qtr1],[Qtr4])
ON COLUMNS
FROM Sample.Basic
• Run the query. The same results should be returned.
• Save the query as ex5.txt.
Exercise 6: Using the CrossJoin Function
The CrossJoin function returns the cross product of two sets from different dimensions.
Its syntax is as follows:
CrossJoin(set,set)

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. This is useful for creating symmetric reports.

To complete this exercise,

• Open qry_blank_2ax.txt.
• Delete the curly braces {} from the columns axis, and replace them with
CrossJoin().
SELECT
CrossJoin ()
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
• Add two comma-separated pairs of curly braces to use 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, now 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
• Save the query as ex6.txt.
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
You should see results similar to the following.

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

When using CrossJoin, the order of arguments has an effect on the order of tuples in the
output.
Exercise 7: Using the Children Function
The Children function returns a set of all child members of the given member. Its syntax
is as follows:
Children (member)

Note: An alternate syntax for Children is to use it like an operator on the input member,
as follows: member.Children. We will use the operator syntax in this exercise.

To complete this exercise,

• Open ex6.txt. You will use the Children function to introduce a shortcut in the
first axis specification.
• In the second set of the column axis specification, replace
[East],[West],[South],[Central] with [Market].Children.
SELECT
CrossJoin ({[100-10]}, {[Market].Children})
ON COLUMNS,
CrossJoin (
 {[Sales],[COGS],[Margin %],[Profit %]}, {[Qtr1]}
)
ON ROWS
FROM Sample.Basic
• Save the query as ex7.txt.
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
• You should see the same results as were returned for Exercise 6: Using the
CrossJoin Function.

Working with Levels and Generations

In MaxL DML, the term layer is used to refer to generations and levels in an Analytic
Services hierarchy.
In Analytic Services, generation numbers begin counting with 1 at the dimension name;
higher generation numbers are those that are closest to leaf members in a hierarchy.
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 MaxL DML 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:
1. By generation or level name; for example, States or Regions.
1. The dimension name along with the generation or level name; for example,
Market.Regions and [Market].[States].
1. The Levels function with a dimension and a level number as input. For example,
[Year].Levels(0).
1. The Level function with a member as input. For example, [Qtr1].Level returns
the level of quarters in Sample Basic, which is level 1 of the Market dimension.
1. The Generations function with a dimension and a generation number as input. For
example, [Year].Generations (3).
1. The Generation function with a member as input. For example,
[Qtr1].Generation returns the generation of quarters in Sample Basic, which is
generation 2 of the Market dimension.
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 even though
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, then Qtr1 is one level higher than Qtr4,
but they are still in the same layer.
Exercise 8: Using the Members Function
The Members function can be used to return all members of a specified generation or
level. Its syntax when used with a layer argument is as follows:
Members (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.

To complete this exercise,

• Open qry_blank.txt.
• Delete the curly braces {}.
• Use the Members function and the Levels function to select all level-0 members
in the Market dimension of Sample Basic:
SELECT
Members(Market.levels(0))
ON COLUMNS
FROM Sample.Basic
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
All of the states in the Market dimension are returned.
• Save the query as ex8.txt.

Using a Slicer Axis to Set Query Point-of-

View
A slicer axis is a way of limiting a query to apply only to a specific area of the database.
The optional slicer, if used, must be in the WHERE section of a MaxL DML query.
Furthermore, the WHERE section must be the last component of the query, following the
cube specification (the FROM section):
SELECT {set}
ON axes
FROM database
WHERE slicer

The slicer axis is used to set the context of the query, and is usually the default context
for all the other axes.
For example, if you want 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, it is not necessary to include them
in the ON AXIS(n) set specifications.
Exercise 9: Limiting the Results with a Slicer Axis

To complete this exercise,

• Open ex6.txt.
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
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 only budgeted values.
SELECT
CrossJoin ({[100-10]}, {[East],[West],[South],[Central]})
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.
Note that the results are different.
• Save the query as ex9.txt.

Common Relationship Functions

The following relationship functions return sets based on member relationships in the
database outline:

Relationship
Description
Function
Children Returns the children of the input member.
Siblings Returns the siblings of the input member.
Descendants Returns the descendants of a member, with varying options.

The following functions are also relationship functions, but they return a single member
rather than a set:
Relationship
Description
Function
Ancestor Returns an ancestor at the specified layer.
Cousin Returns a child member at the same position as a member from
another ancestor.
Parent Returns the parent of the input member.
FirstChild Returns the first child of the input member.
LastChild Returns the last child of the input member.
FirstSibling Returns the first child of the input member's parent.
LastSibling Returns the last child of the input member's parent.

For examples using relationship functions, see the MaxL DML section of the Technical
Reference.

Performing Set Operations

The following set functions are characterized by the fact that they operate on input sets
without deriving further information from a database:

Pure Set
Description
Function
CrossJoin Returns a cross-section of two sets from different dimensions.
Distinct Deletes duplicate tuples from a set.
Except Returns a subset containing the differences between two sets.
Generate An iterative function. For each tuple in set1, returns set2.
Head Returns the first n members or tuples present in a set.
Intersect Returns the intersection of two input sets.
Subset Returns a subset from a set, in which the subset is a numerically
specified range of tuples.
Tail Returns the last n members or tuples present in a set.
Union Returns the union of two input sets.

Exercise 10: Using the Intersect Function

The Intersect function returns the intersection two input sets, optionally retaining
duplicates. Its syntax is as follows:
Intersect (set, set [,ALL])
You can use the Intersect function to compare sets by finding tuples that are present in
both sets.

To complete this exercise,

• Open qry_blank.txt.
• Delete the curly braces {} from the axis, and replace them with Intersect?().
SELECT
Intersect (

)
ON COLUMNS
FROM Sample.Basic
• Add two comma-separated pairs of curly braces to use as placeholders for the two
set arguments you will provide to the Intersect function:
SELECT
Intersect (
{ },
{ }
)
ON COLUMNS
FROM Sample.Basic
• Specify children of East as the first set argument.
SELECT
Intersect (
{ [East].children },
{ }
)
ON COLUMNS
FROM Sample.Basic
9. For the second set argument, specify all members of the Market dimension that
have a UDA of "Major Market."
Note: To learn more about how the UDA function works, see the Technical
Reference.
SELECT
Intersect (
{ [East].children },
{ UDA([Market], "Major Market") }
)
ON COLUMNS
FROM Sample.Basic
10. Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
The results will be all children of East that have a UDA of "Major Market":

New York Massachusetts Florida

8202 6712 5029

11. Save the query as ex10.txt.

Exercise 11: Using the Union Function
The Union function joins two input sets, optionally retaining duplicates. Its syntax is as
follows:
Union (set, set [,ALL])

You can use the Union function to lump two sets together into one set.

To complete this exercise,

12. Open ex10.txt.
13. Replace Intersect with Union, leaving everything else the same.
14. Paste the query into the MaxL Shell and run it.
If you compare the results with the results of the Intersect function in the previous
exercise, you will see that while Intersect returns a set 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.")
15. Save the query as ex11.txt.

For more examples using pure set-operative functions, see the Technical Reference.

Creating and Using Named Sets and

Calculated Members
Calculated members and named sets are logical entities in query which can be used
multiple times during the life of the query. Calculated members and named sets can save
time in lines of code written as well as in execution time.The optional WITH section at
the beginning of a MaxL DML query is where you define the calculated members and/or
named sets.

Calculated Members
A calculated member is a hypothetical member existing for the duration of the query
execution. Calculated members enable you to perform complex analysis without the
necessity of adding new members to the database outline. Essentially, calculated
members are a storage place for calculation results performed on real members.
You can give a calculated member any name you want, with the following guidelines:
 1. You must associate the calculated member with a dimension; for example, to
associated the member MyCalc with the Measures dimension, you would name it
[Measures].[MyCalc].
1. Do not use real member names to name calculated members; for example, do not
name a calculated member [Measures].[Sales], because Sales already exists in
the Measures dimension.
Exercise 12: Creating a Calculated Member
This exercise will include the Max function, a common function for calculations. The
Max function returns the maximum of values found in the tuples of a set. Its syntax is as
follows:
Max (set, numeric_value)

To complete this exercise,

16. Open qry_blank_2ax.txt.
• On the row axis set, specify the children of Product.
SELECT
{}
ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
• At the beginning of the query, add a placeholder for the calculated member
specification:
WITH MEMBER [].[]
AS ''
SELECT
{}
ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
• You will associate the calculated member with the Measures dimension, and name
it Max Qtr2 Sales. To do this, add this information to the calculated member
specification:
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, you will define the
logic for the calculated member named Max Qtr2 Sales. Use the Max function
with the first argument being the set to evaluate (Qtr2), and the second argument
being the measure to evaluate (Sales).
WITH MEMBER [Measures].[Max Qtr2 Sales]
AS '
Max ( {[Year].[Qtr2]}, [Measures].[Sales] )'SELECT
{}
 ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
• Now that the calculated member Max Qtr2 Sales is defined in the WITH section,
in order to use it in a query, you must include it on one of the axes in the SELECT
portion of the query. Select the pre-defined calculated member on the columns
axis:
WITH MEMBER [Measures].[Max Qtr2 Sales]
AS '
Max (
{[Year].[Qtr2]},
[Measures].[Sales]
)'
SELECT
{[Measures].[Max Qtr2 Sales]}
ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
• Paste the query into the MaxL Shell and run it, as described in Exercise 2:
Running Your First Query.
You should see results similar to the following.

Max Qtr2 Sales

100 27187
200 27401
300 25736
400 21355
Diet 26787

• Save the query as ex12.txt.

Named Sets
A named set is a set specification just like those you would define in the SELECT axes,
except you define the sets in the WITH section of the query, and associate them with a
name. This is useful because you can reference the set by name when building the
SELECT section of the query.
For example, a named set called 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

Using Iterative Functions

The following functions loop through sets of data and perform search conditions that you
specify, with results that you specify.

F
unct Description
ion
Filte Returns the subset of tuples in set for which the value of the search condition is
r TRUE.
IIF Performs a conditional test, and returns an appropriate numeric expression or set
depending on whether the test evaluates to TRUE or FALSE.
C Performs conditional tests and returns the results you specify.
ase
G An iterative function. For each tuple in set1, returns set2.
ener
ate

Filter Function Example

The following query returns all Market dimension members for which the expression
IsChild([Market].CurrentMember,[East]) returns TRUE; in other words, the query
returns all children of East.
SELECT
Filter([Market].Members,
IsChild([Market].CurrentMember,[East])
)
ON COLUMNS
FROM Sample.Basic

The Filter function in MaxL DML is comparable to the RESTRICT command in Report
Writer.
For more examples of Filter and other iterative functions, see the Technical Reference.

Suppressing Missing Data

When you are querying on sparse sections of a database, you can use the NON EMPTY
keywords at the beginning of an axis specification to suppress #Missing results.
The axis specification syntax including NON EMPTY is shown next:
<axis_specification> ::=
[NON EMPTY] <set> ON
COLUMNS | ROWS | PAGES | CHAPTERS |
 SECTIONS | AXIS (<unsigned_integer>)

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 the tuple to be eliminated.
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:

Qtr1
Actual #Missing #Missing #Missing #Missing #Missing

Querying for Properties

In MaxL DML, properties describe certain characteristics of data and metadata. MaxL
DML enables you to write queries that use properties to retrieve and analyze data.
Properties can be intrinsic or custom.
Intrinsic properties are defined for members in all dimensions. In MaxL DML, the
intrinsic member properties defined for all members in an Analytic Services database
outline are MEMBER_NAME, MEMBER_ALIAS, LEVEL_NUMBER, and
GEN_NUMBER.
MaxL DML supports two types of custom properties: attribute properties and UDA
properties. Attribute properties are defined by the attribute dimensions in an outline. In
the Sample Basic database, the Pkg Type attribute dimension describes the packaging
characteristics of members in the Product dimension. This information can be queried in
MaxL DML 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.

Querying for Member Properties

Properties can be used inside a MaxL DML query in two ways. In the first approach, 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 will return 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 just 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 both 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

In the second approach, properties can be used inside value expressions in a MaxL DML
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,
[Product].CurrentMember.Caffeinated and
[Product].CurrentMember.[Pkg Type] = "Can")
Dimension Properties
[Caffeinated], [Pkg Type] on columns
FROM Sample.Basic

The following query calculates the value [BudgetedExepenses] 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
WHERE ([Budget])
FROM Sample.Basic
The Value Type of Properties
The value of a MaxL DML property can be a numeric, Boolean, or string type.
MEMBER_NAME and MEMBER_ALIAS properties return string values.
LEVEL_NUMBER and GEN_NUMBER properties return numeric values.
The attribute properties return numeric, Boolean, or string values based on the attribute
dimension type. For example, in Sample Basic, the [Ounces] attribute property is a
numeric property. The [Pkg Type] attribute property is a string property. The
[Caffeinated] attribute property is a Boolean property.
Analytic Services allows attribute dimensions with date types. The date type properties
are treated as numeric properties in MaxL DML. When comparing these property values
with dates, you need to use the TODATE function to convert date strings to numeric
before comparison.
The following query returns all Product dimension members that have been introduced on
date 03/25/1996. Since the property [Intro Date] is a date type, the TODATE function
must be used to convert the date string "03-25-1996" to a number before comparing it.
SELECT
Filter ([Product].Members,
[Product].CurrentMember.[Intro Date] =
TODATE("mm-dd-yyyy","03-25-1996"))ON COLUMNS
FROM Sample.Basic

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

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

NULL Property Values

Not all members may have valid values for a given property name. For example, the
MEMBER_ALIAS property returns an alternate name for a given member as defined in
the outline; however, not all members may have aliases defined. In these cases A NULL
value is be returned for those members that do not have aliases.
In the following query,
SELECT
[Year].Members
DIMENSION PROPERTIES [MEMBER_ALIAS]
ON COLUMNS
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)
ON COLUMNS
FROM Sample.Basic

Managing Security for

Users and Applications
Analytic Services provides a comprehensive system for managing
access to applications, databases, and other objects. The Analytic
Services security system provides protection in addition to the security
available through your local area network.

This chapter contains the following sections:

• Understanding Security and Permissions

• Creating Users and Groups
• Granting Permissions to Users and Groups
• Managing Users and Groups
• Using the Hyperion Security Platform for External
Authentication
• Managing Global Security for Applications and Databases
• Managing User Activity on the Analytic Server
• Understanding the essbase.sec Security File and Backup

Understanding Security
and Permissions
The Analytic Services security system addresses a wide variety of
database security needs with a multi layered approach to enable you
to develop the best plan for your environment. Various levels of
permission can be granted to users and groups or defined at the
system, application, or database scope. You can apply security in the
following ways:

• Users and groups.

To grant permissions to individual users and groups of users.

When higher, these permissions take precedence over minimum
permissions defined for applications and databases. Ordinary
users have no inherent permissions. Permissions can be granted
to users and groups by editing the users and groups or by using
the grant statement in MaxL DDL (data-definition language). For
an explanation of the methods used to grant permissions, see
Granting Permissions to Users and Groups.
You can create users who log on using the parameters of an
external authentication repository instead of the Analytic
Services password. If you want users to use an outside
authentication repository such as LDAP, you must implement the
Hyperion security platform and create the Analytic Services
 users with a reference to the security platform. For information
about the security platform, see Using the Hyperion Security
Platform for External Authentication.
• Application and database settings.

To set common permissions for all users of an application or

database, you can set minimum permissions that all users can
have at each application or database scope. Users and groups
with lower permissions than the minimum gain access; users
and groups with higher granted permissions are not affected.
You can also temporarily disable different kinds of access using
application settings. For a detailed explanation of the use of
application and database settings, see Managing Global Security
for Applications and Databases.
• Server-wide settings.

Create and manage login restrictions for the entire Analytic

Server. View and terminate current sessions and requests
running on the entire Analytic Server or only on particular
applications and databases. For a comprehensive discussion of
how to manage the activities of users, see Managing User
Activity on the Analytic Server.
• Database filters.

Define database permissions that users and groups can have for
particular members, down to the individual data value (cell). To
learn more about how and why to use filters, see Controlling
Access to Database Cells.

Table?28 describes all security permissions and the tasks that can be
performed with those permissions.

Table 28: Description of Analytic Services Permissions ?

Affected
Permission Description
Scope

No Access or Entire system, No inherent access to any users,

None application, or groups, or data values, unless
database access is granted globally or by
means of a filter. No Access is
the default when creating an
ordinary user. Users with No
 Access permissions can change
their own passwords.

Read Database Ability to read data values.

Write Database Ability to read and update data

values.

MetaRead Database Ability to read metadata

(dimension and member names)
and update data for the
corresponding member
specification.

Execute Entire system, Ability to calculate, read, and

(or?Calculate) application, update data values for the
database, or assigned scope, using the
single assigned calculation.
calculation Supervisors, application
designers for the application,
and database designers for the
database can run calculations
without being granted execute
access.

Database Database Ability to modify outlines, create

Designer and assign filters, alter database
settings, and remove
locks/terminate sessions and
requests on the database.
A user with Database Designer
permission in one database does
not necessarily have that
permission in another.

Application Application Ability to create, delete, and

Designer modify databases within the
assigned application. Ability to
modify the application settings,
including minimum permissions,
remove locks on the application,
terminate sessions and requests
 on the application, and modify
any object within the
application. You cannot create or
delete an application unless you
also have been granted the
system-level Create/Delete
Applications permission.
A user with Application Designer
permission in one application
does not necessarily have that
permission in another.

Filter Access Database Ability to access specific data

and metadata according to the
restrictions of a filter assigned to
the user or group. The filter
definition specifies, for subsets
of a database, whether Read,
Write, No Access, or MetaRead is
allowed for each subset. A user
or group can be granted only
one filter per database. Filters
can be used in conjunction with
other permissions. For a
comprehensive discussion of
filters, see Controlling Access to
Database Cells.

Create/delete Entire system Ability to create and delete

applications applications and databases
within those applications, and
control permissions, locks, and
resources for applications
created. Includes designer
permissions for the applications
and databases created by this
user.

Create/Delete Entire system Ability to create, delete, edit, or

Users, Groups rename all users and groups
having equal or lesser
permissions than their own.
Supervisor Entire system Full access to the entire system
and all users and groups.

Creating Users and

Groups
When you create a user or a group in Analytic Services, you define a
security profile. The security profile is where you define the extent of
the permissions that users and groups have in dealing with each other
and in accessing applications and databases. This section contains the
following sections:

• Creating Users
• Creating Groups

If you are using Administration Services, you also need to create users
on the Administration Server. For more information, see About
Administration Services Users.

Creating Users
To create a user means to define the user name, password, and
permission. You can also specify group membership for the user, and
you can specify that the user is required to change the password at
the next login attempt, or that the user name is disabled, preventing
the user from logging on.

User names can contain only characters defined within the code page
referenced by the ESSLANG variable and they cannot contain the
backslash (\) character. User names must begin with a letter or a
number.

To create a new user, use either of the following methods:

Tool Topic Location

Administration Creating Users on Essbase XTD

Services Analytic Servers Administration Services
Online Help

MaxL create user Technical Reference

For example, to create a user named admin and grant that user
Supervisor permissions, use the following MaxL statements:

create user admin identified by 'password';
grant supervisor to admin; 
 

Creating Groups
A group is a collection of users who share the same minimum access
permissions. Placing users in groups can save you the time of
assigning identical permissions to users again and again.

Note: A member of a group may have permissions beyond those

assigned to the group, if permissions are also assigned individually
to that user.

The process for creating, editing, or copying groups is the same as

that for users, except that there are no group passwords. You define
group names and permissions just as you do for users.

Note: A group name may not contain a backslash (\).

When you create a new user, you can assign the user to a group.
Similarly, when you create a new group, you can assign users to the
group. You must define a password for each user; there are no
passwords for groups.

To create groups, use either of the following methods:

Tool Topic Location

Administration Creating Groups Essbase XTD

Services on Analytic Administration Services
Servers Online Help
MaxL create group Technical Reference

Granting Permissions to
Users and Groups
You can define security permissions for individual users and groups.
Groups are collections of users that share the same minimum
permissions. Users inherit all permissions of the group and can
additionally have access to permissions that exceed those of the
group.

Permissions can be granted to users and groups in the following ways:

• Specifying a user or group type upon creation or by editing

the user or group. This method specifies system-level
permissions that span all applications and databases. For
descriptions of the types of users and groups, see Assigning
User and Group Types.
• Granting permission to access applications or databases. For
an explanation of how to grant resource-specific permissions,
see Granting Application and Database Access to Users and
Groups.
• Granting designer permissions to users or groups. For an
explanation of situations requiring the granting of designer
permissions, see Granting Designer Permissions to Users and
Groups.

Assigning User and Group Types

One way to assign permissions to users and groups is to define user
and group types when you create or edit (modify the permissions of)
the users and groups.

In Administration Services, users and groups can be created in

different ways to specify their system-level permissions. These
methods are represented in Administration Services Console as user
types. In MaxL, user types do not exist; instead you grant the
permissions after the user is created.

In Administration Services, users can be created with the following

types:

• Supervisor.

A user or group with Supervisor permission has full access to the

entire system and all users and groups. The user who installs
Analytic Services on the server is designated the System
Supervisor for that server. Analytic Services requires that at least
one user on each server has Supervisor permission. Therefore,
you cannot delete or downgrade the permission of the last
supervisor on the server.
• User.

Users or groups with ordinary permission have no inherent

access to any users, groups, or resources. This type of user is
the default user.
• Users with Create/Delete Users, Groups permission.

This type of user or group can create, delete, edit, or rename

users and groups with equal or lower permissions only.
• Users with Create/Delete Applications permission.

This type of user or group can create and delete applications and
control permissions and resources applicable to those
applications or databases they created.
Users with Create/Delete Applications permission cannot create
or delete users, but they can manage application-level
permission for those applications that they have created. For a
comprehensive discussion of application-level permission, see
Managing Global Security for Applications and Databases.

For instructions about creating users and groups, see Creating Users
and Creating Groups.

Granting Application and Database Access to Users and Groups

If you need to grant resource-specific permissions to users and groups
that are not implied in any user types, you can grant the specific
application or database permissions to users when creating or editing
them in Administration Services. Using MaxL, you grant the
permissions after the user is created by using the grant statement.

You can grant or modify user and group application and database
permissions from an edit-user standpoint or from an application or
database security perspective. The results are the same.

Note: If a user has insufficient permission to access the data in a

database, the value does not show up in queries, or shows up as
#NOACCESS.

There is no need to grant permissions to users or groups that are

already Supervisors-they have full permissions to all resources on the
Analytic Server. For a given database, users or groups can also be
granted any of the following permissions:

Table 29: Permissions Available at the Database Scope ?

Database
Description
permission

None Indicates no access to any object or data value in

a database.

Filter Access Indicates that data and metadata access is

restricted to those filters assigned to the user.
(For a comprehensive discussion of filters, see
Controlling Access to Database Cells.)
The Filter check box grants a filter object to a
user or group. A user or group can be granted
only one filter per database. Selecting this option
or any other option except None enables the
selection of a filter object from the list box.

Read Only Indicates read permission, that is, the ability to

retrieve all data values. Report scripts can also
be run.

Read / Write Indicates that all data values can be retrieved

and updated (but not calculated). The user can
run, but cannot modify, Analytic Services objects.

MetaRead Indicates that metadata (dimension and member

 names) can be retrieved and updated for the
corresponding member specification.

Calculate Indicates that all data values can be retrieved,

updated, and calculated with the default
calculation or any calculation for which the user
has been granted permission to execute.

Database Indicates that all data values can be retrieved,

Designer updated, and calculated. In addition, all
database-related files can be modified.

To grant or modify application or database permissions for a user or

group, use either of the following methods:

Tool Topic Location

Administration Managing User/Group Essbase XTD

Services Permissions for Administration
Applications and Services Online Help
Databases

MaxL To grant permissions: Technical Reference

grant
To change the user type
or group: alter user

Granting Designer Permissions to Users and Groups

Users and groups can be granted Application Designer or Database
Designer permission for particular applications or databases. These
permissions are useful for assigning administrative permissions to
users who need to be in charge of particular applications or databases,
but who only need ordinary user permissions for other purposes.

You need to grant database access to other users if any of the

following conditions apply:
 • The users have not been granted sufficient user permission to
access databases.
• The database in question does not allow users sufficient
access through its minimum-permission settings.
• The users do not have sufficient access granted to them
through filters.

For references to methods you can use to grant Designer permissions

to a user or group, see Granting Application and Database Access to
Users and Groups.

Managing Users and

Groups
To help manage security between users and groups, the following
user-management tasks are available at varying degrees to users with
different permissions:

• Viewing Users and Groups

• Editing Users
• Editing Groups
• Copying an Existing Security Profile
• Deleting Users and Groups
• Renaming Users and Groups

Viewing Users and Groups

To view users and groups, use either of the following methods:

Tool Topic Location

Administration Enterprise View > Essbase XTD

Services Security node Administration Services
Online Help

MaxL display user or Technical Reference

display group
Editing Users
To edit a user means to modify the security profile established when
the user was created. For information about changing user passwords,
see Propagating Password Changes.

To change a password or other user properties, use either of the

following methods:

Tool Topic Location

Administration Editing User Essbase XTD Administration

Services Properties Services Online Help

MaxL alter user Technical Reference

Editing Groups
To edit a group means to modify the security profile established when
the group was created.

To view or change group membership, use either of the following

methods:

Tool Topic Location

Administration Editing Group Essbase XTD

Services Properties Administration Services
Online Help

MaxL display user in Technical Reference

group or alter
group

Copying an Existing Security Profile

An easy way to create a new user with the same permissions as
another user is to copy the security profile of an existing user. The new
user is assigned the same user type, group membership, and
application/database access as the original user.

You can also create new groups by copying the security profile of an
existing group. The new group is assigned the same group type, user
membership, and application access as the original group.

You can copy users and groups on the same Analytic Server or from
one Analytic Server to another, according to your permissions. You can
also migrate users and groups across servers along with an
application. For more information, see "Copying Users" in Essbase XTD
Administration Services Online Help.

To copy a user or group means to duplicate the security profile of an

existing user or group, and to give it a new name. It is helpful to copy
users and groups because it saves you the time of reassigning
permissions in cases where you want them to be identical.

Note: Copying removes any security permissions the creator does

not have from the copy. For example, a user with Create/Delete
Users permission cannot create a new supervisor by copying the
profile of an existing supervisor.

To create a new user or group by copying the security profile of an

existing user or group, use either of the following methods:

Tool Topic Location

Administration Copying Users Essbase XTD

Services and Copying Administration Services
Groups Online Help

MaxL create user or Technical Reference

create group

Deleting Users and Groups

To delete users and groups, use either of the following methods:

Tool Topic Location

Administration Deleting Users Essbase XTD

Services and Deleting Administration Services
Groups Online Help

MaxL drop user or Technical Reference

drop group

Renaming Users and Groups

To rename users and groups, use either of the following methods:

Note: A group name may not contain a backslash (\).

Tool Topic Location

Administration Renaming Users Essbase XTD

Services and Renaming Administration Services
Groups Online Help

MaxL alter user and Technical Reference

alter group

Using the Hyperion

Security Platform for
External Authentication
External authentication means that the user login information needed
by Analytic Services is maintained in a central authentication directory,
such as Lightweight Directory Access Protocol (LDAP) Directory,
Microsoft Active Directory, or Windows NT LAN Manager.

An authentication directory is a centralized store of user information

such as login names and passwords, and other corporate information.
The repository functions like a telephone directory. The authentication
directory probably contains much more than user names and
passwords; for example, it may include e-mail addresses, employee
IDs, job titles, access rights, and telephone numbers. It may also
contain objects other than users; for example, it may contain
information about corporate locations or other entities.

To use the security platform for Analytic Services, your organization

must already have an authentication directory that contains centralized
user information. Additionally, you must employ an XML-based security
configuration file to specify correct information pertaining to your
corporate authentication directory.

The following types of authentication repositories are supported by the

security platform:

• Windows NT LAN Manager (NTLM)

• Lightweight Directory Access Protocol (LDAP)
• Microsoft Active Directory server (MSAD)
To learn more about implementing the Hyperion security platform,
1. Check the Essbase XTD Analytic Services Installation Guide to
make sure your required platform and authentication
directory are supported.
2. See the help topic Configuration for External Authentication,
which is in the Security Platform Reference section of the
Technical Reference. Follow the configuration guidelines in
that document.
3. To manage external authentication of users using
Administration Services, see also "Managing External
Authentication" in the Essbase XTD Administration Services
Online Help.

Note: Prior to this release, Analytic Services provided support for

external authentication using built-in modules supplied as
parameters to the AUTHENTICATIONMODULE essbase.cfg setting.
Those modules did not include the ability to share the same
external authentication scheme with other Hyperion software
applications or to enable single sign-on to Analytic Services from
other Hyperion applications. Support for the earlier modules is
unaffected by the new security platform. Implementation of the
security platform is optional, but Hyperion strongly encourages
using the security-platform authentication over the built-in modules
authentication.
Managing Global
Security for
Applications and
Databases
In addition to granting permissions to users and groups, you can
change security settings for entire applications and databases and
their related files and resources. Application and database security
settings enable you to manage connections and create a lowest-
common-security profile for the applications and databases.

This section contains the following sections:

• Defining Application Settings

• Setting General Application Connection Options
• Setting Application and Database Minimum Permissions

Defining Application Settings

You can define permissions and other security settings that apply to
applications by changing the application settings. The settings you
define for the application affect all users, unless they have higher
permissions granted to them at the user level.

Only users with Supervisor permission (or Application Designer

permission for the application) can change application settings.

To define settings for an application, see Setting General Application

Connection Options or Setting Application and Database Minimum
Permissions.

Setting General Application Connection Options

The following application settings are available:

• A brief description of the application

 • A time-out setting for locks
• Options that control application loading, command processing,
connections, updates, and security
• Settings that define the minimum permissions to the
application. For detailed information about minimum
permissions, see Setting Application and Database Minimum
Permissions.

The following settings are available for various levels of application

security. For information about how and when disabling these settings
takes effect, see Table?30.

• Allow Application to Start

When disabled, prevents all users from starting the application

directly or as a result of operations that would start the
application; for example, attempting to change application
settings or create databases. By default, the application is not
prevented from starting.
• Start When Analytic Server Starts

When enabled, the application starts automatically whenever the

Analytic Server starts. By default, the application does not start
when the Analytic Server starts.
• Allow commands

When unchecked, prevents any user from making any requests

to databases in the application, including non-data-specific
requests such as viewing database information or changing
database settings. Supervisors are affected by this setting as a
safety mechanism to prevent accidental changes to databases
during maintenance operations. By default, commands are
enabled.
• Allow connects

When unchecked, prevents any user with a permission lower

than Application Designer for that application from making
connections to databases within the application which require the
databases to be started. By default, connections to databases
are allowed.
• Allow updates
 When unchecked, prevents modification to on-disk database
structures; for example, any operation that might have an effect
on the data, including updating the data or making outline
modifications. Supervisors are affected by this setting as a safety
mechanism to prevent accidental updates to databases during
maintenance operations. By default, updates are enabled.
• Enable Security

When unchecked, Analytic Services ignores all security settings

in the application and treats all users as Application Designers.
By default, security is enabled.

Table?30 describes when the implementation of protective application

settings takes effect, how long the effects last, and which users are
affected.

Table 30: Scope and Persistence of Application-Protection

Settings ?
Which Users
When the
Disabled are Affected Persistence of
Disabled
Application by the the Disabled
Setting Takes
Setting Disabled Setting
Effect
Setting

Allow Users Immediately All users, The application

to Start including cannot be started
Application supervisors. until an
administrator re-
Users
enables the start-
currently
up setting.
logged on
and users
who log on
later.

Start Immediately All users. The application

Application will not start with
When Analytic Server
Analytic unless an
Server Starts administrator
enables it.

Allow Immediately All users, Commands are

Commands including disabled until any
supervisors. of the following
actions occur:
Users
currently 1. The
logged on administr
and users ator who
who log on disabled
later. comman
ds logs
off.
2. The
applicatio
n is
stopped
and
restarted
.
3. An
administr
ator re-
enables
comman
ds.

Allow Immediately, Users with Connections are

Connects except that permissions disabled until any
disabling lower than of the following
connections Application actions occurs:
does not affect Designer. 1. The
users who Users applicatio
already have currently n is
databases logged on stopped
loaded. and users and
who log on restarted
later. .
2. An
Users already
administr
connected to
ator re-
the database
enables
are not
connectio
affected.
ns.

Allow Immediately All users, Updates are

Updates including disabled until any
supervisors. of the following
occurs actions:
Users
currently 1. The
logged on administr
and users ator who
who log on disabled
later. updates
logs off.
2. The
applicatio
n is
stopped
and
restarted
.
3. An
administr
ator re-
enables
updates.

Enable Immediately All users, Security is

Security including disabled until a
supervisors. user re-enables
security.
Users
currently
logged on
and users
who log on
later.

To change application settings, use either of the following methods:

Tool Topic Location

Administration Setting Essbase XTD

Services Application Administration Services
Properties Online Help

MaxL alter application Technical Reference

Note: If performing maintenance operations that require disabling
commands or updates, make those maintenance operations within
the same session as the one in which the setting was disabled.

If you disable commands or updates in a MaxL script, be aware that

the end of the script constitutes the end of the session. Calling a
nested MaxL or ESSCMD script from the current MaxL script also
constitutes the end of the session.

If you disable commands or updates in an ESSCMD script, the end of

the script constitutes the end of the session, but calling a nested
ESSCMD script from the current ESSCMD script does not constitute the
end of the session.

Caution: Never power down or reboot your client computer when

you have cleared any of the Allow settings. Always log off from the
server correctly. Improper shutdown can cause the application to
become inaccessible, which requires a full application shutdown and
restart.

If a power failure or system problem causes Analytic Server to

improperly disconnect from the Analytic Services client, and the
application is no longer accessible, you must shut down and restart the
application. For instructions about starting and stopping Analytic
Services, see Starting and Stopping Analytic Server.

Setting Application and Database Minimum Permissions

Minimum database access permissions can be specified at the
application or database level. If specified for an application, minimum
database access permissions apply to all databases within the
application. When a minimum permission is set to a level higher than
None (or No Access) for an application or database, all users inherit
that permission to access the database or databases.

For example, if an application has Read permission assigned as the

minimum database access level, all users can read any database
within that application, even if their individual permissions do not
include Read access. Similarly, if a database has a minimum
permission setting of None, only users with sufficient granted
permissions (granted directly, or implied by filters or group
membership) can gain access to the database.

Users with Supervisor, Application Designer, or Database Designer

permissions are not affected by minimum-permission settings applied
to applications or databases they own. Supervisors have full access to
all resources, and Application Designers and Database Designers have
full access for their applications or databases.

Users and groups with lower than the minimum permissions inherit at
least the minimum permissions for any applications or databases.

Changes to the minimum permission settings for applications affect

only those databases that have lower minimums. In other words,
settings defined at a lower level take precedence over more global
settings.

The permissions listed in Table?31 are available as minimum settings

for applications and databases. Databases of an application inherit the
permissions of the applications whenever the application permissions
are set higher than those of the database.

Table 31: Minimum Permission Settings Available for

Applications and Databases ?
Permission Description

None Specifies that no minimum permission has

been defined for the application or database.
None is the default global permission for newly
created applications and databases.

Read Specifies Read-Only access to any object or

data value in the application or database. Users
can view files, retrieve data values, and run
report scripts. Read access does not permit
data-value updates, calculations, or outline
modifications.

Write Specifies Update access to any data value in

the databases of the application, or in one
database. Users can view Analytic Services
files, retrieve and update data values, and run
 report scripts. Write access does not permit
calculations or outline modifications.

MetaRead Gives Read access to the specified members,

but hides data for their ancestors, and hides
data and metadata for their siblings.

Calculate Specifies Calculate and update access to any

data value in the databases of the application,
or in one database. Users can view files,
retrieve, update, and perform calculations
based on data values, and run report and
calculations scripts. Calculate access does not
permit outline modifications.

Designer (for Specifies Calculate and update access to any

Application or data value in the databases of the application,
Database) or in one database. In addition, Designer
permission enables users to view and modify
the outline and files, retrieve, update, and
perform calculations based on data values, and
run report and calculation scripts.

Note: Although any user with a minimum of Read access to a

database can start the database, only a Supervisor, a user with
Application Designer permission for the application, or a user with
Database Designer permission for the database can stop the
database.

To set minimum permissions for an application, see "Setting

Minimum Permissions for Applications" in the Essbase XTD
Administration Services Online Help, or see alter application in the
MaxL DDL section of the Technical Reference.
To set minimum permissions for a database, see "Setting Minimum
Permissions for Databases" in the Essbase XTD Administration
Services Online Help, or see alter database in the MaxL DDL section
of the Technical Reference.
Managing User Activity
on the Analytic Server
AnalyticThis section explains how to manage the activities of users
connected to the Analytic Server. The security concepts explained in
this section are session and request management, lock management,
connection management, and password and user name management.
For information about managing security for partitioned databases, see
Designing Partitioned Applications.

Disconnecting Users and Terminating Requests

The security system lets you disconnect a user from the Analytic
Server when you want to perform maintenance tasks.

To view sessions, disconnect sessions, or terminate requests, you must

have Supervisor permission or Application Designer permission for the
specified application. You can view or terminate only sessions or
requests for users with permissions equal to or lesser than your own.

A session is the time between login and logout for a user connected to
Analytic Server at the system, application, or database scope. A user
can have more than one session open at any given time. For example,
a user may be logged on to different databases. If you have the
appropriate permissions, you can log off sessions based on any criteria
you choose; for example, an administrator can log off a user from all
databases or from a particular database.

A request is a query sent to Analytic Server by a user or by another

process; for example, a default calculation of a database, or a
restructuring of the database outline. Each session can process only
one request at a time.

Note: You cannot terminate a restructure process. If you attempt

to terminate it, a "command not accepted" error is returned, and
the restructure process is not terminated.

To disconnect a session or request using Administration Services, see

"Disconnecting User Sessions and Requests" in the Essbase XTD
Administration Services Online Help.
 To disconnect a session or request using MaxL, see the following
table:

Table 32: Session and Request Termination Options ?

Selections in Administration
MaxL equivalents
Services

log selected user only alter system logout 

off ?? session
? <session­id>;

log all users on selected alter system logout 

off server session all;

log all users on selected alter system logout 

off application session on
application <app­
name>;

log all users on selected alter system logout 

off database session on
database <dbs­name>;

log all instances on selected alter system logout 

off of user server session by user
<user­name>;

log all instances on selected alter system logout 

off of user application session by
user <user­name> on 
application
<app­name>;

log all instances on selected alter system logout 

off of user database session on
database <dbs­name>;

kill selected only alter system kill 

request request
<session­id>;

kill all requests on selected alter system kill 

 server request all;

kill all requests on selected alter system kill 

application request on
application <app­
name>;

kill all requests on selected alter system kill 

database request on
database <dbs­name>;

kill all requests on selected alter system kill 

from user server request by
user <user­name>;

kill all requests on selected alter system kill 

from user application request by
user <user­name> on 
application <app­
name>;

kill all requests on selected alter system kill 

from user database request by user
<user­name> on database 
<dbs­name>;

Managing User Locks

Spreadsheet Add-in users can interactively send data from a
spreadsheet to the server. To maintain data integrity while providing
multiple-user concurrent access, Analytic Services enables users to
lock data for the purpose of updating it. Users who want to update
data must first lock the records to prevent other users from trying to
change the same data.

Occasionally, you may need to force an unlock operation. For example,

if you attempt to calculate a database that has active locks, the
calculation must wait when it encounters a lock. By clearing the locks,
you allow the calculation to resume.

Only Supervisors can view users holding locks and remove their locks.
 To view or remove locks, use either of the following methods:

Tool Topic Location

Administration Viewing Data Locks Essbase XTD

Services and Unlocking Data Administration Services
Online Help

MaxL drop lock Technical Reference

Managing Passwords and User Names

You can place limitations on the number of login attempts users are
allowed, on the number of days users may not use Analytic Services
before becoming disabled from the server, and on the number of days
users are allowed to have the same passwords. Only system
administrators (users with Supervisor permission) can access these
settings. The limitations apply to all users on the server, and are
effective immediately upon clicking OK.

Note: If you later change the number of unsuccessful login

attempts allowed, Analytic Services resets the count for all users.
For example, if the setting was 15 and you changed it to 20, all
users are allowed 20 new attempts. If you changed the setting to 2,
a user who had already exceeded that number when the setting
was 15 is not locked out. The count returns to 0 for each change in
settings.

To place limitations on users, use either of the following methods:

Tool Topic Location

Administration Managing Password Essbase XTD

Services Longevity Administration Services
Disconnecting Users Online Help
Automatically

MaxL alter user Technical Reference

Propagating Password Changes
You can change a user's password and then propagate the new
password to other Analytic Server instances. You need Create/Delete
Users and Groups permissions for both the source and the target
servers. The user whose password you are changing must exist on the
target servers, and the target servers must be running.

If you use Administration Services to change a user's Analytic Server

password, and if the user is also an Administration Services user, the
user's Administration Services user properties are updated
automatically. The user's Administration Services password is not
affected. For more information, see "Changing Passwords for Analytic
Server Users" in Essbase XTD Administration Services Online Help.

To change a user's Analytic Server password and propagate the new

password to other Analytic Server instances, see "Propagating
Passwords Across Servers" in Essbase XTD Administration Services
Online Help.

Viewing and Activating Disabled User Names

You can prevent a user from logging in to an Analytic Server by
disabling the user name at the Analytic Server level. A username is
disabled automatically when the user exceeds limitations specified, or
a username can be disabled manually for individual users. For more
information about limitations that cause user names to become
disabled automatically, see Managing Passwords and User Names.

Administration Services provides a Disabled Usernames window that

enables you to view and activate all usernames that have been
disabled for an Analytic Server. Only a user with at least Create/Delete
User permission can view or reactivate disabled user names.

To disable a user name manually, use either of the following

methods:

Tool Topic Location

Administration Disabling Essbase XTD Administration

Services Usernames Services Online Help

MaxL alter user Technical Reference

 To view or activate currently disabled user names, use either of the
following methods:

Tool Topic Location

Administration Viewing or Essbase XTD

Services Activating Disabled Administration Services
Usernames Online Help

MaxL alter user Technical Reference

Understanding the
essbase.sec Security
File and Backup
All information about users, groups, passwords, permissions, filters,
applications, databases, and their corresponding directories is stored in
the essbase.sec file in the ARBORPATH\bin directory. Each time you
successfully start the Analytic Server, a backup copy of the security file
is created as essbase.bak. You can also update the security backup
file more often by using one of the following methods:

• Manually compare the security backup file to the security file

at any time and update the backup file if necessary
• Specify an interval at which Analytic Services automatically
compares the security backup file to the security file and
updates the backup file if necessary
To update the security backup file, use either of the following
methods:

Tool Topic Location

Administration Updating the Essbase XTD

Services Security Backup Administration Services
 File Online Help

MaxL alter system Technical Reference

sync security
backup

If you attempt to start Analytic Server and cannot get a password

prompt or your password is rejected, no .bak file is created. You can
restore from the last successful startup by copying essbase.bak to
essbase.sec. Both files are in the essbase\bin directory where you
installed Analytic Services.

Caution: If Analytic Services stops running unexpectedly for any

reason, such as a freeze or crash, or as the result of terminating a
process, do not restart Analytic Server until you copy the backup
file (essbase.bak) to the security file (essbase.sec). If you do not
perform the copy first, when Analytic Server starts, Analytic
Services notes that essbase.sec is corrupt, creates an empty
security file, and copies it to essbase.bak, thus destroying the
backup of your security information.

Controlling Access to Database Cells

When the security levels defined for applications, databases, users, and groups are not
enough, Analytic Services security filters give you control over security at the most
detailed level. Filters let you control access to individual data within a database, by
defining what kind of access is allowed to which parts of the database, and to whom these
settings apply.
If you have Supervisor permissions, you can define and assign any filters to any users or
groups. Filters do not affect you.
If you have Create/Delete Applications permissions, you can assign and define filters for
applications you created.
If you have Application Designer or Database Designer permissions, you can define and
assign filters within your applications or databases. For descriptions of permission levels,
see Understanding Security and Permissions.
This chapter contains the following sections:
1. Understanding How Filters Define Permissions
1. Creating Filters
1. Managing Filters
1. Assigning Filters
Understanding How Filters Define
Permissions
Filters control security access to data values, or cells. You create filters to accommodate
security needs for specific parts of a database. When you define a filter, you are
designating a set of restrictions upon particular database cells. When you save the filter,
you give it a unique name to distinguish it from other filters, and the server stores it in
ESSBASE.SEC, the security file. You can then assign the filters to any users or groups on
the server.
For example, a manager designs a filter named RED, and associates it with a particular
database to limit access to cells containing profit information. The filter is assigned to a
visiting group called REVIEWERS, so that they can read, but cannot alter, most of the
database, while they have no access at all to Profit data values.
Filters are composed of 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 an individual cell.

Access
Description
Level
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.
MetaRe Metadata (dimension and member names) can be retrieved and updated for
ad 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, then try to retrieve the
substitution variable, an unknown member error occurs, but the value of the substitution
variable gets displayed. This is expected behavior.

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 getting this error, be sure to
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.
Note: Data values not covered by filter definitions default first to the access levels
defined for users and second to the global database access levels. For a detailed
discussion of user access levels, see Granting Permissions to Users and Groups. For a
detailed discussion of global access levels, see Managing Global Security for
Applications and Databases.
Calculation access is controlled by minimum global permissions or by permissions
granted to users and groups. Users who have calculate access to the database are not
blocked by filters-they can affect all data elements that the execution of their calculations
would update.

Creating Filters
You can create a filter for each set of access restrictions you need to place on database
values. There is no need to create separate filters for users with the same access needs-
once 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:
1. Connect to the server and select the database associated with the filter.
1. Check the naming rules for filters in Limits.

To create a filter, use either of the following

methods:
Tool Topic Location
Administration Creating or Editing Essbase XTD Administration Services
Services Filters Online Help
MaxL create filter Technical Reference

Filtering Members Versus Filtering Member Combinations

Figure?210 illustrate different ways to control access to database cells. Data can be
protected by filtering entire members, or by filtering member combinations.
1. Filtering members separately affects whole regions of data for those members.
1. Filtering member combinations affects data at the member intersections.
Figure 210: How Filters Affect Data AND/OR Relationships

Note: Filtering on member combinations (AND relationship) does not apply to

MetaRead. MetaRead filters each member separately (OR relationship).
Filtering Members Separately
To filter all the data for one or more members, define access for each member on its own
row in Filter Editor. Filter definitions on separate rows of a filter are treated with an OR
relationship.
For example, assume that user KSmith is assigned this filter:
Figure 211: Filter Blocking Access to Sales or Jan

Access Member Specification

None Sales
None Jan
The filter blocks access to all members Sales or Jan in the Sample Basic database.
The next time user KSmith connects to Sample Basic, she has no access to data values for
the member Sales or for the member Jan. Her spreadsheet view of the profit margin for
Qtr1 looks like this view:
Figure 212: Results of Filter Blocking Access to Sales or Jan

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.
Filtering Member Combinations
To filter data for member combinations, define the access for each member combination
using a single row in Filter Editor. A filter definition using one row and a comma is
treated as an AND relationship.
For example, assume that user RChinn is assigned this filter:
Figure 213: Filter Blocking Access to Sales for Jan

Access Member Specification

None Sales, Jan

The filter blocks only the intersection of the members Sales and Jan in the Sample Basic
database.
The next time user RChinn connects to Sample Basic, she has no access to the data value
at the intersection of members Sales and Jan. Her spreadsheet view of the profit margin
for Qtr1 looks like this view:
Figure 214: Results of Filter Blocking Access to Sales, Jan
Sales data for January is blocked from view. However, Sales data for other months is
available, and non-Sales data for January is available.

Filtering with Attribute Functions

You can use filters to restrict access to data for base members sharing a particular
attribute. To filter data for members with particular attributes defined in an attribute
dimension, use the attribute member in combination with the @ATTRIBUTE function or
the @WITHATTR function.
Note: @ATTRIBUTE and @WITHATTR are member set functions. Most member set
functions can be used in filter definitions.
For example, assume that user PJones is assigned this filter:
Figure 215: Filter Blocking Access to Members with Attribute "Caffeinated_False"

Access Member Specification

None @ATTRIBUTE("Caffeinated_False")

The filter blocks access to data for caffeine-free products. "Caffeinated_False" is a

Boolean-type attribute member in Sample Basic, in the Pkg_Type attribute dimension.
This attribute is associated with members in the Product base dimension.
The next time user PJones connects to Sample Basic, he has no access to the data values
for any base dimension members associated with Caffeinated_False. His spreadsheet
view of first-quarter cola sales in California looks like this view:
Figure 216: Results of Filter Blocking Access to Caffeine-free Products
Sales data for Caffeine Free Cola is blocked from view. Note that Caffeine Free Cola is a
base member, and Caffeinated_False is an associated member of the attribute dimension
Caffeinated (not shown in the above spreadsheet view).

Managing Filters
You can perform the following actions on filters:
1. Viewing Filters
1. Editing Filters
1. Copying Filters
1. Renaming Filters
1. Deleting Filters

Viewing Filters

To view a list of filters, use any of the

following methods:
Tool Topic Location
Administration Creating or Editing Essbase XTD Administration Services
Services Filters Online Help
MaxL display filter Technical Reference
ESSCMD LISTFILTERS Technical Reference

Editing Filters

To edit an existing filter, use either of the

following methods:

Tool Topic Location

Administration Creating or Editing Essbase XTD Administration Services
Services Filters Online Help
MaxL create filter Technical Reference

Copying Filters
You can copy filters to applications and databases on any Analytic Server, according to
your permissions. You can also copy filters across servers as part of application
migration.
 To copy an existing filter, use any of the
following methods:

Tool Topic Location

Administration Copying Essbase XTD Administration Services Online
Services Filters Help
MaxL create filter Technical Reference
ESSCMD COPYFILTER Technical Reference

Renaming Filters

To rename an existing filter, use any of the

following methods:
Tool Topic Location
Administration Renaming Essbase XTD Administration Services Online
Services Filters Help
MaxL create filter Technical Reference
ESSCMD RENAMEFILT Technical Reference
ER

Deleting Filters

To delete an existing filter, use either of the

following methods:

Tool Topic Location

Administration Deleting Filters Essbase XTD Administration Services Online
Services Help
MaxL drop filter Technical Reference

Assigning Filters
Once you have defined filters, you can assign them to users or groups. Assigning filters to
users and groups 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 role of Supervisor. Only one filter per database
can be assigned to a user or group.

To assign a filter to a user or group, see

"Assigning Filters" in the Essbase XTD Administration Services Online Help.

Overlapping Filter Definitions

If a filter contains rows that have overlapping member specifications, the inherited access
is set by the following rules, which are listed in order of precedence:
• A filter that defines a more detailed dimension combination list takes precedence
over a filter with less detail.
• If the preceding rule does not resolve the overlap conflict, the highest access level
among overlapping filter rows is applied.

For example, this filter contains overlap conflicts:

Table 33: Filter with Overlap Conflicts

Access Member Specification

Write Actual
None Actual
Read Actual, @IDESCENDANTS("New York")

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 data points, such as Budget, are accessible according to the minimum database
permissions.
Note: If you have Write access, you also have Read access.
Changes to members in the database outline are not reflected automatically in filters. You
must manually update member references that change.

Overlapping Access Definitions

When the access rights of user and group definitions overlap, the following rules, listed in
order of precedence, apply:
7. An access level that defines a more detailed dimension combination list takes
precedence over a level with less detail.
8. If the preceding rule does not resolve the overlap conflict, the highest access level
is applied.
Example 1:
User Fred is defined with the following database access:
FINPLAN R
CAPPLAN W
PRODPLAN N
He is assigned to Group Marketing which has the following database access:
FINPLAN N
CAPPLAN N
PRODPLAN W
His effective rights are set as follows:
FINPLAN R
CAPPLAN W
PRODPLAN W
Example 2:
User Mary is defined with the following database access:
FINPLAN R
PRODPLAN N
She is assigned to Group Marketing which has the following database?access:
FINPLAN N
PRODPLAN W
Her effective rights are set as follows:
FINPLAN R
PRODPLAN W

In addition, Mary uses the filter object RED (for the database FINPLAN). The filter has
two filter rows:
Figure 217: RED Filter for Database FINPLAN

Access Member Specification

Read Actual
Write Budget, @IDESCENDANTS("New York")

The Group Marketing also uses a filter object BLUE (for the database FINPLAN). The
filter has two filter rows:
Figure 218: BLUE Filter for Database FINPLAN

Access Member Specification

Read Actual, Sales
Write Budget, Sales

Mary's effective rights from the overlapping filters, and the permissions assigned to her
and her group, are as follows:

R Entire Finplan database

WFor all Budget data in the New York branch
WFor data values that relate to Budget and Sales

For additional sample scenarios, see Security Examples.

Security Examples
This chapter describes some sample security problems and solutions, which are based on
the Sample application. These examples use security procedures described in Managing
Security for Users and Applications.
1. Security Problem 1
1. Security Problem 2
1. Security Problem 3
1. Security Problem 4
1. Security Problem 5

Security Problem 1
Three employees need to use Analytic Services-Sue Smith, Bill Brown, and Jane Jones.
Each?requires update access to all databases in the Sample application.
Solution:
Because the users need update access to only one application, they do not need to have
Supervisor permission. Because the users do not need to create or delete applications,
users, or groups, they do not need to be defined as special types of users with
Create/Delete permission. All these users need is Application Designer permission for the
Sample application.
The supervisor should perform the following tasks:
• Set up the users with Administration Services.
For more information, see Essbase XTD Administration Services Installation
Guide.
• Create Sue, Bill, and Jane as ordinary users with Application Designer
permission.
 If Sue, Bill, and Jane are created without Application Designer permission, assign
Application Designer permission to the three users.
For more information, see Creating Users or Granting Designer Permissions to
Users and Groups.

Security Problem 2
Three employees need to use Analytic Services-Sue Smith, Bill Brown, and Jane Jones.
Sue and Bill require full access to all databases in the Sample application. Jane requires
full calculate access to all databases in the Sample application, but she does not need to
define or maintain database definitions.
Solution:
The supervisor should perform the following tasks:
9. Set up the users with Administration Services.
See the Essbase XTD Administration Services Installation Guide.
10. Create Sue and Bill as ordinary users with Application Designer permission.
If Sue and Bill are created without Application Designer permission, assign
Application Designer permission to the two users.
For more information, see Creating Users or Granting Designer Permissions to
Users and Groups.
11. Define global Calculate access for the Sample application as the Minimum
Database Access setting to give all additional users Calculate access to all
databases for the application.
See "Setting Minimum Permissions for Applications" in the Essbase XTD
Administration Services Online Help.
9. Create Jane as an ordinary user with no additional permissions. She inherits the
Calculate access from the application global setting.
For more information, see Creating Users.

Security Problem 3
Three employees need to use Analytic Services-Sue Smith, Bill Brown, and Jane Jones.
Sue and Bill require full access to all databases in the Sample application. Jane requires
full update and calculate access to all databases within the Sample application, but she
will not define or maintain the database definitions. Additional users will be added, all of
whom will require Read access to all databases.
Solution:
Because the current users have different needs for application and database access, define
their user permissions individually. Then, to save time assigning individual Read
permissions for future users, make Read the global setting for the application. (It does not
matter in what order you assign the user permissions and the global access.)
The supervisor should perform the following tasks:
10. Set up the users with Administration Services.
For more information, see Essbase XTD Administration Services Installation
Guide.
11. Create or edit Sue and Bill as ordinary users with Application Designer
permissions.
 For more information, see Creating Users and Granting Designer Permissions to
Users and Groups.
12. Create Jane as an ordinary user, and give her Calculate permission for the Sample
application.
For more information, see Creating Users and Granting Application and Database
Access to Users and Groups.
• Define global Read access for the Sample application as the Minimum Database
Access setting to give all additional users Read access to all databases in the
Sample application.
See "Setting Minimum Permissions for Databases" in the Essbase XTD
Administration Services Online Help.

Security Problem 4
Three employees need to use Analytic Services-Sue Smith, Bill Brown, and Jane Jones.
Sue requires full access only to the Sample application; Jane requires calculate access to
all members of the Basic database; Bill requires Read access to all members. No other
users should have access to the databases.
Furthermore, Jane and Bill need to run report scripts that are defined by Sue.
Solution:
Because the different users have different needs for application and database access,
define the global access setting as None, and assign the user permissions individually.
The supervisor should perform the following tasks:
• Set up the users with Administration Services. (Because Jane and Bill need to run
the report scripts, they must use Administration Services.)
For more information, see Essbase XTD Administration Services Installation
Guide.
• Create Sue as an ordinary user, but grant her Application Designer permission for
the Sample application.
For more information, see Creating Users and Granting Designer Permissions to
Users and Groups.
• Create Jane as an ordinary user, and give her Calculate permission for the Sample
application.
For more information, see Creating Users and Granting Application and Database
Access to Users and Groups.
• Create Bill as an ordinary user and give him Read permission on the Sample
application.
For more information, see Creating Users and Granting Application and Database
Access to Users and Groups.

Security Problem 5
The Supervisor, Sue Smith, needs to perform some maintenance on the Sample
application. She must make changes to the database outline and reload actual data. While
she changes the application, Sue must prevent other users from connecting to the
application.
Solution:
Sue should perform the following tasks:
 • Disable the Allow Commands setting to prevent other users from connecting to
the application, and also prevent connected users from performing any further
operations.
For more information, see "Clearing Applications of User Activity" in the Essbase
XTD Administration Services Online Help.
• Check to see if any users have active locks.
If any users have active locks, Sue's calculation or data load command might halt,
waiting for access to the locked records. Sue can allow the users to complete their
updates or clear their locks.
For more information, see "Viewing Data Locks" in the Essbase XTD
Administration Services Online Help.
• After confirming that no users have active locks, proceed to perform maintenance
on the application.

The Analytic Services Implementation of

Unicode
Through its Unicode implementation, Essbase XTD Analytic Services enables employees
of global businesses to view, in their own languages, company information stored in their
Analytic Services databases.
The following sections of this chapter provide a brief overview of Unicode and describe
the Analytic Services implementation of the Unicode standard.
1. About Unicode
1. About the Analytic Services Implementation of Unicode
1. When to Use Unicode-Mode Applications

About Unicode
Sharing data across national and language boundaries is a challenge for multi-national
businesses Traditionally, each computer stores and renders text based on its locale
specification. A locale identifies the local language and cultural conventions such as the
formatting of currency and dates, sort order of the data, and the character set encoding to
be used on the computer. The encoding of a character set refers to the specific set of bit
combinations used to store the character text as data, as defined by a code page or an
encoding format. In Analytic Services, 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 that has a
different locale.
The Unicode Standard was developed to enable 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 a single encoding form, Unicode enables users to correctly
view character data created on computers with different locale settings.
Analytic Services conforms to version 2.1 of the Unicode Standard and uses the popular
UTF-8 encoding form within the Unicode Standard.
For additional information about the Unicode Standard, see www.unicode.org.

About the Analytic Services

Implementation of Unicode
By providing Unicode support, Analytic Services helps solve the multi-national business
problem of sharing data across the enterprise. Analytic Services users whose computers
are set up in different languages can work with the same database. For example, using
alias tables in their respective languages, users in Taiwan can view database reports
displaying Chinese characters while users in France can view the same reports in French
characters.
The following topics describe the fundamental characteristics of the Analytic Services
implementation of Unicode.
1. Locales and Analytic Services
1. Unicode and Non-Unicode Application Modes
1. Unicode and Non-Unicode Server Modes
1. Increased Name Lengths
1. Compatibility Between Different Versions of Clients and Analytic Servers
1. Unicode-Enabled Administration Tools
1. Unicode-Enabled C API
1. Spreadsheet Retrieval
1. Sample_U Basic
1. Support of Different Locales on Clients and Analytic Servers
1. Identification of Text Encoding and Locale
1. Export File Encoding

User-defined character sets (UDC) are not supported and the Chinese National Standard
GB 18030-2000 is not supported. Unicode-mode applications do not support the hybrid
analysis, query logging, triggers, and data mining features. Unicode-mode applications
also do not support the MaxL Data Manipulation Language (MaxL DML). SQL Interface
does not work with Unicode-mode applications.

Locales and Analytic Services

Analytic Services uses the ESSLANG variable to define the locale of a computer. You
must specify the ESSLANG variable for each Analytic Server installation and you should
set ESSLANG to the same locale as is defined for the operating system of the computer.
Defining an ESSLANG variable on client computers is optional. If ESSLANG is defined
on a client, Analytic Services uses the ESSLANG value as the computer locale. If no
ESSLANG value is specified on a client, Analytic Services uses the locale specified for
the operating system. For more information about defining the ESSLANG variable, see
the Essbase XTD Analytic Services Installation Guide.
Note: As described in About Unicode, a locale specification contains several kinds of
information about the language and culture the computer supports. Analytic Services uses
only the code-page portion of locale specifications. The cultural conventions and sort-
order portions are not used.

Unicode and Non-Unicode Application

Modes
Applications are designated as Unicode-mode applications or non-Unicode-mode
applications.
Unicode-mode applications support multiple character sets. When it works with Unicode-
mode applications, Analytic Services uses the UTF-8 encoding form to interpret and store
character text. Character-based objects in Unicode-mode applications, such as member
and alias names, can include characters from different languages.
Since Unicode-mode applications accept input files in non-Unicode-encoding as well as
in UTF-8, Analytic Services relies on locale indicators and user prompting to read or
write non-Unicode-encoded files. For a basic description of encoding, see About
Unicode.
Clients working with Unicode-mode applications can have different locales than Analytic
Server. For example, client computers with Japanese locales and client computers with
German locales can work with the same Unicode-mode application on an Analytic Server
that has a Spanish locale.
For Unicode-mode applications, the limits of most object names are longer than those
names in non-Unicode-mode applications and the limits are calculated based on
characters rather than bytes. See Increased Name Lengths.
Non-Unicode-mode applications support one character set that is defined by the a locale
value which must be the same for Analytic Server and all non-Unicode clients that work
with the non-Unicode-mode applications. By default, Analytic Services creates
applications in non-Unicode mode.
You can define an application as Unicode-mode when you create the application or you
can migrate a non-Unicode-mode application to Unicode mode in a separate step. For
information about these processes, see Creating a New Unicode-Mode Application.
Note: You cannot convert a Unicode-mode application to non-Unicode mode.
Both Unicode-mode and non-Unicode-mode applications can reside on the same Analytic
Server. For information to help determine the type of application to use for particular
situations, see When to Use Unicode-Mode Applications.

Unicode and Non-Unicode Server Modes

Analytic Server must have permission to create Unicode-mode applications or to migrate
existing applications to Unicode mode. When this permission is enabled, Analytic Server
is said to be in Unicode mode. For information about granting or revoking this
permission, see Setting Analytic Server to Unicode Mode.
Whether or not Analytic Server is in Unicode mode affects only the creation and
migration of applications. Regardless of the Analytic Server Unicode setting, you can
work with both Unicode mode and non-Unicode-mode applications.
Increased Name Lengths
For Unicode-mode applications, the maximum number of characters allowed in strings
such as application, database, and member names is greater than the maximum allowed
for non-Unicode-mode applications.
For non-Unicode-mode applications, the maximum length of most object names is
calculated in bytes. For Unicode-mode applications, the maximum length of most object
names is calculated based on the number of characters, regardless of how many bytes
each character requires. Not limiting by bytes is advantageous for applications using
multi-byte character sets, such as Chinese and Japanese. For example, member names in
Unicode-mode applications can contain 80 characters, even if they are multi-byte
characters. For a list of object-name size maximums for Unicode-mode and non-Unicode-
mode applications, See Limits.
Note: The increase in size limits does not affect the size of the outline, but may affect the
size of user-written client programs.
To take advantage of the 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.)

Compatibility Between Different Versions

of Clients and Analytic Servers
To support customers over the time they upgrade their computers to a Unicode-enabled
release of Analytic Services, Analytic Services enables different versions of clients and
servers to communicate with each other. Table?34, "Compatibility Between Different
Versions of Clients and Analytic Server", summarizes the compatibility between different
versions of Analytic Services clients and servers. The following terminology is used in
this table:
1. Not Unicode-enabled server: Analytic Server installed using a release of Analytic
Services prior to Release 7.0
1. Unicode-enabled server: Analytic Server installed using Analytic Services Release
7.0 or later
1. Not Unicode-enabled client: a client program built using include files and DLLs
from non-Unicode releases of Analytic Services. Clients that are not Unicode
enabled deal entirely in short strings and non-Unicode encoding. Application
Manager is an example of a client that is not Unicode-enabled.
1. Unicode-enabled client: a client program built using include files and DLLs from
Unicode-enabled releases of Analytic Services. Unicode-enabled client programs
can be in Unicode mode or non-Unicode mode.
1. Unicode-mode client program: a Unicode-enabled client program that
communicates with the Analytic Services API in Unicode encoding, using
long strings (See the API Reference for details.) Administration Services is
an example of a Unicode-mode client.
1. Non-Unicode-mode client program: a Unicode-enabled client program
that communicates with the Analytic Services API in short strings (See the
 API Reference for details.) Excel Spreadsheet Add-in is an example of a
non-Unicode-mode client.
1. Unicode-mode application: an Analytic Services application that uses UTF-8
encoding to display and store character text
1. Non-Unicode-mode application: an Analytic Services application that displays
and stores character text based on the locale common to clients and server

Table 34: Compatibility Between Different Versions of Clients and Analytic Server ?

Unicode-
enabled
Unicode-enabled
Analytic
Not Unicode-enabled Analytic Server, Non-
Server,
Analytic Server Unicode-mode
Unicode-
application
mode
application
Not Unicode-enabled Yes Yes No
Client
For example:
Application Manager
and pre-7.0
Spreadsheet Add-in
Non-Unicode-mode Yes, except for clients Yes Yes, but
Client?Program on a using the grid API except no
Unicode-enabled changes can
Client be made to
For example: outlines.
The MaxL Shell and No outline
Excel?Spreadsheet synchronizati
Add-in packaged on
with Unicode-
enabled Analytic
Services
Unicode-mode Yes, except for clients Yes. Yes
Client Program on a using the grid API Synchronization
Unicode-enabled Synchronization of of?outlines not
Client outlines not supported supported for
Examples: for applications applications encoded to
Administration encoded to locales with locales with multi-byte
Services and multi-byte characters characters
Spreadsheet Services
Unicode-Enabled Administration Tools
Hyperion provides Administration Services and MaxL to administer Unicode-mode
applications. The main administration activities include, in addition to the normal
Analytic Services administration activities, changing the Unicode-related mode of the
server to enable or disable creation of Unicode-mode applications, creation of Unicode-
mode applications, migration of non-Unicode-mode applications to Unicode mode, and
viewing the Unicode-related status of servers and applications.
Administration Services is a Unicode-mode client. You can use Administration Services
with both Unicode and non-Unicode-mode applications. See Working With Unicode-
Mode Applications for information about Unicode-related administration tasks.
To administer non-Unicode-mode applications, you can use Application Manager from
previous Analytic Services releases that were not Unicode enabled.

Unicode-Enabled C API
Without recompilation, existing custom-written client programs are not Unicode-enabled.
These programs use short strings and short buffers. You can continue to use these
programs with non-Unicode-mode applications.
Depending on how they are written, in order to provide restricted access to Unicode-
mode applications, existing custom-written client programs can be recompiled in a
Unicode-enabled release of Analytic Services. Simply recompiled, these programs work
with long buffers but short strings.
For complete access to Unicode-mode and non-Unicode-mode applications, existing
custom-written applications need to be modified using the new Analytic Services API
functions for Unicode. Rewritten and compiled clients work with long buffers and long
strings for full Unicode support. For information about updating custom-written client
programs, see the API Reference.

Spreadsheet Retrieval
The Analytic Services Spreadsheet Add-in for Excel supports viewing data in both
Unicode and non-Unicode-mode applications. Older versions of the spreadsheet add-ins
for Excel and Lotus?1-2-3 can view data only in non-Unicode-mode applications. The
older versions of these add-ins are available only through older releases of Analytic
Services that are not Unicode-enabled.
You can use Spreadsheet Services to view data in both Unicode-mode applications and
non-Unicode-mode applications. To run Spreadsheet Services you must also run
Deployment Services. See the installation guides for each of these products for
preparation and installation information.

Sample_U Basic
To demonstrate Unicode-mode applications, the sample applications include a Unicode-
mode application and database: Sample_U Basic. Member names in Sample_U Basic are
in English.
Sample_U Basic includes four non-English alias tables and their import files:
nameschn.alt (Chinese), namesger.alt (German), namesjpn (Japanese), and namesrsn
(Russian).

Support of Different Locales on Clients

and Analytic Servers
For each Analytic Server installation you must define the ESSLANG variable. For details
about defining ESSLANG, see the Essbase XTD Analytic Services Installation Guide.
The ESSLANG variable is a locale definition, including a code page specification that
maps bit combinations to characters. For example, to support American English you can
set ESSLANG to English_UnitedStates.US-ASCII@Binary.
Clients also use locales. ESSLANG variables are optional for clients. If ESSLANG is not
defined on a client, the locale specified for the operating system is used.
The client and server locale values must be the same for non-Unicode-mode clients and
applications. For Unicode-mode applications, the client and server locale values can be
different.

Identification of Text Encoding and Locale

Analytic Services uses the ESSLANG locale to convert non-Unicode-encoded files that
you choose to use with Unicode-mode applications.
Analytic Services also supports use of non-Unicode encoded files with Unicode-mode
applications. In order to identify what type of encoding a file is, Analytic Services looks
for UTF-8 signatures or locale indicators to identify the encoding. If a file contains
neither of these encoding identifiers and the file is not on the server, Administration
Services prompts the user for the locale of the file. For details about locale indicators, see
Encoding Indicators.
The Analytic Services Unicode File Utility program (ESSUTF8) includes options to
insert UTF-8 signatures or locale headers in text files or you can insert them manually.
For general information about this utility, see Analytic Services Unicode File Utility. For
description and syntax of this utility, see the Technical Reference.

Export File Encoding

All export files from Unicode-mode applications are encoded in UTF-8 and include the
UTF-8 signature.

When to Use Unicode-Mode Applications

Consider working with Unicode-mode applications only if you have any of the following
situations:
 1. 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 could view, in their
own languages, information about a common product set.
1. You need to handle object names longer than non-Unicode-mode applications
support. For example, application and database names need to be larger than eight
characters or, if you are working with a multi-byte character set, you need to
handle more characters in object names.
1. For a translated, multi-byte Analytic Services implementation, you have
experienced what is called the "round-trip" problem. The round-trip problem can
occur in communications between multi-byte operating systems and application
programs where two different bit values can map to the same character. As Java
applications, Administration Services and Deployment Services always work in
Unicode. No encoding conversions occur when these clients work with Unicode-
mode applications and UTF-8-encoded text files; hence no round-trip conversion
errors.

When deciding on using Unicode-mode applications, you should also consider the
following points:
1. Using non-Unicode text files with Unicode-mode applications requires an
understanding of locales and care in managing to them. To prevent errors that
could cause database corruption, using UTF-8-encoded files is recommended. For
details, see Managing File Encoding.
1. To work with Unicode-mode applications, custom client applications that were
written to support non-Unicode-mode applications must be built to use the longer
string lengths used by Unicode-mode applications. This may be a simple re-build
or may involve re-programming, depending on the design of the applications.
Also, depending on how they are coded, the new client applications may require
more memory. For details, see the API Reference.

Working With Unicode-Mode

Applications
In most cases, administering Unicode-mode applications is no different than working
with non-Unicode-mode applications. Working in multiple character sets in Unicode
mode can require additional attention in the following areas:
1. Setting Up a Computer for Unicode Support
1. Naming Applications and Databases
1. Defining Password Security
1. Managing Unicode-Mode Applications
1. Using Control Characters in Report Scripts
1. Working With Partitions
1. Working With Logs
1. Managing File Encoding
Setting Up a Computer for Unicode
Support
Consider setting up the following non-Hyperion tools for working with UTF-8 encoded
text on computers that will manage Unicode-mode applications.
1. To enable viewing UTF-8 encoded text that contains non-ASCII characters, install
a font that supports UTF-8 encoding.
1. To support manual editing of data sources or other text files, you may want to
install a Unicode editor that enables viewing, creating, and modifying UTF-8
encoded files and includes the UTF-8 signature. A Unicode editor is not
necessary. Analytic Services provides the Analytic Services Unicode File Utility
which converts text files to UTF-8 encoding.

UTF-8 fonts and Unicode editors are made available by several software manufacturers.

Defining Password Security

Analytic Services security is defined at the Analytic Server level. To create passwords,
use characters encoded according to the code page specified in the ESSLANG value on
Analytic Server. In a multiple character set environment, consider using the characters in
the standard ASCII character set, in the range from 0 through 127. Standard ASCII
includes the upper and lower case letters in the standard English alphabet and the
numerals 0 through 9. These characters are common to all code pages as well as UTF-8.

Naming Applications and Databases

When you name applications and databases, be sure to use characters supported by the
locale of the computer.

Managing Unicode-Mode Applications

Working with Unicode-mode applications involves the following processes:
1. Setting Analytic Server to Unicode Mode
1. Viewing the Unicode-related Mode of Analytic Server
1. Creating a New Unicode-Mode Application
1. Migrating Applications to Unicode Mode
1. Viewing the Unicode-Related Mode of an Application

Setting Analytic Server to Unicode Mode

By setting Analytic Server to Unicode mode, you grant permission for creating Unicode-
mode applications or migrating applications to Unicode mode.
 To set Analytic Server to Unicode mode, use either of the
following methods:

Tool Topic Location

Administrati Managing the Analytic Server Permission Essbase XTD
on Services to Create Unicode-Mode Applications Administration Services
Online Help
MaxL alter system Technical Reference

Note: You can work with Unicode-mode applications without Analytic Server being set to
Unicode mode.

Viewing the Unicode-related Mode of

Analytic Server
The Unicode-related mode of Analytic Server indicates whether or not Analytic Server
has permission to create Unicode-mode applications or migrate applications to Unicode
mode. In Administration Services, the Unicode-related mode of Analytic Server is shown
as a server property. In MaxL, it is displayed as the configuration, with the following
values:
1. 1, for non-Unicode-mode applications
1. 2, for Unicode-mode applications

To check to see whether or not Analytic Server is set to Unicode

mode, use either of the following methods:
Tool Topic Location
Administrati Managing the Analytic Server Permission Essbase XTD
on Services to Create Unicode-Mode Applications Administration Services
Online Help
MaxL display system Technical Reference

Creating a New Unicode-Mode Application

At the time that you create an application you can specify the application to be in
Unicode mode.

To create a new application and specify it to be in Unicode mode,

use either of the following methods:

Tool Topic Location

Administration Creating Unicode-Mode Essbase XTD Administration Services
Services Applications Online Help
MaxL create application Technical Reference

Migrating Applications to Unicode Mode

When Analytic Server migrates an application to Unicode mode, the character encoding
in the application files is converted to UTF-8 encoding. Text files such as calculation
scripts, report scripts, and data sources are not converted to UTF-8 encoding. For
Unicode-mode applications, text files such as calculation scripts, report scripts, and data
sources can be encoded in UTF-8 or in non-Unicode locales. You can use the Analytic
Services Unicode File Utility to convert non-Unicode-encoded files to UTF-8. For details
about this utility, see the Technical Reference.
Note: If you choose to work with non-Unicode text files, make sure that you understand
how Analytic Services determines the locales of non-Unicode text files. See Managing
File Encoding.
Before migrating application files to Unicode mode, perform the following tasks:
 1. As with any major conversion, be sure to back up all application and database
files in the application.
1. 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 the extension .chg; for example, \sample\basic\basic.chg.
1. To avoid mixing Unicode encoding and non-Unicode encoding in the logs, clear
or remove log files after backing them up. Log files end with any of the following
extensions: .log,.xcp, and .olg.
1. Grant Analytic Server permission to migrate applications to Unicode mode. See
Setting Analytic Server to Unicode Mode.

To migrate an application from non-Unicode mode to Unicode

mode, use either of the following methods:

Tool Topic Location

Administration Migrating Applications to Essbase XTD Administration
Services Unicode Mode Services Online Help
MaxL alter application Technical Reference

Viewing the Unicode-Related Mode of an

Application
In Administration Services, the Unicode-related mode of an application is shown as an
application property. In MaxL, it is displayed as the application type, with the following
values:
1. 2, for non-Unicode-mode applications
1. 3, for Unicode-mode applications
 To see whether or not an application is a Unicode-mode
application, use either of the following methods:

Tool Topic Location

Administration Application Properties Essbase XTD Administration Services
Services Window Online Help
MaxL display application Technical Reference

Using Control Characters in Report

Scripts
When working with reports for non-Unicode-mode applications, Report Writer uses
language-specific codes that enable columnar data to line up precisely. Unicode does not
contain these language-specific formatting codes within its encoding. As a result, report
columns may not line up precisely.
Non-Unicode-mode applications using single-byte code pages continue to support the
following Hexadecimal control characters in report scripts: x20, x09, x0A, x0D, xB3,
xC3, xC4, xC2, xC0, x0C, xB1.
Unicode-mode applications and non-Unicode-mode applications using multi-byte code
pages support the following Hexadecimal control characters in report scripts: x20, x09,
x0A, x0C, x0D.

Working With Partitions

Consider the following situations when designing and working with partitions:
1. Partitions cannot connect non-Unicode-mode databases to Unicode-mode
databases.
1. All databases in a partition must be in the same encoding.
1. Partitions across Unicode-mode databases can be administered by Unicode-mode
clients; for example, Administration Services or MaxL Scripts executed in
Administration Services Console.
1. Non-Unicode-mode outlines containing multi-byte characters cannot be
synchronized by Unicode-mode clients such as Administration Services and
MaxL scripts. However, you can use a client that is not Unicode enabled, such as
 Application Manager, or a non-Unicode mode client, such as the MaxL Shell
(essmsh).

Working With Logs

By default, the agent log is encoded to the locale specified by the ESSLANG variable
defined for Analytic Server. You can use the configuration setting,
UNICODEAGENTLOG, to tell Analytic Server to write the agent log in UTF-8
encoding. In UTF-8 encoding, with a font that supports it, all of the characters should be
readable. For details about the UNICODEAGENTLOG configuration setting, see the
Technical Reference.
Application and outline change log files for databases in Unicode-mode applications are
UTF-8 encoded. You can use Log Viewer in Administration Server or a UTF-8 editor to
view these application logs. You need a UTF-8 editor or viewer to view outline change
logs. You cannot change to non-Unicode encoding the encoding of logs related to
Unicode-mode applications.

Managing File Encoding

Analytic Services supports many non-Unicode encodings, as listed under Supported
Locales. In addition, UTF-8 encoding is supported for Unicode-mode applications.
Because a bit combination can map to different characters in different encodings, you
need to understand how Analytic Services works with file encodings-particularly if you
intend to use non-Unicode-encoded files with Unicode-mode applications.
Note: For Unicode-mode applications shared across multiple locales, using UTF-8-
encoded files is recommended. Using UTF-8 encoding is simpler because you do not
have to keep track of locales and encoding. Also, using UTF-8 can be more efficient
because Administration Server uses Unicode encoding internally and no internal
conversion between formats is needed.
This section describes how Analytic Services determines the encoding of files and how
you manage files with different encodings in the following sections:
1. How the Encoding of a File is Determined
1. Encoding Indicators
1. Locale Header Records
1. Analytic Services Unicode File Utility

How the Encoding of a File is Determined

With non-Unicode-mode applications, Analytic Services and Administration Services
assume that all character text is encoded to the locale specified by the ESSLANG value
defined for Analytic Server.
When Analytic Services works with Unicode-mode applications, it encodes character text
in UTF-8 encoding internally and stores character text in UTF-8 encoding, including
application log files. When it works with Unicode-mode applications, Analytic Services
can also handle non-Unicode-encoded files such as script files, rules files, and data
sources, converting them internally to UTF-8.
Analytic Services and Administration Services use file encoding indicators to know if a
file is encoded in UTF-8 or one of the supported non-Unicode encodings. Encoding
indicators are UTF-8 signatures or locale indicators. A locale indicator is optional for a
non-Unicode input file whose encoding matches the locale of the Analytic Server.
However, a locale indicator must be provided for a non-Unicode input file with a
different encoding than specified in the locale of the Analytic Server. For details about the
encoding indicators, see Encoding Indicators.
UTF-8-encoded text files must include the UTF-8 signature.
Administration Services uses the following process to determine the encoding of a non-
Unicode-encoded file:
• If a locale indicator is present in the file, it uses the specified encoding.
• If the file is located within an application, it uses the encoding specified in the
locale of the Analytic Server.
12. It the file is not located within an application, Administration Services determines
the encoding based on the type of file:
1. With text files, Administration Services prompts for the encoding.
1. With outline files and rules files, Administration Services uses the
encoding specified in the locale of the Analytic Server.

When Analytic Services 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 while 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. When
you use any other tool than Administration Services Console to create text Unicode-
encoded files, you must ensure that the UTF-8 signature is included. Locale indicators are
not needed in text non-Unicode-encoded files require a locale indicator if the encoding is
different than the locale of Analytic Server.
The following text Analytic Services system files are encoded to the locale specified by
the ESSLANG value defined for Analytic Server.
1. The configuration file (essbase.cfg)
1. ESSCMD scripts

Encoding Indicators
To properly interpret text such as member names, Analytic Services must know how it is
encoded. Many files contain an encoding indicator, but you may occasionally be
prompted to specify the encoding of a file; for example, when you create a new file and
store it in a different location than the Analytic Server or read a file created by a previous
release of Analytic Server. The type of encoding indicator depends on the type of file:
1. Files that are internal to applications and databases and that users cannot directly
edit are primarily binary files and do not contain any type of encoding indicator.
Character text in these files is encoded to the application which is either a
Unicode-mode or non-Unicode mode application.
1. Text in Unicode-mode application files is UTF-8 encoded.
1. Text in non-Unicode-mode application files is encoded to the locale
specified in the ESSLANG of the Analytic Server where the application
was created.
 1. Binary files that you can edit include outline files and rules files. As needed,
Analytic Services keeps track internally in outline files and rules files whether or
not the character text is in UTF-8 encoding. If not UTF-8, Analtic Services uses
an internal locale indicator to identify the locale used for character text encoding.
1. The following text files that you can edit use a UTF-8 signature or a locale header
to indicate their encoding.
1. Calculation scripts
1. Report scripts
1. MaxL scripts
1. Data sources for dimension builds and data loads
1. Alias table import files
Note: Essbase Administration Services requires alias table import files to
be UTF-8 encoded.

The UTF-8 signature is a mark at the beginning of a text file. The UTF-8 signature,
visible in some third-party editors, indicates that the file is encoded in UTF-8. Many
UTF-8 text editors can create the UTF-8 signature. You can also use the Analytic Services
Unicode File Utility (ESSUTF8) to insert the UTF-8 signature into a file. For more
information, see Analytic Services Unicode File Utility. When you create one of these
files using Administration Services Console, a UTF-8 signature is automatically inserted
in the file.
UTF-8-encoded text files must contain the UTF-8 signature.
The locale header record is an additional text record that identifies the encoding of the
non-Unicode-encoded text file. You can add the locale header at the time you create the
file or you can use the Analytic Services Unicode File Utility to insert the record. For
details about the locale header, see Locale Header Records.
Note: Do not combine a UTF-8 signature and locale header in the same file. If a text file
contains both types of encoding indicators, the file will be interpreted as UTF-8 encoded,
and the locale header will be read as the first data record.
Caution: Do not use non-Unicode-encoded files containing locale indicators with
Analytic Server installations that are not Unicode-enabled; that is, installed using releases
prior to Release 7.0. The Analytic Services Unicode File Utility (ESSUTF8) enables you
to remove locale indicators.

Locale Header Records

The locale header record is an additional text record that identifies the encoding of the
non-Unicode text file. You can insert the locale header record as the first record in a non-
Unicode-encoded text file when you create the file or you can use the Analytic Services
Unicode File Utility (ESSUTF8) program to add the header. The locale header record has
the following format:

//ESS_LOCALE <locale-name>
<locale-name> is a supported Global C locale in the same format as is used for the
ESSLANG variable:

<language>_<territory>.<code page name>@<sortsequence>

Note: Analytic Services consults only the <code page name> portion of the record. The
<sortsequence> specification does not affect sort sequences in report scripts.
See Supported Locales for a list of supported Global C locales.
The following example displays a locale header for a specific Russian code page:

//ESS_LOCALE Russian_Russia.ISO-8859-5@Default

The following rules also apply:

1. After <locale-name>, use a blank, tab or <end of line> to end the header.
1. You can include blanks or tabs in the following locations:
1. Before the keyword "//ESS_LOCALE"
1. Between "//ESS_LOCALE" and <locale-name>
1. After the locale specification
Caution: Do not insert a locale header record in a UTF-8 encoded file. The file will be
interpreted as UTF-8 encoded, and the locale header will be read as the first data record.
For compatibility, when Administration Console saves calculation scripts on Analytic
Server installations that are not Unicode-enabled, that is, installed using releases prior to
Release 7.0, it uses a different format. Instead of prefixing the locale with //,
Administration Console inserts the locale header between the calculation script comment
indicators, /* */.
Supported Locales
The following supported locales can be used as locales in locale header records and in the
Analytic Services Unicode File Utility (ESSUTF8), and as ESSLANG 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.Latin1@Binary

English_UnitedStates.MS1252@Binary

English_UnitedStates.US-ASCII@Binary

Finnish_Finland.IBM500@Finnish

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

Japanese_Japan.MS932@Binary

Japanese_Japan.Shift_JIS@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@Danish

Polish_Poland.ISO-8859-2@Polish

Polish_Poland.MS1250@Polish

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

SimplifiedChinese_China.UTF-8@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

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

Analytic Services Unicode File Utility

You can use the Analytic Services Unicode File Utility to convert non-Unicode-encoded
text files to UTF-8 encoding or to add or delete encoding indicators. This program
supports the following operations:
• Converting non-Unicode-encoded text files to UTF-8 encoding, including the
UTF-8 signature
• Adding UTF-8 signatures to UTF-8-encoded text files
• Inserting a locale header record at the beginning of non-Unicode-encoded text
files
• Adding a locale indicator to outline files (.otl) or rules files (.rul)
• Removing locale indicators from files. (The utility cannot remove UTF-8
signatures.)

Located in the ARBORPATH\bin directory, this utility program is called essutf8.exe (in
Windows) or ESSUTF8 (in UNIX). You can use the Analytic Services Unicode File
utility program with the following files:
• Calculation scripts
• Report scripts
• MaxL scripts
• Text data sources for dimension builds and data loads
• Alias table import files
• Outline files
• Rules files

For information about this utility and its command syntax, see the Technical Reference.
http://dev.hyperion.com/techdocs/essbase/essbase_70/Docs/dbag/frameset.htm?dba_html.
htm