ESBAR

Oracle® Essbase
API Reference
Release 11.1.2.4
Essbase API Reference, 11.1.2.4
Copyright © 1996, 2015, Oracle and/or its affiliates. All rights reserved.
Authors: EPM Information Development Team
This software and related documentation are provided under a license agreement containing restrictions on use and
disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or
allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit,
perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation
of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find
any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of
the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS:
Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or
documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable
Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure,
modification, and adaptation of the programs, including any operating system, integrated software, any programs installed
on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.
No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications that may create a risk of
personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all
appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates
disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective
owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under
license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the
AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark
of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and services
from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any
kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement
between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred
due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement
between you and Oracle.
Contents
Documentation Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Part I. Preliminary Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 1. Introduction to the Oracle Essbase API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Essbase API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
What's in This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
What You Should Know Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Conventions Used in this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Using Function Reference Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 2. Building the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Supported Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Including API Files in Your Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Building a Program on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 3. Integrating Essbase With Your Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Essbase Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Customizing the Run-Time Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Customizing the Path to the Essbase CLIENT Directory . . . . . . . . . . . . . . . . . . . . . . 37
Customizing the Path to the Message Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Customizing the Path to the Essbase Login Help File . . . . . . . . . . . . . . . . . . . . . . . . . 38
Creating Your Own On-line Help for AutoLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
API Files You Need to Ship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Installing Your Application Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Optimizing TCP/IP Networking for API Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 4. Building a Simple API Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
iii
Design Environment Setup Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Basic Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
The Nested Program Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Using Function Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Calling API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Initializing the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Logging On to a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Connecting to a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Terminating the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Assembling a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Building Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Editing the Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Loading Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Updating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Calculating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Using Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Maintaining Applications and Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Handling Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Managing Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Chapter 5. Unicode Issues in Essbase API Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

General Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Defining Unicode Mode Client Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Non-Unicode Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Unicode-enabled Clients in Non-Unicode Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Unicode-enabled Clients in Unicode Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Specifying Unicode Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Specifying the Byte Order Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Unicode Mode and Essbase Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Unicode Outlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Grid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Part II. C Main API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Chapter 6. Using the C Main API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

C Main API Instance Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
C Main API Context Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
C Main API File Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
iv
Using Memory in C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
C Main API Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
How the Essbase C Main API Handles Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Defining a Custom Message Function in C Programs . . . . . . . . . . . . . . . . . . . . . . . . 80
Choosing a Network Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Calling C Main API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Typical C Main API Task Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Initializing the C Main API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Logging in to an Essbase Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Selecting an Active Application and Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Retrieving and Updating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Recalculating the Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Logging Out from the Essbase Server and Terminating the C Main API . . . . . . . . . . . . . . 87
C Main API Common Problems and Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Chapter 7. C Main API Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Standard C Language Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Simple Data Types (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Other Data Types (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Bitmask Data Types (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Pointer Types (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Miscellaneous Types (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Array Types (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
API Definitions (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Constant Definitions (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Attributes Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Dimension Tag Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Implied Share Setting (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Information Flag Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
List Option Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Maximum String Lengths (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Request Type Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Size Flag Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Unicode Mode Constants (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
LRO Constant and Structure Definitions (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Constants for LROs (C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
ESS_CELLADDR_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
ESS_LRODESC_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
ESS_LROHANDLE_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
v
ESS_LROINFO_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Constant and Structure Definitions for Partitions (C) . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Drill-Through Constant and Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
C Main API Drill-Through Constants and Structures (essdt.dll) . . . . . . . . . . . . . . . . 104
C Main Drill-Through Constants and Structures (essdtapi.dll) . . . . . . . . . . . . . . . . . 106
C Main API Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
ESS_APPDB_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
ESS_APPINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
ESS_APPINFOEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
ESS_APPSTATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
ESS_ATTRIBUTEINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
ESS_ATTRIBUTEVALUE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
ESS_ATTRSPECS_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
ESS_BLDDL_STATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
ESS_CONNECTINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
ESS_CONNECTINFOEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
ESS_DBFILEINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
ESS_DBINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
ESS_DBREQINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
ESS_DBSTATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
ESS_DBSTATS_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
ESS_DIMENSIONINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
ESS_DIMSTATS_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
ESS_DTAPICOLUMN_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
ESS_DTAPIDATA_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
ESS_DTAPIHEADER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
ESS_DTAPIINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
ESS_DTAPIREPORT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
ESS_DTBUFFER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
ESS_DTDATA_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
ESS_DTHEADER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
ESS_DISKVOLUME_REPLACE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
ESS_DURLINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
ESS_EXTUSERINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
ESS_GENLEVELNAMEEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
ESS_GLOBAL_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
ESS_INIT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
ESS_LOAD_BUFFER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
ESS_LOCKINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
vi
ESS_LOCKINFOEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
ESS_LOG_DATALOAD_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
ESS_MBRALT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ESS_MBRERR_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ESS_MBRUSER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
ESS_MEMBERINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ESS_NEWSHAREDSERVICESNATIVEUSERINFO_T . . . . . . . . . . . . . . . . . . . . . . 145
ESS_OBJDEF_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
ESS_OBJINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
ESS_PART_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
ESS_PART_CONNECT_INFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ESS_PART_DEFINED_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
ESS_PART_INFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
ESS_PART_REPL_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ESS_PARTDEF_INVALID_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
ESS_PARTDEF_CONNECT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
ESS_PARTDEF_MAP_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ESS_PARTDEF_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ESS_PARTDEF_AREAS_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
ESS_PARTDEF_TYPE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
ESS_PARTHDR_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
ESS_PARTOTL_CHANGE_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
ESS_PARTOTL_CHG_FILE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
ESS_PARTOTL_DIM_ATTRIB_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
ESS_PARTOTL_DIMASSOCCHG_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
ESS_PARTOTL_DIMCHG_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
ESS_PARTOTL_MBR_RSRVD_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
ESS_PARTOTL_MBRASSOCCHG_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
ESS_PARTOTL_MBRATTR_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
ESS_PARTOTL_MBRCHG_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
ESS_PARTOTL_NAMECHG_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
ESS_PARTOTL_NAMED_GENLEV_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
ESS_PARTOTL_NAMEMAP_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
ESS_PARTOTL_OSN_RELATIVES_API_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
ESS_PARTOTL_QUERY_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
ESS_PARTOTL_QRY_FILTER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
ESS_PARTOTL_READ_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
ESS_PARTOTL_SELECT_APPLY_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ESS_PARTOTL_SELECT_CHG_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
vii
ESS_PARTSLCT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
ESS_PARTSLCT_VALIDATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
ESS_PERF_ALLOC_ARG_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
ESS_PERF_ALLOC_ERROR_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
ESS_PERF_ALLOC_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
ESS_PERF_CUSTCALC_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
ESS_PROCSTATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
ESS_RATEINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
ESS_REQUESTINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
ESS_REQUESTINFOEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
ESS_REQ_STATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
ESS_RUNTIMESUBVARS_DESC_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
ESS_SECURITY_MODE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
ESS_SEQID_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
ESS_TIMERECORD_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
ESS_TRANSACTION_ENTRY_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
ESS_TRANSACTION_REPLAY_INP_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
ESS_TRANSACTION_REQSPECIFIC_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
ESS_USERAPP_T, ESS_GROUPAPP_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
ESS_USERAPPEX_T, ESS_GROUPAPPEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
ESS_USERDB_T, ESS_GROUPDB_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
ESS_USERDBEX_T, ESS_GROUPDBEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
ESS_USERINFO_T, ESS_GROUPINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
ESS_USERINFOID_T, ESS_GROUPINFOID_T . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
ESS_USERINFOEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
ESS_VARIABLE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Chapter 8. C Main API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

C Main API Function Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
C Main API Alias Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
C Main API Application Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
C Main API Attributes Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
C Main API Database Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
C Main API Database Member Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
C Main API Drill-through Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
C Main API File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
C Main API Group Administration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
C Main API Initialization and Login Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
C Main API LRO Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
viii
C Main API Location Aliases Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
C Main API Memory Allocation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
C Main API Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
C Main API Object Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
C Main API Partition Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
C Main API Performance Stats Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
C Main API Reporting, Updating, and Calculation Functions . . . . . . . . . . . . . . . . . 205
C Main API Runtime Substitution Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
C Main API Security Filter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
C Main API Substitution Variables Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
C Main API User Administration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
C Main API User and Group Identity Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
C Main API Shared Services Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
C Main API Unicode Mode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
C Main API Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Part III. C Outline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
Chapter 9. Using the C Outline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

C Outline API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
C Outline API Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
C Outline API Server Outline Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
C Outline API Outline Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
C Outline API Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
C Outline API Security Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
C Outline API Function Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Typical C Outline API Task Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Chapter 10. C Outline API Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695

C Outline API Error Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
C Outline API DTS Member Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
C Outline API Symbolic Constant Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Account Member Currency Conversion Category Values . . . . . . . . . . . . . . . . . . . . . 703
Account Member Time Balance Skip Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Account Member Time Balance Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Dimension Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Dimension Categories (Tags) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
Member Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
Generation and Level Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Query Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
ix
Query Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Restructure Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Share Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Sorting Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
ESS_ATTRIBUTEQUERY_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
ESS_GENLEVELNAME_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
ESS_GENLEVELNAMEEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
ESS_MBRCOUNTS_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
ESS_MBRINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
ESS_OTLQUERYERRORLIST_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
ESS_OUTERROR_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
ESS_OUTLINEINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
ESS_OUTLINEINFOEX_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
ESS_PERSPECTIVE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
ESS_PREDICATE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
ESS_SVROTLINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
ESS_VALIDITYSET_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Chapter 11. C Outline API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723

C Outline API Function Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
C Outline API Alias Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
C Outline API Attributes Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
C Outline API Dynamic Time Series Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
C Outline API Generation Name Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
C Outline API Level Name Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
C Outline API Member Administration Functions . . . . . . . . . . . . . . . . . . . . . . . . . 725
C Outline API Member Alias Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
C Outline API Member Formula Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
C Outline API Member Traversal Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
C Outline API Outline Administration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 727
C Outline API Outline Query Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
C Outline API Setup and Cleanup Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
C Outline API Unicode Mode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
C Outline API User-Defined Attributes Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 729
C Outline API User-Defined View Selection Functions . . . . . . . . . . . . . . . . . . . . . . 729
C Outline API Varying Attributes Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
C Outline API Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Chapter 12. C Outline API Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

Example of Traversing an Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
x
Extended Member Query Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Part IV. C Grid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007
Chapter 13. Using the C Grid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009

General Information on the C Grid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Overview of C Grid API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
C Grid API Supported Platforms and Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
Files to Include in C Grid API Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
C Grid API Initialization and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
C Grid API Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
C Grid API Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
Using the C Grid API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
Using the C Main API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
C Grid API Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
Chapter 14. C Grid API Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015

C Grid API Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
Grid Perspective Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
Text List (SmartList) Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
Unicode Mode Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
C Grid API Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
C Grid API Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
ESSG_CONNECTINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
ESSG_DATA_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
ESSG_DRILLDATA_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
ESSG_DTDATA_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
ESSG_DTHEADER_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
ESSG_DTINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
ESSG_DTREPORT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
ESSG_INIT_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
ESSG_LRODESC_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
ESSG_LROINFO_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
ESSG_RANGE_T . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
Chapter 15. C Grid API Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033

EssGBeginConditionalRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
EssGBeginConditionalZoomIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
EssGBeginCreateLRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
EssGBeginDataPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
EssGBeginDeleteLROs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
xi
EssGBeginDrillAcross . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
EssGBeginDrillOrLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
EssGBeginKeepOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
EssGBeginLock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
EssGBeginPivot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1046
EssGBeginRemoveOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048
EssGBeginReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
EssGBeginReportFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
EssGBeginRetrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
EssGBeginSamplingZoomIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
EssGBeginUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
EssGBeginZoomIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
EssGBeginZoomOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
EssGCancelOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
EssGCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
EssGCreateMemberwKeyStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
EssGConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
EssGConnectEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071
EssGDeleteLRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072
EssGDestroyGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073
EssGDisconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
EssGDTBeginDrillThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
EssGDTConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
EssGDTEndDrillThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
EssGDTExecuteReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
EssGDTGetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078
EssGDTGetHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078
EssGDTGetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
EssGDTGetReportData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
EssGDTListReports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
EssGDTReportCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081
EssGDTRequestDrillThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
EssGDTSetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
EssGEndOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
EssGFreeCellLinkResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
EssGFreeMemberInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
EssGFreeMemberwKeyStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
EssGFreeRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088
EssGGetAPIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
xii
EssGGetAPIInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1090
EssGGetCellLinkResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
EssGGetDataPointResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
EssGGetFormattedValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
EssGGetFromMemberwKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
EssGGetGridOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097
EssGGetGridPerspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
EssGGetIsCellDrillable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098
EssGGetLinkedPartitionDesc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
EssGGetLRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
EssGGetLRODesc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1101
EssGGetMemberInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
EssGGetResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
EssGGetRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1104
EssGGetSmartlistforCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105
EssGInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
EssGLoginSetPass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
EssGNewGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
EssGPerformOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
EssGSendRows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
EssGSetGridOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
EssGSetGridPerspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
EssGSetPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1114
EssGTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
EssGUnlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
EssGUpdateLRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117
EssGVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117
Chapter 16. C Grid API Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119

C Grid API Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119
C Grid API Drill-Through Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123
ESSG_OP_MEMBERANDUNIQUENAME Example . . . . . . . . . . . . . . . . . . . . . . . . . 1125
ESSG_DT_MEMBERwKEY Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
BuildTable Example Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
DisplayOutput Example Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
FreeTwoDim Example Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
xiii
Chapter 17. C Grid API Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133
Part V. Other APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
Chapter 18. Java API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
Chapter 19. MDX Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139

MDX Provider API General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
MDX Provider API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141
MDX Provider Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141
EssMdxExecuteQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
EssMdxFreeQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
EssMdxGetAxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
EssMdxGetAxisInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
EssMdxGetAxisMembers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144
EssMdxGetCellAtIndices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
EssMdxGetCellAtOffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
EssMdxGetCellInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
EssMdxGetCellStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
EssMdxGetClusterDimMembers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
EssMdxGetClusterInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
EssMdxGetClusterMembers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
EssMdxGetClusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
EssMdxGetDimInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
EssMdxGetFormatString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1150
EssMdxGetFormattedValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
EssMdxGetMbrIdentifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
EssMdxGetMbrProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151
EssMdxGetNamedSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
EssMdxGetPropertyInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
EssMdxGetQueryCellProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
EssMdxGetQueryOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
EssMdxGetSmartlistforCell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155
EssMdxGetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155
EssMDXIsCellGLDrillable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
EssMdxNewQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
EssMdxSetDataLess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
EssMDXSetHideData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
EssMdxSetMbrIdType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
EssMdxSetNeedCellStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
xiv
EssMdxSetQueryCellProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
EssMdxSetQueryOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
MDX Sample Client Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1160
Chapter 20. Welcome to XMLA Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
Chapter 21. Working with XMLA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175

Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
Discover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179
XMLA Rowsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
CATALOGS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
MDSCHEMA_CUBES Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
MDSCHEMA_DIMENSIONS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184
MDSCHEMA_FUNCTIONS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1187
MDSCHEMA_HIERARCHIES Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189
MDSCHEMA_MEASURES Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192
MDSCHEMA_MEMBERS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194
MDSCHEMA_PROPERTIES Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1197
MDSCHEMA_SETS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
MDSCHEMA_LEVELS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
DISCOVER_SCHEMA_ROWSETS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
DISCOVER_DATASOURCES Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
DISCOVER_PROPERTIES Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
DISCOVER_ENUMERATORS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1207
DISCOVER_KEYWORDS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1209
DISCOVER_LITERALS Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
Flattened Rowset Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
MDX Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
XMLA Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215
Appendix A. API Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219

Sample C API Program 1 (cs1.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
Appendix B. Shared Services Migration and User Management API Example . . . . . . . . . . . . . . . . . . . . . . . 1247
Appendix C. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255

Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
xv
Essbase Server (Host) Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
Application Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255
Database Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Filter Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Group Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Object Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Password Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
User Name Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
Drill-through URL Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257
xvi
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support.
For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://
www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
17
18
Documentation Feedback
Send feedback on this documentation to: [email protected]

Follow EPM Information Development on these social media sites:
LinkedIn - http://www.linkedin.com/groups?gid=3127051&goback=.gmp_3127051
Twitter - http://twitter.com/hyperionepminfo
Facebook - http://www.facebook.com/pages/Hyperion-EPM-Info/102682103112642
Google+ - https://plus.google.com/106915048672979407731/#106915048672979407731/posts
YouTube - http://www.youtube.com/user/OracleEPMWebcasts
19
20
Part I
Preliminary Information
In Preliminary Information:
l Introduction to the Oracle Essbase API Reference

l Building the Program
l Integrating Essbase With Your Product
l Building a Simple API Program
l Unicode Issues in Essbase API Programs
21
22
Introduction to the Oracle
1 Essbase API Reference
In This Chapter
Essbase API Overview .....................................................................................23
What's in This Document ..................................................................................24
What You Should Know Before You Start ................................................................24
Conventions Used in this Document .....................................................................24
Using Function Reference Entries ........................................................................25
Essbase API Overview

Oracle Essbase provides a business performance management solution that satisfies the complex
calculation requirements of end-user analysts across the enterprise in various departments,
including finance, accounting, and marketing. Essbase operates in a client-server computing
environment on a local area network (LAN), enabling multiple users to retrieve and analyze
centralized data.
Essbase client tools provide access to centralized data through a variety of interfaces, including:
l Grid interfaces such as Oracle Smart View for Office.
l Application and data management facilities.
l Custom programs you can develop using the Essbase Application Programming Interface
(API).
The Essbase API provides a range of powerful and sophisticated features, including:
l Transparent client-server access
l Data manipulation, consolidation and reporting
l Encapsulated server login procedure
l Remote file management
l Application and database administration
l User and group administration
l Transparent, built-in security
l Customized memory and message handling
l Multiple platform support
23
l Function library that allows direct creation, manipulation, and maintenance of database
outlines from a C program
l For a list of new features, see the Oracle Essbase New Features.
The API is an interface between your custom client program and Essbase, and manages the
transfer of data between client and server. Your program makes calls to functions within the
API, and data is returned from the Essbase servers you connect to.
You can also run custom programs on the server machine, using the same API functions as on
the client. You don't have to be concerned about where the Essbase Server computer is located
on the network when writing a custom API program. Locating the server and transferring data
is handled by the API.
Before you write programs for the API, use this document to become familiar with some of the
concepts and conventions it uses.
The API functionality is contained in header files you include in the source code of your program
and a set of libraries that you link to your program.
What's in This Document

This document is designed for programmers who develop custom front-end programs that
access the Essbase Server.
The Oracle Essbase API Reference is a comprehensive reference to the functions and libraries you
can use to develop custom front-end programs that access Essbase application servers. The
document provides:
l General information about installing and using the API
l Specific reference material for programmers
What You Should Know Before You Start

To use this document, you need the following:
l A working knowledge of the operating system your server and clients use.
l An understanding of Essbase.
l Knowledge of programming in Windows or UNIX.
l Familiarity with C or Java.
Conventions Used in this Document

Table 1 lists the conventions that the Oracle Essbase API Reference uses to make code and examples
easier to understand.
24
Table 1 Syntax and Text Formatting Conventions
Convention Purpose Example
monospace font Function, structure, file, directory, and environment variables names ESS_STS_T, ESSAPIW.LIB
in text
italic Anything you replace with a value in syntax EssOtlCloseOutline (hOutline)
" " Double quotes enclose text parameters or parameters that include a "appName"
space
SETDEFAULTCALC "CALC ALL";
() Parentheses enclose function parameters, show order of execution for EssOtlDeleteMember

operations (hOutline, hMember);
(a + b) * c
// Comment marker indicates text from // to end of line should be ignored // Gets results
in processing
; Statement terminator marks end of command EXIT;
Using Function Reference Entries

Table 2 lists the information supplied by API function entries.
Table 2 API Function Entries
Function Entry Description
Description Brief description of the function.
Syntax Function syntax. Function name and required keywords: bold. Parameters: italics.
Parameters Definitions of the parameters of the function.
Return Value Value returned by the function.
Notes Notes on using the function.
Access Level of security or other access required to use the function.
Example How to use the function.
See Also Related functions.
25
26
Building the Program
2
In This Chapter
Supported Compilers ......................................................................................27
Supported Platforms.......................................................................................29
Naming Conventions.......................................................................................30
Including API Files in Your Program ......................................................................31
Building a Program on UNIX ..............................................................................31
Supported Compilers
Table 3 lists the compilers that the current release of the Essbase API supports.
Table 3 Supported Compilers
Platform Compiler
Windows 2003 Server / 2008 Server (32/64 bit) Visual Studio 2010 with Service Pack 1
HP-UX 11.x (64-bit only) HP-UX C compiler (Version 5 with latest patch, or later)
AIX (5.3 or later, 32/64 bit) AIX compiler (11.1 or later)
Solaris (10 or later, 32/64 bit) Sun Studio (12.2 or later)
Red Hat Linux or Oracle Enterprise Linux (4.0 or later, 32/64 bit) GCC compiler (4.4.4 or later)
Note: The Essbase API no longer supports Visual Basic.
Sample Windows Make Files

The following are sample make files for either 32-bit or 64-bit Windows. See also Support on
64-Bit Platforms.
# common.mak
# Common Windows settings
UTF8 = 1
27
#--------------------------------------------------------------------
# Essbase's include and library path
#--------------------------------------------------------------------
ESSINCDIR = /I$(APIPATH)/api/include
ESSLIBDIR = /LIBPATH:$(APIPATH)/api/lib
#--------------------------------------------------------------------
# MSDEV compiler options
#--------------------------------------------------------------------
CP = cp
MKDIR = mkdir
RM = rm
MAKE = nmake
CC = cl
CPPC = cl
LINK = link
SVRLINK = link
!IF "$(SXR_64BIT)" == "1"

STDLIBS = kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib
shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib
user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib
oleaut32.lib uuid.lib odbc32.lib odbccp32.lib bufferoverflowu.lib
CFLAGS = /nologo /c /w /D"_CRT_SECURE_NO_DEPRECATE" -DBIT64 -DWIN64

CPPFLAGS = /nologo /c /w /D"_CRT_SECURE_NO_DEPRECATE" -DBIT64 -DWIN64
!IF "$(PROCESSOR_ARCHITEW6432)" == "IA64"

LFLAGS = /nologo /DEBUG /MACHINE:IA64
LPPFLAGS = /nologo /DEBUG /MACHINE:IA64
LIBFLAGS = /nologo /MACHINE:IA64
!ELSE
LFLAGS = /nologo /DEBUG /MACHINE:AMD64
LPPFLAGS = /nologo /DEBUG /MACHINE:AMD64
LIBFLAGS = /nologo /MACHINE:AMD64
!ENDIF
!ELSE
STDLIBS = kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib
shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib kernel32.lib
user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib
oleaut32.lib uuid.lib odbc32.lib odbccp32.lib
CFLAGS = /nologo /MLd /c /w -D_USE_32BIT_TIME_T

CPPFLAGS = /nologo /MLd /c /w
LFLAGS = /nologo /DEBUG /MACHINE:I386
LPPFLAGS = /nologo /DEBUG /MACHINE:I386
LIBFLAGS = /nologo /MACHINE:I386
!ENDIF
!IF "$(UTF8)" == "0"

ESSLIBS = essapin.lib essgapin.lib essotln.lib
!ELSE
ESSLIBS = essapinu.lib essgapinu.lib essotlnu.lib
!ENDIF
28
# Makefile.dat
include common.mak
APITESTSOURCE = \
CuTest.c \
EssUtil.c \
apgd9096056.c \
capimain.c \
#----------------------------------------------------------
# Make rule
#----------------------------------------------------------
INCDIR1 = /IC:/api_view/src
INCDIR2 = /IK:/essexer/base/src
APITESTMAIN = capimain
APITESTOBJS = $(APITESTSOURCE:.c=.obj)
$(APITESTMAIN).exe: $(APITESTOBJS)
$(LINK) $(LFLAGS) /out:$(APITESTMAIN).exe $(APITESTOBJS) $(STDLIBS) $(ESSLIBDIR) $
(ESSLIBS)
$(APITESTOBJS): $(APITESTSOURCE)
$(CC) $(CFLAGS) $(APITESTSOURCE) $(ESSINCDIR) $(INCDIR1) $(INCDIR2)
Supported Platforms
For a list of platforms the current release of the Essbase API supports, see the Oracle Enterprise
Performance Management System Certification Matrix.
Support on 64-Bit Platforms

l Client programs developed using the Essbase C API can be run on 32-bit platforms
connecting to either 32-bit or 64-bit Essbase servers.
l Client programs developed using the Essbase C API can be run on 64-bit platforms
connecting to 64-bit Essbase servers.
l When running the precompiled 32-bit client program on the 64-bit machine, run it from a
command prompt or other shell window where ESSBASEPATH is set to the installation
directory of the 32-bit runtime client, and PATH is set to include the bin subdirectory under
the ESSBASEPATH directory.
l To build 64-bit objects on Windows, use the following compiler and linker flags:
m Compiler:
-DBIT64 -DWIN64
m Linker (Intel and AMD based processor):
/MACHINE:AMD64
29
Naming Conventions
The API uses its own naming conventions for functions, constants, and data types. To ensure
compatibility with future releases of the API, use these constants and data type declarations in
your program:
l Function names—Describe the action the function performs. A name is made of a prefix
that represents the interface, followed by one or more words or fragments that describes the
action and its object. The parts of the name are not separated by spaces but are capitalized
for easier interpretation. Names follow this format:
Format and Parts of Name Example
InterfaceVerbObject Interface
Programming interface EssCreateGroup
Ess = C API EssUpdate = C API
EssOtl = C Outline API EssOtlOpenOutline = C Outline API
EssG = C Grid API EssGSetGridOption = C Grid API
Verb Action to perform, such as "Report" EssReportFile (no verb) sends the report
Object Object of action, such as "Group" EssUpdate (no Object) acts on the current object
l Data structure names—Begin with a prefix that represents the interface, includes a word or
fragment that describes the structure, and ends with a suffix indicating either typedef
definition or macro. Underscore characters separate the parts of the name. Names follow
this format:
Interface_Name_Type Interface
Programming interface: ESS (for C API) EssCreateGroup
Type Type of structure, either T (typedef definition) or M (macro) ESS_STR_T = C language typedef for String
l C API constant names—Begin with the prefix ESS that represents the C interface, includes
a word that describes the constant, and has no suffix. Underscore characters separate the
parts of the name. Names follow this format:
Structure Data type or structure field, such as "Boolean" ESS_Structure_Value
Value Type of value the constant stores ESS_STS_NOERROR could store a value for the ESS_STS_T data type
30
Including API Files in Your Program
To use the Essbase API in your program, you must include the file that contains API definitions.
This topic describes the files you need for the C API.
Header Files
If your program is using the Main API, essapi.h should be included. If it is using the Outline
API, essotl.h should be included. If it is using the Grid API, essgapi.h should be included.
API Files for C Programs

To use the Main API in a C program, you must include the API header definitions file (ESSAPI.H)
in the appropriate source modules. Always include this file after any C run-time library header
files. If you are programming in the Windows environment, place ESSAPI.H after the Windows
include file WINDOWS.H.
C Compiler Options (32–Bit Windows Only)

If you are using an encapsulated C development environment, such as Microsoft Visual C++,
you should check the compiler and linker options carefully to ensure that the API will work
correctly. In particular, you must ensure that structure fields are byte-aligned, and that the
correct libraries are used. Make sure to include the appropriate API library in your link process
(see “API Libraries” on page 40).
The following program statements will ensure byte alignment and should be placed in the
INCLUDE section of the program:
#ifdef WINNT
#pragma pack (1)
#endif
#include
#include
#pragma pack ()
#endif
Building a Program on UNIX

The Essbase API is supported on the same platforms Essbase supports: HP-UX, AIX, Solaris,
and Linux. The Essbase API supports the same CPU architechtures (with regard to 32- and 64-
bit) that are supported by Essbase. See the Oracle Hyperion Enterprise Performance Management
System Installation and Configuration Guide.
This topic provides the information needed to compile an application program using the API
on UNIX.
Memory Allocation
The Essbase API for UNIX uses the standard C library memory allocation functions, malloc(),
realloc(), and free(), as the default memory functions. You use the default memory functions if
31
you pass NULLs in the AllocFunc, ReallocFunc, and FreeFuncfields of the ESS_INIT_T
initialization structure. See “Using Memory in C Programs” on page 78 for more information.
UNIX Support
EssAutoLogin() is not supported in the UNIX versions of the Essbase API.
Be sure to follow UNIX file-naming conventions when using UNIX versions of the Essbase API.
HP-UX Information
l HP-UX-supplied files—For a listing of files supplied with Essbase API for HP-UX, see “API
Libraries” on page 40.
Use the -L flag to tell the linker where to locate the shared libraries:$(CC) file1.o
file2.o -L /essbase/lib -lessapi \ $(LIBS) -o
All libess*.sl files are linked with the +s flag which allows you to use the SHLIB_PATH
search path to locate the shared library when the linked program is run. For further
information about SHLIB_PATH, please check HP-UX programming documentation.
l Linking programs on HP-UX—With the Essbase 6.0 release, you must use aCC to link your
program to maintain compatibility with the third party libraries used with Essbase. If you
are using an earlier version, you should use the ld compiler for linking.
l HP-UX Make File example—The following sample shows a make file for HP-UX.
# Compiler Flags
CC=cc
CFLAGS = -I$(<Location of API>)/api/include -g
# Library files;
LIBS = -L$(<Location of API>)/api/lib -lessapinu -lessotlnu -lessgapinu
main: main.o
$(CC) -o $@ $^ $(LIBS)
main.o: main.c
$(CC) $(CFLAGS) $< -c -o $@
Modify this sample make file to reflect the directories where you have installed the API files
and add other compiling options you want to use.
Even though the link line only specifies three libraries to link against, all of the .sl files must
be available at runtime.
l HP-UX 64-bit Make File example—On 64-bit HP-UX, use the compiler flag +DD64. No
linker flag is needed.
# Compiler Flags
CC=cc
CFLAGS = +DD64 -I$(<Location of API>)/api/include -g
# Library files;
main: main.o
32
$(CC) -o $@ $? $(LIBS)
main.o: main.c
$(CC) $(CFLAGS) -c $< -o $@
Even though the link line only specifies three Essbase libraries to link against, all of
the .so files must be available at runtime.
AIX Information
l AIX-supplied files—For a listing of files supplied with Essbase API for AIX, see “API
l AIX Make File example—The following sample shows a make file for AIX.
# Compiler Flags
CC=cc_r
CFLAGS = -qcpluscmt -I$(<Location of API>)/api/include -g
# Library files;
LIBS = -L$(<Location of API>)/api/lib -lessapinuS -lessotlnuS -lessgapinuS
main: main.o
$(CC) -o $@ $^ $(LIBS)
main.o: main.c
$(CC) $(CFLAGS) $< -c -o $@
For 64-bit AIX, use the -q64 -DAIX64 -DBIT64 compiler and -b64 linker flags.
Solaris Information
l Solaris-supplied files—For a listing of files supplied with Essbase API for Solaris, see “API
l Solaris Make File example—The following sample shows a make file for Solaris.
# Compiler Flags
CC=cc
# Library files;
main: main.o
$(CC) -o $@ $^ $(LIBS)
main.o: main.c
$(CC) $(CFLAGS) $< -c -o $@
33
For 64-bit Solaris, use the -xarch=generic64 -DBIT64 compiler and -
xarch=generic64 linker flags.
Red Hat Linux Information

l Red Hat Linux-supplied files—For a listing of files supplied with Essbase API for Red Hat
Linux, see “API Libraries” on page 40.
l Red Hat Linux Make File example—The following listing shows a sample make file to
compile and link a Red Hat Linux API program using the GCC compiler:
# Compiler Flags
CC=gcc
# Library files;
main: main.o
$(CC) -o $@ $^ $(LIBS)
main.o: main.c $(CC) $(CFLAGS) $< -c -o $@
Linux 64-bit Make File example—On 64-bit Linux, use the compiler flag -DBIT64.
# Compiler Flags
CC=gcc
CFLAGS = -I$(<Location of API>)/api/include -g -DBIT64
# Library files;
main: main.o
$(CC) -o $@ $^ $(LIBS)
main.o: main.c
$(CC) $(CFLAGS) $< -c -o $@
Modify the sample make file to reflect the directories where you have installed the API files
34
Integrating Essbase With Your
3 Product
In This Chapter
Essbase Directory Structure...............................................................................35
Customizing the Run-Time Environment .................................................................36
API Files You Need to Ship................................................................................39
API Libraries ................................................................................................40
Installing Your Application Program ......................................................................41
Optimizing TCP/IP Networking for API Clients ...........................................................42
Essbase Directory Structure

A computer that has the Essbase client programs installed uses a predefined directory structure,
described in Table 4. The exact name of the root directory depends on the name selected during
user installation, but the structure under the root directory is always the same.
Table 4 Predefined Directory Structure for Essbase Installations
Directory Description
\root Root directory: All Essbase files
\root\bin Binary directory: executables, shared libraries, and other program files
\root\client Client directory: Client application and database files
\root\client\appname Files relating to the application appName (one for each application)
\root\client\appname\dbname Files relating to the database dbName in the application appName (one for each database in
the application)
The root directory can have any name the user chooses at installation time.
Note: The root directory name cannot include spaces.
35
Table 5 Essbase API and Run-Time Client Directory Structure (Windows)
Component Directory
Run-Time Client, 32-bit %EPM_ORACLE_HOME%\common\EssbaseRTC\releaseNumber
For example, %EPM_ORACLE_HOME%\common\EssbaseRTC\11.1.2.0
Run-Time Client, 64-bit %EPM_ORACLE_HOME%\common\EssbaseRTC-64\releaseNumber
For example, %EPM_ORACLE_HOME%\common\EssbaseRTC-64\11.1.2.0
API, 32-bit %EPM_ORACLE_HOME%\products\Essbase\EssbaseClient\api
API, 32-bit (installed on 64-bit) %EPM_ORACLE_HOME%\products\Essbase\EssbaseClient-32\api
API, 64-bit %EPM_ORACLE_HOME%\products\Essbase\EssbaseClient\api
Oracle runtime files, 32-bit %EPM_ORACLE_HOME%\bin-32
Oracle runtime files, 64-bit %EPM_ORACLE_HOME%\bin
Customizing the Run-Time Environment

The Essbase API allows you to customize access to some of the API features, so you can integrate
these features with your programs. Besides customizing the memory management and message
handling, you can customize the items described in the these topics:
l “Customizing the Path to the Essbase CLIENT Directory” on page 37
l “Customizing the Path to the Message Database” on page 37
l “Customizing the Path to the Essbase Login Help File” on page 38
l “Creating Your Own On-line Help for AutoLogin” on page 39
You can change each of these paths by passing an entry into the appropriate field of the Essbase
API initialization structure when you call EsxInit(). Because you can change these paths, you
can install these directories and files anywhere you like and rename them if you desire.
You might want to place the files associated with your program in a specific directory. If this is
the case, you should set these paths explicitly in ESS_INIT_T.
An alternative to setting the paths explicitly is to rely on the user's ESSBASEPATH and
ARBORMSGPATH environment variables. When you call EssInit(), the API can define the
paths in the initialization structure based on the root directory of any pre-existing Essbase files
(ESSBASEPATH) or on ARBORMSGPATH.
Note: All settings in the initialization structure apply only to the calling program's instance of
the API library. Custom settings within your program do not affect any other programs
using the API library.
36
Customizing the Path to the Essbase CLIENT Directory
The API uses the CLIENT directory to store any local application or database related files (such
as database outlines or report scripts). The directory structure within the CLIENT directory
mirrors that of the \Appdirectory on the Essbase Server. Each application has its own sub-
directory, and within each application sub-directory, each database in that application has a
separate sub-directory. The list of applications and databases need not match that of any
particular server.
Although the structure of the application and database sub-directories is fixed, you can
customize the client directory under which the application directories are created.
Setting the Local Path Field of the Initialization Structure

The primary way to set the client directory path is to explicitly set the LocalPath field in the
API initialization structure to point to a string indicating the full path name of the CLIENT
directory. This setting causes the API to look in this directory for all client application and
database related files. For example, to set the CLIENT directory to D:\PRODUCT\CLIENT, make
the following change to the initialization structure: ESS_INIT_T
InitStruct;Initstruct.LocalPath = "D:\PRODUCT";
A secondary way to set the client directory path is to set LocalPath to NULL. By default, Essbase
then uses the ESSBASEPATH environment variable to determine the path to the CLIENT
directory.
Customizing the Path to the Message Database

Essbase uses a message database file called, by default, ESSBASE.MDB. The API enables you to
store the message database file with any file name and in any directory path you choose. You
must use the ESSBASE.MDB file, but you can rename it. Using the MessageFile field of
ESS_INIT_T, you can explicitly set the location and name of the message database.
Setting the MessageFile Field of the Initialization Structure

You can change the message database file name and directory path by setting the
MessageFile field in the initialization structure to point to a string indicating the full path and
file name of the message database. This causes the Essbase message system to look for the path
and file name specified whenever it needs to reference the text of an Essbase system message.
For example, if you wanted to call the message database file PRODUCT.MDB, and install it in the
C:\PRODUCT\MESSAGE directory, you would make the following change to the initialization
structure: ESS_INIT_T InitStruct;Initstruct.MessageFile = "C:\PRODUCT
\MESSAGE\PRODUCT.MDB";
If you don't want to set the name and location explicitly, you can set the MessageFile field to
NULL. By default, the API looks for a fully qualified file name in the ARBORMSGPATH
environment variable on the user's machine. If this variable is not set, the API uses the
ESSBASEPATH environment variable, appends \BIN to it, and uses that directory name to look
for ESSBASE.MDB.
37
Setting the ARBORMSGPATH Variable
If you want to use the ARBORMSGPATH environment variable, place an ARBORMSGPATH
statement in yourAUTOEXEC.BAT file if you are programming on a Windows platform. Under
UNIX, you set this variable in the environment script corresponding to your shell. See the
Installation Notes topic for more information. To set the path and file name to C:\PRODUCT
\MESSAGE\PRODUCT.MDB you would use the following statement: ARBORMSGPATH = C:
\PRODUCT\MESSAGE\PRODUCT.MDB
If you intend to use the ARBORMSGPATH or the ESSBASEPATH environment variable, set
the MessageFile field in ESS_INIT_T to NULL.
How Essbase Finds the Message Database

Essbase performs the following priority search to find the message database:
1. Essbase uses the directory path and file name specified in the MessageFile field of the
initialization structure.
2. If the MessageFile field is set to NULL, Essbase uses the complete file and directory path
specified in the ARBORMSGPATH environment variable.
3. If no ARBORMSGPATH variable is defined, Essbase uses the file name ESSBASE.MDB in
the directory path specified in the ESSBASEPATH environment variable, in its BIN sub-
directory.
4. If no ESSBASEPATH variable is defined, Essbase displays an error message.
Customizing the Path to the Essbase Login Help File

In Windows environments, the EsxAutoLogin() call displays a dialog box that contains a Help
button. It also provides access to other dialog boxes with their own Help buttons. Clicking the
Help button displays the Essbase System Login help topic (or the file specified in ESS_INIT_T).
If you don't write your own Help file, you can simply supply the default help to your users with
the product installation.
Setting the HelpFile Field of the Initialization Structure

You can specify the API help file by setting the HelpFile field in the initialization structure to
a string indicating the full path and file name of the API help file. The API looks for the help file
whenever the user invokes a help screen.
For example, if the API help screens are included in a file called PRODUCT.HLP in the C:
\PRODUCT\HELP directory set the initialization structure to the following path:
ESS_INIT_T InitStruct; InitStruct.HelpFile = "C:\PRODUCT\HELP\PRODUCT.HLP";
38
Creating Your Own On-line Help for AutoLogin
In Windows environments, the EssAutoLogin call displays a dialog box that contains a Help
button. It also provides access to other dialog boxes with their own Help buttons. Clicking the
Help button displays the Essbase System Login help topic (or the file specified in ESS_INIT_T).
If you plan to use EssAutoLogin with your own help file, then you need to include
ESSHELP.H in your help project file as follows:
[MAP]
#include <ESSHELP.H>
ESSHELP.H defines the help IDs for the dialog boxes displayed by the API. When you include
ESSHELP.H, you need to create topics in your help source files with context strings
corresponding to the strings in the header file. For example, you need to create a topic with a
context string IDH_SYSTEM_LOGIN_DB for the Login dialog box. See ESSHELP.H for a list
of context strings you should include.
If you have other context-sensitive help areas in your program, then add additional lines to the
MAP section for your additional header files as follows:
[MAP]
#include <ESSHELP.H>
#include <MYHELP.H>
API Files You Need to Ship

For your program to work with Essbase, each client machine that runs your program must have
access to the required Essbase Run-Time Client files. If the Run-Time Client is already installed,
the files are already available in the ESSBASEPATH\bin directory. Otherwise, you must install
them as part of your product's own installation process.
Note: Ensure that ESSBASEPATH is set to EPM_ORACLE_HOME\common\EssbaseRTC\11.1.

2.0 (for 32 bit), or EPM_ORACLE_HOME\common\EssbaseRTC-64\11.1.2.0 (for 64
bit).
For several platforms, you need to distribute additional Oracle run-time libraries, beyond what
is included in the Essbase Run-Time client directory (under EPM_ORACLE_HOME). The following
platforms require access to the additional libraries:
l 32-bit Windows
l 64-bit Windows
l 32-bit Linux
l 64-bit Linux
l HP-UX Itanium 64
l Solaris x86 64
l Solaris SPARC64
39
l AIX 64
The additional Oracle run-time libraries are located in %EPM_ORACLE_HOME%\bin (for

Windows) and $EPM_ORACLE_HOME/lib (for UNIX). In some installations, these run-time
libraries may instead be located in %ORACLE_HOME%\bin (for Windows) or $ORACLE_HOME/
lib (for UNIX).
On UNIX platforms, ensure that you preserve the symbolic links when distributing libraries.
General Description of Files

The Essbase API libraries can exist anywhere on the client machine or on an accessible network
file server.
To ensure that the operating system can find the libraries at run time, they should either be in
the same directory as your executable files, or in one or multiple directories included in the user's
PATH variable (for Windows), LIBPATH (for AIX), SHLIB_PATH (for HP-UX), or
LD_LIBRARY_PATH (for Solaris and Linux). See “Essbase Directory Structure” on page 35 for
more information.
The ESSBASEPATH variable needs to be set so that your program can find the .mdb files.
Optionally set ARBORPATH on the client side.
Platform-by-Platform File Lists

Users of applications programs can install the Essbase Client in order to avoid downloading
specific files. Refer to the Oracle Hyperion Enterprise Performance Management System
Installation and Configuration Guide for information on installing the Essbase Client.
See “API Libraries” on page 40 for list of linking library files. A full list of files is not provided,
as it may be subject to change.
API Libraries
The files needed to link the main, outline, and grid APIs for each supported platform are listed
below.
l Windows API Libraries (32 Bit and 64 Bit)
m ESSAPINU.LIB
m ESSOTLNU.LIB
m ESSGAPINU.LIB
l AIX API Libraries (32 Bit and 64 Bit)
m libessapinuS.a
m libessgapinuS.a
m libessotlnuS.a
l HP-UX API Libraries (32 Bit)
m libessapinu.sl
40
m libessotlnu.sl
m libessgapinu.sl
l HP-UX API Libraries (64 Bit)
m libessapinu.so
m libessgapinu.so
m libessotlnu.so
l Solaris API Libraries (32 Bit and 64 Bit)
m libessapinu.so
m libessgapinu.so
m libessotlnu.so
l Red Hat Linux API Libraries
m libessapinu.so
m libessgapinu.so
m libessotlnu.so
Installing Your Application Program

When you create an installation for your Essbase API program, you may wish to include the API
support files as part of the installation for your application. Alternately, you can install the
Essbase runtime client on the target machine and accept all the environment update options.
That process installs all the files needed by the API and sets the PATH variable.
If you decide to include the Essbase API environment setup as part of the installation of your
product, you must construct your installation process to install the files required by the Essbase
API. The exact steps required depend on your program and on the target operating system. The
following steps illustrate a typical installation process:
1. Prompt the user for the root installation drive and directory name, where root represents the
name of the installation drive and directory; for example, C:\Hyperion\products
\Essbase.
2. Create the \root and\root\bin directories.
3. Copy the product executable files to the \root\bin directory.
4. Copy any other product files to the \root directory or any sub-directories.
5. Prompt the user to choose a network protocol.
6. Copy or rename the appropriate Essbase network driver library to the \root\bin directory.
7. Copy the remaining library files to the \root\bin directory.
8. Copy the message database to the \root\bin directory.
9. In your operating system environment, define the ESSBASEPATH environment variable,
and make it equivalent to \root\. This step is necessary only if you didn't explicitly set the
client directory path in the ESS_INIT_T structure.
41
10. In your operating system environment, define the ARBORMSGPATH environment
variable, and make it equivalent to \root\bin\filename. This specifies the custom
directory path and file name for the message database. This step is necessary only if you
didn't explicitly set the message database path in the ESS_INIT_T structure or if the message
database cannot be found by using the ESSBASEPATH environment variable.
11. Include <EPM_ORACLE_HOME>/bin/ in your program's PATH. This is necessary to enable
your program to connect to Essbase. For UNIX, include <EPM_ORACLE_HOME>/lib/ in
your program's LD_LIBRARY_PATH.
Note: These instructions are appropriate for Windows client machines. Installing on other
operating systems requires slightly different steps.
Installing API Programs on Different Platforms

If you install your program on different operating system platforms, be aware that each operating
system has slightly different procedures for setting the environment variables, such as PATH,
ESSBASEPATH, and ARBORMSGPATH.
On Windows, the environment variables are set in the environment section of the Windows
System Properties. Access the system variables through the Start > Settings > Control Panel >
System > Environment tab. Adding the %ESSBASEPATH%\Bin path declaration to the path
variable on Windows is equivalent to editing the PATH statement in the AUTOEXEC.BAT file on
earlier Windows machines.
On UNIX systems, environment variables are typically set using login scripts for individual users.
The standard practice for setting these variables on UNIX is to provide a script with your
installation that sets the appropriate variables and can be included in a user's login script by the
system administrator. For more information on setting environment variables, see the Oracle
Hyperion Enterprise Performance Management System Installation and Configuration Guide.
Optimizing TCP/IP Networking for API Clients

All Essbase C-API based clients communicate with the Essbase Server by means of a network
layer. A request from a client C-API based application to Essbase involves opening a TCP/IP
socket at the start of the request and closing it at the end of the request. A socket is a resource
managed by the operating system, and there are a fixed number of such resources - the number
of which is operating-system specific. When a socket is closed, it enters a dormant state, referred
to as TIME_WAIT state, for a duration that is operating-system specific and configurable. At
the end of that time period, the socket can be reaped by the operating system for reuse. Whether
a call to open a socket succeeds or not is a function of how rapidly the operating system is able
to reap the closed sockets for reuse.
Problems may occur in cases where an API client is designed to make and conclude so many
connections, so rapidly, that the fixed number of available ports (about 64,000) is at or near
exhaustion. Because the used ports are still resting in TIME_WAIT state, available ports cannot
be harvested fast enough by the operating system, and the result is that connections are denied
or the program runs sluggishly. If a deployment expects highly concurrent processing and these
42
symptoms are occurring, we recommend decreasing the TIME_WAIT delay for the operating
system. For example, a significant performance improvement can result from decreasing the
delay from four minutes to 30 seconds.
This situation can be detected by running the command netstat on the command prompt.
The output shows the number of sockets that are in TIME_WAIT state. The higher the number,
the larger the probability that certain subsequent API requests will fail.
To get around this situation, consider reducing the TIME_WAIT value on your operating
system.
On Windows, the TIME_WAIT value is found in the Windows registry.
On UNIX, system tools such as ndd (Solaris & HPUX), no (AIX), and echo (Linux) are used to
manipulate kernel parameters.
To view and adjust the TIME_WAIT value on Solaris and HP-UX,
ndd -get /dev/tcp tcp_time_wait_interval
ndd -set /dev/tcp tcp_time_wait_interval 30000
On AIX, the following command gives a value for all parameters:

/usr/sbin/no -a
Issue the following command on AIX to set TCP_TIMEWAIT state to 30 seconds (but do not
adjust it if is already below 30):
/usr/sbin/no -o tcp_timewait =2
/usr/sbin/no -o tcp_ephemeral_low = 32768
/usr/sbin/no -o tcp_ephemeral_high = 65535
On Linux, issue the following command to set the timeout_timewait parameter to 30 seconds:
echo 30 > /proc/sys/net/ipv4/tcp_fin_timeout
43
44
Building a Simple API Program
4
In This Chapter
Introduction.................................................................................................45
Design Environment Setup Issues ........................................................................45
Basic Requirements .......................................................................................46
Assembling a Program.....................................................................................51
Introduction
This topic details implementing a simple Essbase API application, including hints and tips that
might not be apparent to a new API user.
Essbase API functions are prefixed with "Ess" for the C API. Similarly, the prefix ESS is for a data
type or constant; for example, ESS_NULL.
This tutorial refers to functional sample programs that are delivered with the API
documentation. To find the sample programs, look in /Docs/Api/Samples. The C programs
are in /Samples/Cexecs. Both the compilable source and the compiled executables are
included. See Appendix A, “API Sample Programs.”
Design Environment Setup Issues

Before you can build Essbase API programs, you must set a few configuration options in your
design environment. This discussion focuses on Microsoft Visual C++ version 6. The
configuration settings within a specific development environment are set in different ways, but
here are a couple of hints to assist in building an API program:
l Use byte-alignment for all API program structures. Note that byte-alignment is NOT the
default setting for most C compilers!
l Alternately, if you need to link your code with code that uses another alignment setting (for
example when you are using another external API), use the following #pragma directive
(only when compiling with the Microsoft C/C++ compiler):
#pragma pack(push,localid,1)
#include <essapi.h>
#pragma pack(pop,localid)
l Always compile using the large memory model (for X86 platforms).
45
l Include the header file essapi.h in all program files that use the API, and the header file
essotl.h in all files that use the outline API.
l Include the appropriate link library in your link process. Add the following library to your
project: ESSAPIN.LIB for Windows. Add the Outline API library if your program uses the
Outline API (ESSOTLN.LIB for Windows). For more information on the Essbase API
libraries, refer to “API Libraries” on page 40.
Basic Requirements
All API programs are required to perform some core operations, such as logging in. These
sections describe in detail the process of writing the shell of an application, and is meant for
programmers who are new to the Essbase API:
l “The Nested Program Model” on page 46
l “Using Function Return Codes” on page 47
l “Calling API Functions” on page 47
l “Initializing the API” on page 48
l “Logging On to a Server” on page 49
l “Connecting to a Database” on page 50
l “Logging Out” on page 51
l “Terminating the API” on page 51
The Nested Program Model

When programming using the API, your code should adopt the nested programming model. In
the nested programming model the code has calls to an initial function and a corresponding
final function. The calls are arranged as a sandwich, with the code to perform some action in
between as the filling. Consider the following example:
begin action 1
begin action 2
begin action 3
perform action 3
end action 3
begin action 4
perform action 4
end action 4
end action 2
end action 1
The implication of this arrangement is that you should ensure that you end every action or
operation that you begin. Here is a more concrete example that uses real API actions:
Initialize the API
Login to a server
Connect to a database
Open a database outline
46
Browse the outline
Close the outline
Open a report
Modify & save the report
Close the report
Disconnect from a database
Logout from the server
Terminate the API
The example above illustrates the basic structure of any code that accesses the Essbase API.
Using Function Return Codes

One of the first things you need to know is how to handle the status codes returned by API
functions. In general, a zero return code indicates successful completion and a non-zero return
code indicates an error. In the latter case, the program should abort the operation in progress
and return to the default state, only calling those API functions that are needed to clean up.
Every time a program makes a call to the API, it should check the return code and handle it
properly.
The API provides a type declaration for status return codes (ESS_STS_T) and a constant
declaration (ESS_STS_NOERR). The constant declaration can be used to test the status return
codes from API functions in an implementation-independent way.
/* C Example of checking return value from an API function */
ESS_STS_T sts;
if ((sts = EssSomeFunction (.....)) == ESS_STS_NOERR)
{
do something else;
}
else
{
process error;
}
The nested programming model is good for releasing resources if an Essbase function fails and
returns an error return value. Consider the following example:
allocate resource 1
begin action 1
allocate resource 2
begin action 2
action 2
end action 2
free resource 2
end action 1
free resource 1
Calling API Functions

Each API function has a prefix, such as Ess, followed by a verb-object naming convention; for
example, EssGetDatabaseInfo. Some functions that relate to a specific area of the product have
47
an additional prefix to indicate that relationship. For example, all the Outline API functions
have EssOtl prefixes.
All API functions take a series of arguments. The arguments are different for every function, and
follow a logical sequence. The first argument to most functions is typically a handle, either an
instance handle, a context handle, an outline handle, or a member handle. The term "handle"
refers to an identifier used by the API to keep track of different objects in the system (just like a
file handle). Different handles are returned by certain functions. Handles should then be stored
in your program and passed to other API functions when required.
For more information on the different types of API handles and their uses, refer to Chapter 6,
“Using the C Main API”.
If there are any arguments to be passed in to a function, they typically come next in the sequence.
Finally, if the function returns any values, the variables to store those returned values are passed
in at the end of the argument list.
In the following examples, the first argument is a context handle (hCtx). The next two arguments
(the application and database names, Sample and Basic), are passed in and the argument to be
returned (the database information structure, ESS_DBINFO_T) is passed in at the end:
/* C Example of passing arguments to an API function */
ESS_STS_T sts;
ESS_HCTX_T hCtx;
ESS_PDBINFO_T pDbInfo;
sts = EssGetDatabaseInfo (hCtx, "Sample", "Basic", &pDbInfo);
if (sts == ESS_STS_NOERR)
{
do something;
}
Note that the returned argument (pDbInfo) is passed to the function as a double indirection (a
pointer to a pointer) by passing the address of a declared structure pointer variable (using the
& operator). This variable is then assigned the address of a database information structure that
is allocated internally by the API function.
Initializing the API

All application programs must initialize the API (with EssInit) before using any other Essbase
functions. The program should perform the initialization only once, preferably during the
program's startup sequence.
/* C Example of initializing the API */
ESS_STS_T sts;
ESS_INIT_T InitStruct;
ESS_HINST_T hInst;
/* first clear the init structure (use API defaults) */
memset (&InitStruct, 0, sizeof (ESS_INIT_T));
sts = EssInit (&InitStruct, &hInst);
The API default settings are appropriate for most application programs. If you need to change
the settings, refer to EssInit and/or for more information on setting the individual fields of
the API initialization structure (“ESS_INIT_T” on page 135 in your program.
48
The instance handle (hInst) that is returned from EssInit should be saved within your program
for subsequent API calls. This instance handle uniquely identifies your program and its
associated resources to the API.
See Appendix A, “API Sample Programs.”
Logging On to a Server
After the API is initialized, a program must log in to an Essbase Server in order to perform any
actions on that server. Generally, a login only needs to be performed when a specific action is
requested by the user (typically a database connect operation). Note that a login to a server does
not necessarily imply a connection to a specific application or database on that server; some
administration operations do not require a connection to a particular database, and some do
not even require connection to a server.
A login can be performed using EssLogin. For Microsoft Windows only, an encapsulated login
dialog function, EssAutoLogin, is available. The dialog box displayed by this function is similar
to the one used by the Administration Services Console or Smart View. Optionally, the user can
use the dialog box to select an application and a database to connect to (see “Connecting to a
Database” on page 50). The user can also perform other operations, such as changing a
password.
/* C Example of a login using the EssLogin function */
ESS_STS_T sts;
ESS_HINST_T hInst;
ESS_SVRNAME_T Server = "Larch";
ESS_USERNAME_T Username = "Joe User";
ESS_PASSWORD_T Password = "secret";
ESS_ACCESS_T Access;
ESS_HCTX_T hCtx = ESS_INVALID_HCTX;
sts = EssLogin (hInst, Server, Username, Password, &Access, &hCtx);
The following is a similar example of logging in, this time using EssAutoLogin. When using
this function, the user supplies all the relevant information (server name, user name, password,
application, and database names) by entering the information into the appropriate fields of the
dialog box:
/* C Example of a login using the EssAutoLogin function */
ESS_STS_T sts;
ESS_HINST_T hInst;
ESS_HCTX_T hCtx = ESS_INVALID_HCTX;
sts = EssAutoLogin (hInst, ESS_NULL, ESS_NULL, ESS_NULL, ESS_NULL,
ESS_NULL, AUTO_DEFAULT, &Access, &hCtx);
See EssLogin, and EssAutoLogin.

Note that, if string variables, instead of ESS_NULL, are passed to the function as the user-entered
parameters, on return from the function those variables contain the values entered into the login
dialog box by the user.
Your program should normally login once (at the start of a user session). However, if tying up
unused server ports is a big issue, consider logging in at the start of each operation, and logging
49
out at the end of each operation (see “Logging Out” on page 51). Note, however, that this
process can slow down user response time significantly.
When using either EssLogin or EssAutoLogin, the returned login context handle (hCtx)
should be saved within your program for subsequent API calls. The login context handle
uniquely identifies that particular login to the API.
Using Local Context Handles

If you are performing API administrative operations (such as file operations) on the client
machine, you can use a dummy login context handle to represent a local login to the API. The
dummy handle can be used like a server context handle, except that most server-specific and
database-specific operations cannot be performed. Use EssCreateLocalContext to create a
local context handle. Consider the following example:
/* C Example of creating a local context handle */
ESS_STS_T sts;
ESS_HINST_T hInst;
ESS_HCTX_T hLocalCtx = ESS_INVALID_HCTX;
sts = EssCreateLocalContext (hInst, ESS_NULL, ESS_NULL, &hLocalCtx);
Connecting to a Database
Many Essbase API functions (such as server administration, security, and outline maintenance)
can be performed after the program has logged in. However, many database-related functions
(for example, reporting or performing calculations) require that the program connect to a
specific application and database. Use EssSetActive to identify a specific Essbase database.
Logging in with EssAutoLogin also allows the identification of a specific database.
Note that the user must have sufficient privileges to access the database. A list of all applications
and databases to which a particular user has access is returned by EssLogin, and can be obtained
using EssListDatabases.
If you connect to a database that is not running, Essbase automatically starts the database. It is
not necessary to disconnect from a database. However, using the same login context handle to
connect to another database will disconnect you from the original database. If you really need
to be connected to two or more databases at once, your program needs to login multiple times
(and manage each context handle independently).
/* C Example of connecting to a database */
ESS_STS_T sts;
ESS_HCTX_T hCtx;
ESS_APPNAME_T AppName = "Sample";
ESS_DBNAME_T DbName = "Basic";
sts = EssSetActive (hCtx, AppName, DbName, &Access);
The user's access level to the selected database is returned by EssSetActive (and by
EssAutoLogin). This access level can be checked by using the security constant definitions that
allow the application program to alter user options, by graying out menus, and so on.
50
Logging Out
After the user completes one or more database operations and finishes with Essbase, your
program should log out from the server. Logging out can be done either as a result of an explicit
user request or automatically (for example, after a specific sequence of actions is complete). All
active connections should also be logged out before the program terminates and exits.
It is not always necessary for the program to log out after each data access operation. Whether
to log out (and so release Essbase Server ports) or remain logged in (giving faster response to
successive user requests) is a design judgment call.
/* C Example of logging a user out */
ESS_STS_T sts;
ESS_HCTX_T hCtx;
sts = EssLogout (hCtx);
hCtx = ESS_INVALID_HCTX;
After logging out, do not use that same context handle. That will probably crash your program.
If you want to dispose of a local context handle, use EssDeleteLocalContext:
/* C Example of deleting a local context handle */
ESS_STS_T sts;
ESS_HCTX_T hLocalCtx;
sts = EssDeleteLocalContext (&hLocalCtx);
Terminating the API

At the very end of its execution, your program should terminate the Essbase API by calling
EssTerm, to ensure the proper release of all API resources. This function also logs out all active
server connections (if they are not already explicitly logged out by your program).
/* C Example of terminating the API */
ESS_STS_T sts;
ESS_HINST_T hInst;
sts = EssTerm (hInst);
hInst = ESS_INVALID_HINST;
After terminating the API, do not attempt to make any more calls to API functions. If you make
more calls, your program will probably crash.
Assembling a Program
So far in this discussion we have addressed those aspects of the API that are common to all
programs. We have not addressed the operations that the program will be designed to
accomplish. All programs require that you understand the nested programming model, pass
arguments to and from the API functions in a consistent way, interpret the function's return
codes, initialize the API, log in to a server, connect to a database, log out, and terminate. Now
we need to address the real point of the program; the program needs to perform an operation
of some kind.
51
This discussion covers the main functional groups of the C Main API. Some sections have
references to the sample programs, but the sample programs do not include all areas of the API.
The sample program loads data, reports the contents of the database, performs an update and
a calculation, and then reports the new status of the data. Comments in the code show places
where functions could be added in the future to perform additional operations.
To get some idea of the types of operations that the API can perform, take a look at the “C Main
API Function Categories” on page 194. There are almost 200 functions in the C Main API divided
into 20 functional groups. That means there is a wide variety of operations that the API can
perform. The C Outline API (78 functions) and the Grid API (59 functions) represent additional
possible complexity for an API program. The sample programs need to stay as simple as possible,
so they only use a small number of functions from the C Main API, and they do not use the
Outline API or the Grid API at all.
The sample programs use the Sample Basic database that is supplied with Essbase. The database
is delivered empty and needs to be loaded with data. The data is delivered in a text file named
CALCDAT.TXT. The sample program uses a prebuilt calc script and a prebuilt report script. The
login information used by these programs (server name, application name, database name, user
name, and password) are hardcoded into the program. The program displays the Login dialog
box, but all the fields are filled in. The user needs only to click OK in response to the dialog box.
The server name is "LocalHost". The application name is "Sample". The database name is "Basic".
The user name is "admin" and the password is "password".
Topics that discuss how to assemble a program:
l “Building Dimensions” on page 52
l “Editing the Outline” on page 53
l “Loading Data” on page 54
l “Reporting” on page 54
l “Updating Data” on page 61
l “Calculating Data” on page 62
l “Using Security” on page 63
l “Maintaining Applications and Databases” on page 64
l “Handling Messages” on page 65
l “Managing Memory” on page 66
Building Dimensions
Dimensions are the building blocks of the database. They define the database's structure
(commonly referred to as the outline or metadata). Build the database by first assembling the
necessary dimensions and each dimension's associated members. Then add the data. The outline
can be developed from scratch or an existing database can be altered by adding and subtracting
dimensions and members. The Sample Basic application/database is delivered with a complete
outline, so it is not necessary to build the outline to run the sample programs. But it is necessary
52
to load the data either through Oracle Essbase Administration Services, MaxL, or by running
the sample program.
The API can automate the process of rebuilding dimensions dynamically from a data file or SQL
source. To automate the process you must first create rules files by using Administration Services
Console and then use the rules files to build the dimensions by calling EssBuildDimension.
These functions take the rules and data file object definitions as arguments and dynamically
modify the outline on the server according to the parameters set in the rules file. They also cause
any data in the database to be restructured to correspond to the new dimension structures in
the outline.
The API can alter an existing database by adding and subtracting dimensions and members
(using the Outline API) until the needed structure is in place. After the outline is finished load
the data into the database using EssImport.
Editing the Outline

The database outline can be navigated and modified, using the outline API functions. These
functions allow movement through the outline hierarchy, modification of member information
and properties, addition and deletion of members, and so on.
Control Flow of the Outline API Functions

To begin using an outline, call EssOtlOpenOutline. If you intend to edit the outline, you
should set both of the fLock and fKeepTrans arguments to TRUE. fLock locks the outline to
prevent anyone else from updating it (but not from viewing it). fKeepTrans saves all transactions
performed during the edit of the outline, for when the outline is subsequently restructured.
To start navigating the outline from the first dimension member, call
EssOtlGetFirstMember. Alternately, you can locate a member by name by using
EssOtlFindMember or EssOtlFindAlias. In either case, the function returns a member
handle that can then be used to get or set information about that member or to get the member
handles of adjacent members in the outline hierarchy.
53
To get information about the current member, use EssOtlGetMemberInfo,
EssOtlGetMemberAlias and EssOtlGetMemberFormula. To set information for the current
member, use the corresponding Set functions.
To get the parent of a member, call EssOtlGetParent. To get the first child of a member, call
EssOtlGetChild. To get the siblings of a member, call EssOtlGetNextSibling or
EssOtlGetPrevSibling. To locate the next shared occurrence of a member, call
EssOtlGetNextSharedMember.
To add or delete dimensions in an outline, use EssOtlAddDimension or

EssOtlDeleteDimension.
To modify members in the outline hierarchy, use EssOtlAddMember,

EssOtlDeleteMember, or EssOtlMoveMember.
After an outline is modified, it can be verified using EssOtlVerifyOutline, saved using

EssOtlWriteOutline, and then closed using EssOtlCloseOutline.
Before any changes made to a server outline can take effect, the database must be restructured
by calling EssOtlRestructure. This function applies the edits made to the outline against the
old version of the outline and restructures both the outline and the associated data.
Loading Data
After the outline dimensions are built, data can be loaded into the database through the API.
The data load can be done by using a data file or a SQL source together with a rules file, by
loading a free-form data file, or by loading free-form data a record at a time.
To load by using a rule with either a data file or an SQL source, use EssImport. Pass valid rules
and data file object definitions as arguments. To load a free-form data file without a rules file,
simply pass a NULL rules file object definition.
To load data a record at a time, call EssBeginUpdate with the Unlock argument set to FALSE,
and then call EssSendString with each record of data to be loaded. This method avoids the
need to lock the blocks being updated. This mechanism should be used only for batch data
loading. Do not use this mechanism in multi-user situations. The lack of locking can compromise
data integrity.
Note also that each record sent to the server by this method must have a terminating newline
character at the end of each row.
Reporting
Reporting in the Essbase API requires the use of a report script. The report script is sent through
the API to the Essbase Server and is executed. The results are sent back through the API to the
caller. The resulting output data can be displayed, printed, sent to a file, and so on. It can also
be parsed and stored in an array data structure within your program.
Topics that discuss reporting:
l “Creating a Report Script” on page 55
54
l “Executing a Report Script” on page 57
l “Parsing the Report Output” on page 58
l “Using Report Output as a Script” on page 59
l “Using Report Output to Perform Zoom Operations” on page 60
l “Creating Tabular Format Report Output” on page 61
Creating a Report Script

A report script is a text string that contains data extraction and data formatting commands
required to generate output from the Essbase Server. See the Oracle Essbase Technical
Reference for a full description of the Report Writer language. The following principal elements
generally need to be included in a report script for an API application:
l {TABDELIMIT} command—Include at the beginning of any report script sent to the API.
It causes the output data to be returned in a format useful for parsing within a program.
This command suppresses all unnecessary formatting (for example the commas used as
thousand separators in numbers) and returns each member name or data value as a tab-
separated token, that can be parsed and divided into cells.
l {DECIMALS n} command—Specifies the decimal precision of the returned numeric data
(all numbers are stored internally as floating point numbers with 15 digits of precision). For
example, {DECIMALS 2} gives two digits of decimal precision.
l {INDENTGEN n} command—Allows a program the option of indenting either parent
members or child members in the rows of the report output. A negative value of n indents
parent members by n spaces relative to their children. A positive value of n indents the child
members by n spaces relative to their parents. A zero value of n turns off all indenting. For
example, {INDENTGEN -2} indents parent members by two spaces per level (the default):
100-10 47 41 50 138
100-20 44 38 49 131
100-30 21 14 20 55
100 112 93 119 324
200-10 25 19 23 67
200-20 18 14 18 50
200-30 17 9 14 40
200 60 42 55 157
Product 287 217 290 794
l {SUPMISSING} and {SUPZERO} commands—Eliminates unnecessary rows in the report
output. The {SUPMISSING} command suppresses the output of all data rows that contain
only #Missing values (that is, no actual data), and the {SUPZERO} command suppresses
the output of rows that contain only zero values.
Also useful are the {SUPBLANK} command, that suppresses both zero and #Missing values,
and the {SUPALL} command, that suppresses a range of report output parameters.
l {MISSINGTEXT string} command—Converts #Missing values in the output data to a string
specified by the program. For example {MISSINGTEXT "N/A"} converts any #Missing
values to the string "N/A".
55
l {OUTALTNAMES} or {OUTMBRNAMES} commands—{OUTALTNAMES}enables you
to use alias names instead of member names in the output. To revert to member names, use
{OUTMBRNAMES} (the default).
l <PAGE, <COL and <ROW commands—Specify how the different dimensions are oriented
in a report. <PAGE specifies which dimensions are in the page header (at the top of the
report), and <COL and <ROW specify that dimensions are in the columns and rows,
respectively. For example, <ROW(Market, Product) forces the members of the Market and
Product dimensions to be displayed in that order in the rows of the report.
Any member from any dimension can be specified in <PAGE, <COL, and <ROW. Each
dimension should appear in only one of these commands, otherwise the last command takes
precedence, and all dimensions should be specified (or the report layout will be
unpredictable).
l List of member names (including any macro commands)—To extract the data required in
the report by the simplest method, list the members concerned. For example, "Actual Sales
Ohio Jan Feb Mar Product" produces the following report output:
Actual Sales Ohio
Jan Feb Mar
Product 287 217 290
Alternately, you can use macro commands to specify a range of members from a dimension.
Consider the following example:
m <CHILDREN / <ICHILDREN
m <DESCENDANTS / <IDESCENDANTS
m <DIMBOTTOM
m <ALLINSAMEDIMENSION
m <ONSAMELEVELAS
m <PARENT
m <ANCESTORS
Note: All the above macro commands can be abbreviated, for example, <DESC, <ICHILD,
and <PAR.
The most commonly used of the above macro commands are <CHILD (or <ICHILD) to
perform a single level drill-down; <DESC (or <IDESC) to perform multilevel drill-downs,
and <DIMBOTTOM to drill down to the lowest level members of a dimension.
For example, "Actual Sales Ohio <ICHILD Qtr1 <DESC Product" produces the following
report output:
Actual Sales Ohio
Jan Feb Mar Qtr1
100-10 47 41 50 138
100-20 44 38 49 131
100-30 21 14 20 55
100 112 93 119 324
56
200-10 25 19 23 67
200-20 18 14 18 50
200-30 17 9 14 40
200 60 42 55 157
300-10 30 19 32 81
300-20 24 16 25 65
300-30 12 7 11 30
300 66 42 68 176
400-10 30 27 32 89
400-20 14 10 12 36
400-30 5 3 4 12
400 49 40 48 137
100-20 44 38 49 131
200-20 18 14 18 50
300-30 12 7 11 30
Diet 74 59 78 211
Because member names can be numbers (for example, "100") and can contain embedded
spaces (for example, "New York"), it is always a good practice to surround member names
with double quotation marks when sending a report script to the API. You can force member
names to be output in this format by using the {QUOTEMBRNAMES} command.
l Bang (!)—The final element of a report script must always be a bang (!), the exclamation
point character. Each script must have one (at least one) bang to cause data to be generated.
If a report script appears to be executing correctly but no data is output, check to make sure
that you are appending a bang to the report script.
Many of these elements are typical user-configurable parameters that are set up in advance by
the user, either globally or per-report (or both).
See “API Libraries” on page 40.
Executing a Report Script

A report script can be executed in one of three ways:
l By passing it as a string to EssReport
l By passing a set of strings with EssBeginReport, EssSendString, and EssEndReport
l By specifying a report script file with EssReportFile
All of these methods send the report specification to the server for processing. The output from
the server is then returned to the client, and you must read all the output from that report before
calling other API functions with the same context handle.
57
Control Flow of the Reporting Functions
To execute a report, you can call EssReport and pass the report script as a single string. Set the
Output argument to TRUE and the Lock argument to FALSE, unless you are performing a lock
and send operation.
Alternately, call EssBeginReport (setting the Output and Lock arguments as above), and then
call EssSendString to send the report script a string at a time. Finally, terminate the report
sequence with a call to EssEndReport.
To execute a report script from a file, call EssReportFile.
To get the report output, call EssGetString repeatedly to read the returned strings, until a null
pointer value is returned.
Parsing the Report Output

To parse the data returned from a report, you first need to understand the report's format. If
you included the {TABDELIMIT} command in the report script, the data comes back in the
following format:
<token><tab><token><tab><token><tab>..........<token><newline>
<token><tab><token><tab><token><tab>..........<token><newline>
.....
<token><tab><token><tab><token><tab>..........<token><null>
For example, consider the following report script:

{SSFORMAT}{DECIMAL 0} <COL(Year) <ROW(Market) Budget Sales Cola <CHILD Qtr1 <ICHILD
Market !
This report script would normally output data that looks like the following:
Budget Sales Cola
Jan Feb Mar
East 5200 5000 5300
West 5600 5350 5700
Central 4250 4050 4400
58
South 3800 3450 3800
Market 18850 17850 19200
When you include the {TABDELIMIT} command, the report script outputs the data as follows:
<tab>Budget<tab>Sales<tab>Cola<newline>
<tab>Jan<tab>Feb<tab>Mar<newline>
East<tab>5200<tab>5000<tab>5300<newline>
West<tab>5600<tab>5350<tab>5700<newline>
Central<tab>4250<tab>4050<tab>4400<newline>
South<tab>3800<tab>3450<tab>3800<newline>
Market <tab>18850<tab>17850<tab>19200<null>
To parse data in this format, scan the returned string for a tab, a newline, or a null, each of which
define the end of a token. The token can be one of four types:
l A member name (must begin with an alphanumeric character)
l A data value (must always begin with a number or a negative sign)
l A special value, such as #Missing (must begin with a # character)
l An empty cell (none of the above)
If the report is stored in an internal data structure, such as a grid or array, and the report shrinks
in the number of rows or the number of columns (for example, after a zoom out operation),
you might need to adjust the bounds of the new report.
The possible conflict between numeric values and numeric member names can usually be
resolved by scanning any tokens that begin with a number and validating that they conform to
the parameters (for example, decimal precision) of a number value. Any token that does not
conform should be treated as a member name.
A more reliable method is to use the positioning of the token in the report to determine whether
it is a member name or a data value. The first x rows of the report can be only member names
(where x is the number of column dimensions + 1 row for the page header), and the first y
columns can only be member names (where y is the number of row dimensions). If the
coordinates of the token are greater than both x and y, then the token is either a special value
(begins with a # character), or it is a number value.
It is possible to force double quotation marks around all member names (and so avoid the
identification issue) by using the <QUOTEMBRNAMES command. When you use this
command, you can recognize member names by the leading double quotation marks.
It is often useful to parse the returned report output tokens into Page, Column, Row and Data
areas, so they can be easily re-used in subsequent reports (see Using Report Output as a Script,
below).
Using Report Output as a Script

The output from a report script can be used as the input to another report. The report output
contains only member names and data, so you need to preface the new report with the header
commands (as described above). Then append the member names output by the previous report
onto the report header (not including the returned data, to avoid sending unnecessary
59
information to the server), and execute that as a script. For example, if you first execute the
following:
<COL("Year") <ROW("Market")
"Actual" "Sales" "Cola" <CHILD "Qtr1" <CHILD "East"
!
The resulting report output might look something like the following:
Actual Sales Cola
Jan Feb Mar
New York 36 32 39
Massachusetts 24 09 14
Florida 37 29 37
Connecticut 0 5 11
New Hampshire 12 10 11
Now if you send the header from the previous report (that is, the first two lines of format
commands), strip out all data from the report output, surround all member names with double
quotation marks, and append a bang (!) character, you should get the following report script:
{TABDELIMIT}{DECIMALS 0} <PAGE("Scenario", "Measures", "Product") <COL("Year")
<ROW("Market")
"Actual" "Sales" "Cola" "Jan" "Feb" "Mar" "New York" "Massachusetts" "Florida"
"Connecticut" "New Hampshire"
!
This script now generates the same report that the first script generated. This method is useful
when performing a series of ad-hoc operations, such as drill-downs, on a view.
Essbase inserts spaces before certain member names. What is inserted depends on the
<INDENTGEN report setting. Leading spaces must be removed if the members are subsequently
used as part of a report script.
Using Report Output to Perform Zoom Operations

To perform a simple (one-level) zoom in on a member in a view, send the output from the report
that created the view as a script with the <CHILD (or <ICHILD) command before the member
to be zoomed on. To perform a multilevel zoom in, use the <DESC or <IDESC commands. To
perform a zoom out, use the <PARENT (or possibly the <ANCESTORS) command.
For example, consider the following report output:
Actual Sales Cola
Jan Feb Mar
East 109 85 112
If the user chooses to drill down on East, the report script might be as follows:
{SSFORMAT}{DECIMALS 0} <PAGE(Scenario, Measures, Product) <COL(Year) <ROW(Market)
Actual Sales Cola Jan Feb Mar <ICHILD East
!
This script generates the following report output:

Actual Sales Cola
Jan Feb Mar
60
New York 36 32 39
Massachusetts 24 09 14
Florida 37 29 37
Connecticut 0 5 11
New Hampshire 12 10 11
East 109 85 112
Creating Tabular Format Report Output

It is possible to force the output of a report to be in a tabular format that resembles a relational
database query. The Report Writer commands to achieve this format are as follows:
l {ROWREPEAT} command—Causes the full list of member names to be output on each
row of the report, even when there are nested groups. In the following example, Ohio is
repeated on each row:
Actual Sales
Jan Feb Mar
Ohio 100-10 130 121 134
Ohio 100-20 118 104 123
Ohio 100-30 77 65 81
l {SUPCOLHEADING} command—Adding this command to the report suppresses the
column headings in the report output.
Actual Sales
Ohio 100-10 130 121 134
Ohio 100-20 118 104 123
Ohio 100-30 77 65 81
l {SUPHEADING} command—Adding this command also suppresses the page headings in
the report output. As shown in the following example:
Ohio 100-10 130 121 134
Ohio 100-20 118 104 123
Ohio 100-30 77 65 81
Also, all of the dimensions (or all but one) need to be included in the <ROW command in the
report, to ensure that the data is returned in a fully normalized form.
Updating Data
Updating data is the process of changing data in a view, and sending the data back to the server.
When the update is in progress the user must lock the blocks that relate to the view. This ensures
that no other user can change the data between the time the program retrieves that data and the
time the data is written back to the database.
The sequence of actions for an update is as follows:
1. Execute a report script to lock the relevant blocks and retrieve the data to be updated
2. Change some or all of the data in the view
3. Send the data back to the server and unlock the blocks
61
Control Flow of the Update Functions
Lock the blocks with EssReport or EssBeginReport. Make sure to set the Lock argument
passed to these functions to TRUE, locking all the blocks relating to the retrieved data. These
functions can either lock the blocks and retrieve the data or just lock the blocks (if the data is
either new or already current). The functions lock the blocks without retrieval by changing the
value of the Output argument passed to them to TRUE or FALSE, as appropriate.
Next, allow the user to edit the data cells in the view (using whatever mechanism your product
provides).
Finally, call EssUpdate and pass it the entire contents of the view (including the updated data
values), or call EssBeginUpdate, and send the entire view to the server a string at a time by
calling EssSendString.
Each string sent to the server must have a newline terminating each line of the update
specification.
To execute an update from a file, first lock the blocks as described above and then call
EssUpdateFile.
Calculating Data
To calculate data in Essbase means to consolidate part or all of the database by using either the
hierarchies and formulas defined in the database outline (the default calculation), or the
formulas contained in a calc script.
62
Control Flow of the Calculation Functions
The default calculation is stored in the database and is executed by calling EssDefaultCalc.
To get and set the script used for a default calculation, use EssGetDefaultCalc and either
EssSetDefaultCalc or EssSetDefaultCalcFile.
Like reports, calculations can be executed in one of three ways:

l By passing the calc specification as a string to EssCalc
l By passing a set of strings with EssBeginCalc, EssSendString, and EssEndCalc
l By specifying a calc script file with EssCalcFile
Calculations in Essbase are asynchronous operations, meaning that when the appropriate calc
function is called, the API returns to the caller immediately without waiting for the calc to finish
(unlike executing a report, for example). Essbase uses asynchronous calculations because a
calculation can take a significant amount of time to complete (several hours is not uncommon).
So, after the calculation starts, the program must check (by calling EssGetProcessState) at
intervals to see if the calculation is complete.
The simplest way to check is to set up a system timer to wake up a process at short intervals (say
5-10 seconds), checking the status of the calculation. While the calculation is running you can
perform any other operations within your program, but you can not make function calls to the
Essbase API using the same context handle.
Using Security
All the capabilities provided by Administration Services for administering security are available
through the Essbase API. To fully understand the workings of the security system, refer to the
Oracle Essbase Database Administrator's Guide.
63
Many of the functions that use the security system require certain privileges to be available to
the logged in user and return errors if an attempt is made to change security information without
the correct authority. Typically, the logged in user should have Administrator or Application or
Database Manager privileges, but you should be aware of possible problems if you are using the
security functions and should plan for such errors, particularly during your initial testing.
To create or delete users or groups in Essbase, use EssCreateUser and EssDeleteUser. To
set a user's password, use EssSetPassword. To get a list of users on a server, use
EssListUsers.
To get and set a user's or a group's security information, call EssGetUser and EssSetUser.
To get and set the list of users that are members of a group (or the list of groups to which a
member belongs), call EssGetGroupList and EssSetGroupList.
To get user access privileges to an application, call EssGetApplicationAccess.
The security functions can return the names of all the users who have access to a named
application, all the applications to which a named user has access, or the access level of a specific
application-user combination. A similar function exists for databases, and corresponding Set
functions exist for setting application and database access.
To get the contents of a named security filter, first call EssGetFilter then repeat calls to
EssGetFilterRow (to get each row description in the filter) until a NULL string is returned.
To set the contents of a filter, first call EssSetFilter, and then repeat calls to
EssSetFilterRow until all rows have been sent (send a NULL row pointer to terminate the
sequence).
To get a list of the named filters in a database, call EssListFilters. To get a list of users who
are assigned a named filter, use EssGetFilterList.
For detailed descriptions of the security-related functions, see “C Main API Security Filter
Functions” on page 206.
Maintaining Applications and Databases

Apart from maintaining database outlines, there are some other administrative functions that
can be performed with the API.
To get information about an application, use EssGetApplicationInfo. To get modifiable
application state parameters, call EssGetApplicationState (a corresponding Set function
also exists to update these parameters). Similar administrative functions exist for databases.
When using any of the application or database Set functions, call the corresponding Get function
first to initialize the structure fields.
To get an application log file, call EssGetLogFile.
To get a selection of database run-time statistics, call EssGetDatabaseStats. To get or set a
database note (a text string that can be viewed from the default login dialog box), use
EssGetDatabaseNote and EssSetDatabaseNote.
To export part or all of a database into a text file format that can be reloaded into databases, use
EssExport.
64
To move Essbase file artifacts (outlines, calc scripts, rules files, and so on) between applications
or databases, use EssCopyObject. To move artifacts between the client and server for editing,
use EssGetObject and EssPutObject.
To create an artifact, call EssCreateObject. To rename an artifact, call EssRenameObject.
To delete an artifact, call EssDeleteObject. To list all artifacts of a particular type within an
application or database, call EssListObjects.
For detailed descriptions of using the administration functions for database and application, see
“C Main API Database Functions” on page 196 and “C Main API Application Functions” on
page 195.
See “API Libraries” on page 40.
Handling Messages
The API includes a mechanism for intercepting error messages and other messages generated at
the server and for displaying the appropriate messages automatically on the client program's
screen. This mechanism, although generally useful, can be turned off if desired. The API allows
your program to prevent those messages from appearing and to trap them for processing within
your program. You can choose which messages to display and then display the messages in a
way that is consistent with your program's internal message and error handling. This mechanism
provides seamless integration of Essbase with your program.
The default message processing in Essbase is platform-dependent, but typically generates a dialog
box with the log information (application and database name, username, timestamp, and so on)
and the message text.
Every Essbase message has a unique identification number, a message level number, and an
associated text string (that is not necessarily unique). By default, Essbase displays error messages
only for serious errors, not for warnings and not for information messages.
Message Handling in C
In the C API, you can define a Custom Message Handling function and pass a pointer to that
function during the initialization call, EssInit(). This custom function is then called when the
API receives a message from the server. The custom function can examine the function return
code either to process the message internally or to pass the message back to the API for default
message processing. For more details see, “C Main API Message Handling” on page 79.
An example of a message handling function for Windows and C is given below:
/* C Example of a message handling function */
ESS_FUNC_M ErrorHandler (ESS_PVOID_T myCtx,
ESS_LONG_T MsgNum,
ESS_USHORT_T Level,
ESS_STR_T LogStr,
ESS_STR_T MsgStr)
{
ESS_STS_T sts = 0;
ESS_STR_T ErrorStr;
ESS_USHORT_T len;
HANDLE hMem;
/* Only display messages of level ERROR or above */
65
if (Level >= ESS_LEVEL_ERROR)
{
/* Calculate combined length of Log and Message strings */
len = 3; /* allow for end of line characters + null */
if (LogStr != NULL)
len += strlen (LogStr);
if (MsgStr != NULL)
len += strlen (MsgStr);
/* Concatenate the strings */
if ((hMem = GlobalAlloc (GPTR, len)) != 0)
{
ErrorStr = GlobalLock (hMem);
sprintf (ErrorStr, "%s\n%s", LogStr, MsgStr);
/* Display message in a Windows message box */
MessageBox ((HWND)NULL, ErrorStr, "Essbase Error",
MB_OK);
GlobalUnlock (hMem);
GlobalFree (hMem);
}
}
return (sts);
}
Managing Memory
In the C API, it is possible to define custom memory management functions for use within the
API itself, so that you do not have any conflict between your internal memory management
scheme and the memory management scheme of the API. Again, custom functions provide
integration of the API into your program.
First, you need to write three functions within your code:
l A memory allocation function.
l A memory freeing function.
l A memory reallocation function.
Next, you need to pass pointers to these three functions to the API during the initialization call,
EssInit. The functions are then used within the API whenever the API needs to allocate, free, or
reallocate a memory buffer. Any items that are allocated within the API and returned to your
program are guaranteed to have used these functions, so you can reallocate or free them without
any possibility of a memory corruption or violation.
For more information on using custom memory management with the API, see “Using Memory
in C Programs” on page 78.
66
Unicode Issues in Essbase API
5 Programs
In This Chapter
General Programming Considerations ...................................................................67
Defining Unicode Mode Client Programs ................................................................67
Specifying the Byte Order Encoding......................................................................69
Unicode Mode and Essbase Server ......................................................................70
Unicode Outlines...........................................................................................71
Grid API .....................................................................................................71
General Programming Considerations

Only Unicode mode clients can fully work with Unicode mode applications. In general, writing
Essbase applications programs for Unicode must take into account the mode of the client and
of the server. The assumption made for this discussion is that the Essbase Server is fully Unicode
enabled, that is, the Essbase Server is the latest version.
There are three basic scenarios depicting three types of client communicating with the Unicode
enabled Essbase Server. The three client types:
l Non-Unicode client program communicating with the Unicode server
l Unicode-enabled client in non-Unicode mode communicating with the Unicode server.
l Unicode-enabled client communicating with the Unicode server.
Unicode enabled programs in non-Unicode mode can access all data on Unicode servers, but
can not change the database outlines for Unicode mode applications. Only Unicode enabled
client programs operating in Unicode mode have full access to both the data and the database
outlines on Unicode enabled servers.
Defining Unicode Mode Client Programs

Only Unicode-mode client programs can communicate with the server using UTF-8 encoded
data. To initialize a Unicode mode client program, use theusApiType field of the ESS_INIT_T
structure passed to EssInit(). This field has two possible values: ESS_API_NONUNICODE and
ESS_API_UTF8.
This API initialization function is the only place to specify the mode of an application program.
This topic contains the following sections:
67
l “Non-Unicode Clients” on page 68
l “Unicode-enabled Clients in Non-Unicode Mode” on page 68
l “Unicode-enabled Clients in Unicode Mode” on page 69
l “Specifying Unicode Mode” on page 69
Non-Unicode Clients
The non-unicode clients are the older clients were built to work with previous version of the
Essbase API. These clients deal entirely in short strings and non-unicode encoding. These older
clients cannot deal with the longer strings and are, therefore, restricted to dealing with non-
Unicode-enabled applications.
This type of client can not edit the outlines or rules files on a Unicode mode server.
A Unicode-enabled server can communicate in non-Unicode mode with non-Unicode clients.
The non-Unicode clients can edit outlines and rules files while not connected to a server.
However, encoding can be an issue for non-Unicode clients editing rules files and for Unicode
clients editing rules files and outlines.
When editing rules files or outlines a Unicode mode server, the user can select the format of the
output file or let it default to being the same as the input file. The permissible output file formats
are:
l Non-Unicode format - short strings and non-Unicode encoding
l Unicode format - long strings and UTF-8 encoding
The files are edited internally in non-Unicode encoding by non-Unicode clients and in Unicode
encoding by Unicode clients.
If the input file is to be converted from Unicode format to non-Unicode format, but cannot be
converted because it contains strings that are too long, then the conversion is aborted and a
diagnostic is returned to the user.
Unicode-enabled Clients in Non-Unicode Mode

Unicode-enabled clients are built with the include files and DLLs of Unicode-enabled Essbase,
but communicate with the API in native encoding. The API does not support placing client API
DLLs from Unicode-enabled Essbase onto a client that is built with include files from non-
Unicode Essbase. Clients must be built with the Unicode-enabled Essbase include files in order
to run with the new DLLs.
Unicode-enabled clients in non-Unicode mode cannot edit the outlines or rules files on a
Unicode mode server.
To work with the Unicode-enabled include files and DLLs, a client must support the longer
maximum string lengths. For some clients, this may be as simple as recompiling with the
Unicode-enabled Essbase include files that define the longer maximum lengths.
68
For other clients, supporting the longer maximum lengths may require code changes. For
instance, a client may use a single byte for storing the member name byte length. Because one
byte is not enough to hold the new maximum byte length for member names (320 bytes), the
design must be changed to allow the client to support the longer maximum lengths.
Unicode-enabled Clients in Unicode Mode

Unicode clients are built with Unicode-enabled Essbase and communicate with the API in
UTF-8.
To run as a Unicode client, a client must handle long maximum string lengths, as described in
the previous subsection on new native clients. In addition, the client must communicate with
the API in UTF-8.
If a client is written in Java, the conversion may be easier than if the client is written in another
language. However, in either case, the changes are likely to be substantial. For instance, the client
code must communicate with the operation system in non-Unicode encoding while
communicating with the Essbase API in Unicode mode.
Specifying Unicode Mode

The initialization structure, ESS_INIT_T, is the only place that you can specify the Unicode-
related mode of the client program. If nothing is specified, the program operates in non-Unicode
mode. Use the usApiType field to specify the mode.
Specifying the Byte Order Encoding

Unicode clients using the C Main API to communicate with Unicode-enabled Essbase
applications must send the UTF-8 encoded Unicode byte order mark (BOM) in the text stream
immediately after calling any of the following functions:
l EssBeginReport
l EssBeginUpdate
l EssBeginDataload
l EssBeginDataloadASO
l EssBeginDataloadEx
l EssBeginStreamBuildDim
l EssBeginCalc
To send the BOM, use EssSendString, as shown in the following examples:
void ESS_BeginUpdate()
{
ESS_STS_T sts = ESS_STS_NOERR;
ESS_BOOL_T Store;
69
ESS_BOOL_T Unlock;
ESS_STR_T query = "";
/* Begin Update */
Store = ESS_TRUE;
Unlock = ESS_FALSE;
sts = EssBeginUpdate (hCtx, Store, Unlock);
printf("EssBeginUpdate sts: %ld\n",sts);
/* Send update specification */
//String with BOM characters
query = "\xEF\xBB\xBF 'marché' 'New York' 'Actual' 'Sales' '100-10' 5";
if(!sts)
sts = EssSendString(hCtx, query);
/* End Update */
if(!sts)
sts = EssEndUpdate(hCtx);
}
void ESS_BeginReport()
{
ESS_STR_T rString = ESS_NULL;
ESS_STR_T query = ESS_NULL;
sts = EssBeginReport (hCtx, ESS_TRUE, ESS_FALSE);
printf("EssBeginReport sts: %ld\n",sts);
if(!sts)
{
//String with BOM characters
query = "\xEF\xBB\xBF 'New York' 'Actual' 'Sales' '100-10' 'marché' 'Jan' !";
sts = EssSendString(hCtx, query);
}
if(!sts)
sts = EssEndReport (hCtx);
if(!sts)
sts = EssGetString(hCtx,&rString);
while ((!sts) && (rString != NULL))

{
printf("%s", rString);
EssFree (hInst, rString);
sts = EssGetString (hCtx, &rString);
}
printf("\n");
}
Unicode Mode and Essbase Server

Essbase Server allows the creation of Unicode mode applications, or migration of non-Unicode
mode applications to Unicode mode, only when it is in Unicode mode.
For more information, see “C Main API Unicode Mode Functions” on page 210.
70
Unicode Outlines
For functions related to working with Unicode mode outlines, see “C Outline API Unicode Mode
Grid API
To initialize a Unicode mode client program utilizing the Grid API, use the usApiType field of
the ESSG_INIT_T structure which is passed to EssGInit(). Additionally, ESSG_DATA_T has
additional values for the usType field to work in Unicode mode..
71
72
Part II
C Main API
In C Main API:
l Using the C Main API

l C Main API Declarations
l C Main API Functions
73
74
Using the C Main API
6
In This Chapter
C Main API Instance Handles .............................................................................75
C Main API Context Handles ..............................................................................76
C Main API File Objects....................................................................................76
Using Memory in C Programs .............................................................................78
C Main API Message Handling............................................................................79
Choosing a Network Protocol .............................................................................82
Calling C Main API Functions .............................................................................82
Typical C Main API Task Sequence .......................................................................83
Initializing the C Main API .................................................................................84
Logging in to an Essbase Server..........................................................................84
Selecting an Active Application and Database..........................................................84
Retrieving and Updating Data ............................................................................85
Recalculating the Database...............................................................................86
Logging Out from the Essbase Server and Terminating the C Main API...............................87
C Main API Common Problems and Solutions ..........................................................87
C Main API Instance Handles

An instance handle (similar in concept to a file handle) represents a program's access to the API,
and distinguishes the program-specific resources and settings used within the API. This
identification is necessary for dynamic shared libraries, which may be accessed by several
different programs simultaneously. When a program initializes the API by calling EssInit(), an
instance handle is returned.
Using the Instance Handle in an Application

An instance handle is declared as type ESS_HINST_T in C programs.
The instance handle must be passed to the EssLogin() call, which returns a context handle, and
also to the API terminate function EssTerm() to free any program-specific resources used within
the API.
Instance handles may be passed to other programs, child processes, or threads, which can then
log in independently of the original using the same API resources and settings. Make sure that
75
all programs, processes or threads using the same instance handle log out before they can
terminate the API.
Note: A thread may require its own instance handle (phInstance) to avoid overwriting another
thread's networking status information.
C Main API Context Handles

A context handle represents a single, valid login by a user onto the system. A successful call to
EssLogin() returns a context handle, which can be passed to other API calls which require a
context handle as an argument:
l Using context handles in an application—Context handles are defined as type
ESS_HCTX_T in C programs. In general, a context handle is valid for as long as the user
remains logged in to that server (that is, until after a successful EssLogout() call). However,
in case such as a server shutdown, a context handle can become invalid. Your program should
therefore provide some way for the user to log back in during a session (for example, through
a menu option or function key).
Note: A context handle is specific to an instance of the API, and contains an implied
reference to the resources and settings for the appropriate instance.
l Multiple context handles—A single instance of an API program may make multiple calls to
EssLogin(), using the same user name or different user names on one or more Essbase
servers. Each call to EssLogin() returns a unique context handle, and your program must
keep track of each context handle returned. You may have up to 255 context handles per
client application in use simultaneously, but if a program performs all its processing on a
single server, in general it is easier to use only one context handle and to switch between
different applications and/or databases as required, using either the EssSetActive() function
or the EssAutoLogin() function.
l Sharing context handles—In general, it is not advisable to share context handles between
multiple programs, processes, or threads, unless such use is guaranteed to be exclusive. A
better approach is to use the same instance handle and log in each process or thread
separately.Essbase ensures that multiple logins using the same user name on the same server
will only occupy one port on that server.
l Local context handles—Operations on local objects and files (on the client) can use a local
context handle (see Using Local Context Handles).
See also Local Contexts.
C Main API File Objects

An Essbase object is simply a file (in 8 by 3 alphanumberic character format) Essbase uses, such
as a database outline, a calc script, or other data.Essbase has an object system which allows you
to refer to such files through the API simply by the name, the file type, and the application and
76
database with which they are associated. This allows objects to be manipulated independently
of the underlying file system (which may vary between different platforms and implementations
of Essbase).
Objects can reside on any Essbase Server or client, and can be copied between them. A locking
mechanism on the server controls access to objects, so that users with sufficient privilege can
lock server objects and copy them to the client (using the EssGetObject() function), edit them,
and save them back to the server (using the EssPutObject() function). Server objects can also
be opened without locking for read-only access, but then cannot be saved back to the server. A
user can also create or edit objects on client workstations for their personal use, or save them to
the server for other users to share.
Accessing Objects
When you access objects through the API, the object name refers to the file name of the object
(without an extension). The object types are declared in the API header file in the form
ESS_OBJTYPE_xxx (where xxx represents the specific type, as in ESS_OBJTYPE_REPORT).
Most objects are associated with an application and database, but some objects such as calc
scripts and rules files can be stored at the application level and used with any database within
the application.
Database outline files are different from other objects, and cannot be deleted, renamed, copied,
or saved using the API.
Server object files are physically located in the corresponding application or database sub-
directory. However, it is not generally advisable to manipulate server object files directly. Always
use the appropriate API functions to copy the files locally.
Client object files are also stored by default in application and database sub-directories of the
directory specified by the LocalPath setting of ESS_INIT_T. You can freely manipulate and edit
these files, but you should ensure your program is well-behaved when locking and unlocking
server objects which are being edited on the client (always lock an object before editing and
unlock it afterwards, whether or not changes are saved).
You can bypass the client object system and go directly to the file system by setting the application
and database to NULL. This makes the object field the entire path.
Local Contexts
If you intend to access file objects on a client machine through the API, you need to create alocal
context handle for the API object functions to use. To create a local context, use the
EssCreateLocalContext function, which returns a context handle. This handle can be passed
to any of the object API functions instead of a login context handle, and causes the API to perform
the requested operation on the local client object system instead of the server. You only need to
create a local context once, immediately after your program first initializes the API.
If you create a local context, your program should clean up by calling the
EssDeleteLocalContext function before terminating the API.
77
Using Memory in C Programs
All programs perform some form of memory allocation. The Essbase API allocates memory
internally, some of which is returned in the form of pointers to the calling program. The calling
program can also allocate memory, which is passed as pointers to the API. To avoid potential
conflicts between different memory management schemes, the API provides two mechanisms
for integrating the memory management in your application:
l Use the API's memory management scheme in your application
l Customize the API to use your application's memory management scheme internally
Using the C API's Memory Management Scheme

The API provides a set of memory management functions, EssAlloc(), EssRealloc(), and
EssFree(). These functions (plus all internal API memory allocations) call memory allocation
routines pointed to by the AllocFunc, ReallocFunc, and FreeFunc fields of the
ESS_INIT_T initialization structure. If you pass NULLs into these fields, you use the default
allocation routines supplied with the API, which use native memory application routines
appropriate to the target platform.
The native memory allocation routines called by all platforms call the C standard library calls
malloc(), realloc(), and free(). The C standard library calls accommodate the operation of the
Outline API, which uses many small allocations of memory during normal usage. Unlike
GlobalRealloc(), realloc() does not initialize new buffer areas to NULLs.
Note: If you are using a compiler for an Intel X86-based Microsoft Windows platform,
remember that the API exclusively uses the large memory model.
Customizing the Memory Management Scheme

If you do not want to call the API's memory management functions, or you want to ensure that
the same allocation scheme is used consistently throughout your application, you can define
your own set of memory management functions for the API to use. To do this, you can write
your own custom functions to allocate, reallocate, and free memory, and make your functions
available to the API. Usually these functions internally call the corresponding memory
management functions used within your application.
Defining Custom Memory Management Functions in C Programs

To define your own custom memory management functions in a program, you write the
functions and set the Allocfunc, ReallocFunc, and FreeFunc fields in the API initialization
structure to point to your custom function before calling EssInit(). You can use any names you
wish for these functions and their arguments, but you must use the following form to declare
them:
ESS_FUNC_M CustomAlloc (ESS_SIZE_T BufSize, ESS_PPVOID_T ppBuffer);
ESS_FUNC_M CustomRealloc (ESS_SIZE_T BufSize, ESS_PPVOID_T ppBuffer);
ESS_FUNC_M CustomFree (ESS_PVOID_T pBuffer);
In this code, the fields are defined as follows:
78
l The BufSize argument is the minimum size of memory buffer to allocate or reallocate.
l The ppBuffer argument is the address of a memory pointer to receive the allocated or
reallocated buffer's address.
l The pBuffer argument is the address of a memory buffer to free. These functions return
zero (0) for success and non-zero for failure.
Pointers to these three functions should then be assigned to the AllocFunc, ReallocFunc, and
FreeFunc fields of the initialization structure before it is passed to the EssInit() function (see
“Initializing the C Main API” on page 84).
Note: If you decide to define your own custom memory management functions, you must create
and assign functions for all three structure fields.
After you have defined your own custom memory management functions, you cannot use the
default API memory management within that application, as any calls made to the Essbase
memory management API functions, EssAlloc(), EssRealloc(), and EssFree(), from within your
code will automatically invoke the equivalent custom functions you defined. However, any other
applications simultaneously using the API will not be affected; each application which calls
EssInit() can independently choose whether to define its own custom functions or use the default
ones.
Note: You should not attempt to call any Essbase API functions from within your custom
message function, with the exception of the memory management API functions, EssAlloc(),
EssRealloc(), and EssFree().
C Main API Message Handling

When your program calls the API, system messages and error messages are generated. Some of
those messages are returned by the Essbase Server, and others are internal to the API. Your
program must process these messages in some way, and if there is an error which causes the
operation in progress to abort, the user may need to be informed.
This section explains the API's message handling scheme, and then shows what C developers
can do to implement custom message processing in their programs:
l “How the Essbase C Main API Handles Messages” on page 79
l “Defining a Custom Message Function in C Programs” on page 80
How the Essbase C Main API Handles Messages

The following message levels are supported in Essbase:
l Information messages (for information only)
l Warning messages (operation will continue)
l Error messages (operation aborted)
79
l Serious errors (operation aborted-system is unstable)
l Fatal errors (operation aborted-system is halting)
When your program uses Essbase API default message handling, all messages of level Error or
higher (Serious or Fatal) are displayed on the current application screen.
Defining a Custom Message Function in C Programs

The C API allows you to supply a custom message handling function which you can use to trap
error messages before they are processed by the API. You may want to code a custom message
handling function, either to trap particular error conditions, or to ensure uniform processing
and display of all user messages throughout your program. If you choose not to supply a custom
message function, all message processing is handled by the API default message handler.
To define a custom message function in a program, you must write the function and set the
MessageFunc field in the API initialization structure to point to your custom function before
calling EssInit().
Coding the Custom Message Handling Function

You can use any name you wish for this function and its arguments, but it must be declared in
the following form:
ESS_FUNC_M CustomMessage (
ESS_PVOID_T UserContext, /* user context pointer */
ESS_LONG_T MessageNumber, /* Essbase message number */
ESS_USHORT_ T Level, /* message level */
ESS_STR_T LogString, /* message log string */
ESS_STR_T MessageString /* message string */
);
In this code, the fields are defined as follows:

l The UserContext argument is a copy of the pointer passed in the UserContext field of
the initialization structure to the EssInit() function during API initialization (see
“Initializing the C Main API” on page 84). You can use this pointer to contain any
application-specific context information which is required during custom message
processing, but typically it is used to pass a structure containing state information for your
program.
l The MessageNumber argument is used to trap messages returned by specific error
conditions (individual error message codes are defined in the header file (esserror.h).
l The Level argument is used to trap messages based on the message level, which denotes
whether the message is an information, warning, or error message.
l The LogString argument receives the server log entry information as a string. It passes
strings of the form:
[Date & Time] Server/Application/Database/Username/Thread/Message#
For example:
[Fri Feb 04 11:51:18 1994]Elm/Sample/Basic/Admin//1012550
80
l The MessageString argument contains the message text as a string. It passes the complete
message text, for example:
Total Calc Elapsed Time : [46] seconds
l The default API message handler displays both the log string and the message string on
successive lines, (either within the message dialog, or just written to the stdout stream). For
example:
[Fri Feb 04 11:51:18 1994]Elm/Sample/Basic/Admin//1012550 Total Calc Elapsed Time :
[46] seconds
Setting the MessageFunc Field to Point to Your Function

Pointers to the custom message function must be assigned to the MessageFunc field of the
initialization structure passed to the EssInit() function (see “Initializing the C Main API” on
page 84).
Using a Custom Function to Control Message Processing

The custom message function is called before an Essbase Server returns a message or the Essbase
API returns an error. When the function is called, the arguments passed to it contain the message
number, message level, log string, and error string for that particular message. For each message,
the function can use these argument values to choose whether to process the message, ignore it,
or return it to the API for default processing:
l What the return code means to the API—A return value of zero denotes that the function
processed the message successfully and that no further action needs to be taken by the API.
If the return code is non-zero, the message is passed to the default API message handling
function for further processing and display. To have your program ignore a message, simply
return a zero from the custom message function.
Note: The API automatically frees the log and message strings when it has finished
processing the message. Do NOT attempt to free them within your code.
l Determining which return code your function should generate—To determine which
return code to generate, you can code the custom message function to check the
MessageNumber argument, and/or the Level argument. For example, a program might
ignore all information messages, and possibly also any warning messages (you can make this
a user-definable setting) by testing the Level argument against the appropriate constant
defined in ESSAPI.H (for example, ESS_LEVEL_WARNING), and returning zero if the
value is equal to or below the required value. For other messages the function should either
process them internally and return a zero value, or return a non-zero value to ensure that
they are processed by the default API message handler.
Note: You should not attempt to call any Essbase API functions from within your custom
message function, with the exception of the memory management API functions,
EssAlloc(), EssRealloc(), and EssFree().
If you define your own custom message handling function, any other applications
simultaneously using the API will not be affected; each application which calls EssInit() can
81
independently choose whether to define its own custom message function or just use the
default message handler.
Choosing a Network Protocol

Essbase supports several different network protocols and different network vendor
implementations by providing a number of different Essbase network drivers. The driver you
need to install depends on the exact hardware, operating system, and network platform of the
client machine, and on the Essbase Server machine it is connecting to.
You need to determine the required network configuration and install the appropriate driver
file.
Calling C Main API Functions

This section describes calling API functions, using instance and context handles, and handling
return code.
Function Declarations
The API uses the ESS_FUNC_M macro to declare C API functions. This declares them to be of
type unsigned long for all supported platforms. You must also use this macro to declare any
custom functions which you pass to the API, such as custom memory management or message
handling functions.
Passing the Instance Handle or Context Handle

You must pass the instance handle returned by the initial call to EssInit() in calls to
EssLogin() or EssTerm(). You must pass the context handle returned by EssLogin() in any
function calls associated with a specific login.
Handling the Return Code

All Essbase API functions return a status code of type ESS_STS_T. A return code of zero indicates
that the function was executed successfully, and a non-zero value indicates an error condition.
A full list of error return constants is contained in the header file esserror.h. The
corresponding message text is in messages.txt.
Note: You should always check the return code from any Essbase API function. If the return
code is non-zero, any pointers or values returned by the function are undefined.
Internal Message Handling

Essbase uses an internal message handling function for non-custom message hadling. If an error
event is incountered under a 32-bit Windows system, a text error message is generated.
82
Typical C Main API Task Sequence
The API requires that your program call certain functions before others. The basic ordering rules
are:
l A program must call EssInit() before calling any other API functions.
l A program must call EssLogin() or EssAutoLogin() before calling any API functions which
require a context handle argument (most API functions). Additionally, if you need to create
a local context for API object functions to use, you must call EssCreateLocalContext() before
calling any API functions requiring a context handle argument.
l Some API functions require an active application and database to be set. This is done by
having the program call EssSetActive() or EssAutoLogin() before they are called.
l C programs cannot call any functions except memory management functions from within
custom message handling functions.
l C programs cannot not call any API functions from within custom memory management
functions.
l A program must not pass a context handle to any API functions after calling EssLogout()
for that handle.
l A program must not call any API functions after calling EssTerm().
This is the typical order of operations for a simple API application:

1. Create and initialize an ESS_INIT_T structure.
2. Initialize the API by calling EssInit().
3. Allocate any local static or global structures.
4. Log in to the required server by calling EssLogin() or EssAutoLogin().
5. Select an active application and database by calling EssSetActive() or EssAutoLogin().
6. Retrieve (or lock) data by calling EssReport() or related functions.
7. Update data by calling EssUpdate() or related functions.
8. Recalculate the database by calling EssCalc() or related functions.
9. Produce reports against the data by calling EssReport() or related functions.
10. Log out from the server by calling EssLogout().
11. Free any local static or global structures.
12. Terminate the API by calling EssTerm().
83
Initializing the C Main API
A program must initialize the API by calling the EssInit() function before calling any other
Essbase API functions. EssInit() initializes all internal API state variables, and also allows you
to tailor the API to your program's requirements.
The calling program must pass the EssInit() function an initialization structure. This structure
is defined in ESSAPI.H as type “ESS_INIT_T” on page 135. It contains a series of fields which
are used to customize the API and set up certain API defaults. You must declare an instance of
this structure and initialize the relevant fields before calling EssInit().
The EssInit() function returns an instance handle, which should then be passed as an argument
to the API login function.
Declaring the Initialization Structure

The initialization structure passed to EssInit() can usually be declared as a local (i.e. stack)
variable in the calling function, as it is usually not required once it has been passed to
EssInit(). Alternatively, you can allocate the structure before calling EssInit(), then free it after
returning.
If the initialization structure points to custom memory management functions in the
initialization call, make sure your program frees the structure using the correct memory
allocation scheme.
If any of the fields of the initialization structure are set to zero values or NULL pointers, the API
will use the internal default values for those fields.
It is a good idea to clear out all structures (set to 0) before setting fields and calling the API
function.
Logging in to an Essbase Server

In general, the first thing your program should do after calling EssInit() is to prompt the user
for a server name, user name, and password (or use predefined defaults), then attempt to log in
to that server by calling EssLogin(). Alternatively, use the encapsulated login function,
EssAutoLogin(). If this call is successful, then the returned context handle should be stored and
used for all subsequent API calls.
Selecting an Active Application and Database

In addition to the context handle, the login functions also return a list of the applications and
databases to which the logged in user has access (a program can obtain this list at any time by
calling the EssListDatabases() function. The program allows the user to select a specific
application and database by calling the EssSetActive() function.
If EssAutoLogin() is used to log in, it can optionally set the active application and database.
To get information about an Essbase application (e.g. whether or not it is already loaded), call
the EssGetApplicationState() or EssGetApplicationInfo() functions. To get information about
84
a specific database, call the EssGetDatabaseState() or EssGetDatabaseInfo() functions. You can
call these functions before setting the active application and database.
Retrieving and Updating Data

Retrieving Data
To retrieve data from an Essbase database, either for reporting or for subsequent updating, your
program needs to use a report specification. Report specifications can be in the form of a single
text string (if it is less than 32 KB in length), a series of text strings, or a file. Report files can
reside either on the client machine, or on the Essbase Server.
l Sending a report specification as a single string—To send a report specification as a single
string, have the program call EssReport() passing the entire report string, not greater than
32 KB long, as an argument. If the Output flag is set to TRUE in the call to EssReport(), the
program must also read the returned report data by calling EssGetString() repeatedly until
a NULL string is returned. The returned data can then be displayed, written to a file, or
printed, as required.
l Sending a report specification as a series of strings—To send a report specification as a
series of strings, first call EssBeginReport(), then call EssSendString() repeatedly to send
each string in the report specification (note that in Windows, each individual string must
not be greater than 32 KB long). Finally, terminate the report specification by calling
EssEndReport(). If the Output flag is set to TRUE in the call to EssBeginReport(). The
program must also read the returned report data by calling EssGetString() repeatedly until
a NULL string is returned. The returned data can then be displayed, written to a file, or
printed, as required.
l Sending a file as a report specification—To send a file as a report specification, use the
EssReportFile() function, passing the report file name. If the Output flag is set to TRUE in
the call to EssReportFile(), the program must also read the returned report data by calling
EssGetString() repeatedly until a NULL string is returned. The returned data can then be
displayed, written to a file, or printed, as required.
Updating Data
To update data in the database, you should first lock the blocks in the database which you are
going to update.
ä To lock database blocks, select one method:

l Send a report specification as described above, with the Output flag set to TRUE and
Lock flag also set to TRUE. The data output by this report can be modified, then sent back
to the database as an update.
l Alternatively, if there is new or modified data ready to be loaded, a program can first use it
as a report specification to lock the data blocks by setting the Output flag to FALSE and
setting the Lock flag to TRUE when calling the appropriate report function.
85
The database can be updated either from a single string, a series of strings, or a file. Update data
files can reside either on the client machine, or on the Essbase Server:
l Sending update data as a single string—To send an update as a single string, call
EssUpdate() passing the entire string as an argument. (Note that in MS-Windows, the string
must not be greater than 32 KB long). Set the Store flag to TRUE in the call to
EssUpdate() so that the database will be updated. If the Unlock flag is also set to TRUE, any
locked data blocks in the database will be unlocked once the data is updated, to allow other
users to update those blocks.
l Sending update data as a series of strings—To send an update as a series of strings, first call
EssBeginUpdate(), then call EssSendString() repeatedly to send all the data (note that in
MS-Windows, each individual data string must not be greater than 32 KB long). Finally,
terminate the update by calling EssEndUpdate(). Set the Store flag to TRUE in the call to
EssUpdate() so that the database will be updated. If the Unlock flag is also set to TRUE, any
locked data blocks in the database will be unlocked once the data is updated.
l Sending update data as a file—To send an update as a file, use the EssUpdateFile() function,
passing the data file name. Set the Store flag to TRUE in the call to EssUpdate() so that the
database will be updated. If the Unlock flag is also set to TRUE, any locked data blocks in
the database will be unlocked once the data is updated.
Recalculating the Database

After updating any data in the database it is essential to perform a recalculation to ensure that
the consolidated totals are correct. To recalculate a database, you can either perform the default
calculation, or send a specific calculation script. You can also set a calculation script to be the
default calc script. Calc scripts can be sent either as a single string, a series of strings, or a file.
Calc script files can reside either on the client machine, or on the Essbase Server.
Sending a Calc Script as a Single String

To send a calc script as a single string, call EssCalc() passing the entire string as an argument
(note that in MS-Windows, the string must not be greater than 32 KB long). Set the
Calculate flag to TRUE in the call to EssCalc() so that the calc script will be executed. You will
then need to check on the progress of the calculation at regular intervals.
Sending a Calc Script as a Series of Strings

To send a calc script as a series of strings, first call EssBeginCalc(), then call EssSendString()
repeatedly to send all the strings in the calc script (note that in MS-Windows, each individual
string must not be greater than 32 KB long). Finally, terminate the script by calling
EssEndCalc(). Set the Calculate flag to TRUE in the call to EssBeginCalc() so that the database
will be recalculated. You will then need to check on the progress of the calculation at regular
intervals (see "Checking the Progress of Calculations").
Sending a Calc Script as a File

To send a calc script as a file, use the EssCalcFile() function, passing the calc script file name.
Set the Calculate flag to TRUE in the call to EssCalcFile() so that the database will be
86
recalculated. You will then need to check on the progress of the calculation at regular intervals
(see "Checking the Progress of Calculations").
Using the Default Calc Script

To recalculate a database using the current default calc script, use the EssDefaultCalc() function.
To set the default calc script for a database, use EssSetDefaultCalc(), passing the calc script as a
single string. To set the default calc script from a file, use the EssSetDefaultCalcFile() function,
passing the calc script file name. Use EssGetProcessState() to determine when the calculation
is finished (see "Checking the Progress of Calculations").
Checking the Progress of Calculations

After a database calculation is started, check the progress of the calculation at regular intervals
(five seconds is recommended) by calling the EssGetProcessState() function. This function
returns a structure indicating the calculation state. Call EssGetProcessState() until it indicates
that the calculation is finished or that an error has occurred. You may also cancel a calculation
in progress with the EssCancelProcess() function.
Caution! While a calculation is in progress, do not attempt to call any API functions other
than EssGetProcessState() or EssCancelProcess() using the same context handle,
until the calc operation has completed successfully or has been canceled. After
EssGetProcessState() indicates the calc has finished, your program may continue
performing other API operations with that context handle.
Logging Out from the Essbase Server and Terminating

the C Main API
When all database operations are complete, the application should first log out by calling
EssLogout(). This frees up any internal resources reserved within the database, and may also
free the login port on the server for use by another user.
When an application program is about to terminate, it should call the EssTerm() function,
passing the instance handle which was returned from the original call to EssInit(). This releases
all resources used by the Essbase API. After calling this function, no other API calls can be made,
unless EssInit() is called again to reinitialize the API.
C Main API Common Problems and Solutions

The Essbase API gives you unrestricted access to many of the same functions that Essbase
Administration Server and MaxL use.
This section is a quick reference to help you in identifying and solving the most common
problems.
87
Problem Solution
Your program is generating Here are some things C programmers can check:
protection faults when allocating
or freeing memory. l Check that any memory returned from the API is being freed using the EssFree() function.
l Check the declared indirection level of any pointers being passed to the API.
l Use a memory checking program, such as Bounds Checker™ or Purify™, to determine the affected
module.
Even if the errors are occurring when accessing memory not used by Essbase, there may be some
interference between the Essbase memory management scheme and your own. You might consider
defining your own custom memory management functions.
Your program generates an Most of the Essbase error messages are self-explanatory, and it should be fairly obvious where the
Essbase error when calling an problem lies. However a couple of common errors to watch out for are (%n indicates a message argument
API function. which is replaced by a context-specific string):
l "NULL argument (%1) passed to ESSAPI function %2". This message indicates that one or more
arguments passed to the API function %2 were NULL. The %1 indicates the number of the first null
argument (1-based).
l "Invalid call sequence in ESSAPI function %1". This message indicates that you have made a call
to an API function (%1) when another function call was required. For example, if you have executed
a report function, such as EssReport(), make sure that you call EssGetString() repeatedly until a
NULL string is returned; or if you have executed a calculation function, e.g. EssCalc(), that you
repeatedly check the calculation state by calling EssGetProcessState() until the returned value
indicates that the calc has completed.
l "Local operation not allowed in ESSAPI function %s". You have passed a local context handle to a
function which does not allow it; use a login context handle instead.
l "Cannot open message database %s". The message database is not accessible on the machine
on which your program is running. Ensure that the message database is where Essbase expects to
find it. Essbase first examines the MessagePath field of the initialization structure passed to
EssInit(), then the directory and file name specified by the ARBORMSGPATH environment variable,
and finally, the $ESSBASEPATH\BIN directory where $ESSBASEPATH is an environment variable.
If the message database is not available in any of these directories, Essbase returns an error
message at run time. Verify which setting Essbase uses, and then verify that the message database
is located where specified. See Chapter 3, “Integrating Essbase With Your Product” for more
information.
Your program is consistently Certain internal API errors cannot display a message, typically because the user's context information
receiving an Essbase error return is not available when the message occurs. In these cases, make a note of the error code returned from
code from an API function, but the function, then refer to the list of error messages in messages.txt to find the corresponding
no message is displayed, or a message text. The error constants themselves are contained in esserror.h.
message saying "No message
for message #%1 in message
database" is generated.
When accessing fields in API- Check your compiler defaults to ensure you have structures aligned on byte boundaries. If the problem
defined structures, they appear still occurs, make sure you are compiling with the most recent versions of the API header files, and
to contain the wrong values, or linking with the most recent API DLLs.
the values seem to be "shifted"
by a few bytes.
88
C Main API Declarations
7
In This Chapter
Standard C Language Types ..............................................................................89
Constant Definitions (C)...................................................................................94
LRO Constant and Structure Definitions (C) ........................................................... 101
Constant and Structure Definitions for Partitions (C) ................................................. 103
Drill-Through Constant and Structure Definitions ..................................................... 104
C Main API Structures ................................................................................... 108
Standard C Language Types

The following data types are defined in the Essbase API for the C programming language:
l “Simple Data Types (C)” on page 89
l “Other Data Types (C)” on page 90
l “Bitmask Data Types (C)” on page 90
l “Pointer Types (C)” on page 92
l “Miscellaneous Types (C)” on page 93
l “Array Types (C)” on page 93
l “API Definitions (C)” on page 94
Simple Data Types (C)

Data Type Essbase Type
typedef char ESS_CHAR_T
typedef short ESS_SHORT_T
typedef long ESS_LONG_T
typedef unsigned char ESS_UCHAR_T
typedef unsigned short ESS_USHORT_T
typedef unsigned long ESS_ULONG_T
89
typedef float ESS_FLOAT_T
typedef double ESS_DOUBLE_T
If win32 && _USE_32BIT_TIME_T defined: ESS_TIME_T *

typedef __time32_t
Otherwise,
typedef time_t
typedef unsigned short ESS_DATE_T
If win32 && _USE_32BIT_TIME_T defined: ESS_DATETIME_T *

typedef __time32_t
Otherwise,
typedef time_t
Note: * For Visual Studio 2005 or later compilers, the C library data type time_t can be
long or int64 Windows datatypes, based on the compiler macro
_USE_32BIT_TIME_T. Essbase data types ESS_TIME_T and ESS_DATETIME_T are
long for 32-bit Windows platforms.
Other Data Types (C)

Data Type Essbase Type Description
typedef void *ESS_HCTX_T API context handle
typedef void *ESS_HINST_T API instance handle
typedef unsigned char ESS_BOOL_T boolean
typedef size_t ESS_SIZE_T size of a memory block
typedef char *ESS_STR_T string (array of char)
typedef void ESS_VOID_T void
Bitmask Data Types (C)

The values for these data types consist of bit values that are combined to provide additional
values when appropriate. For example, a caller needing WRITE access to a database must have
the READ and WRITE privileges, thus ESS_ACCESS_WRITE equals the bit values for
ESS_PRIV_READ and ESS__PRIV_WRITE. Similarly, ESS_OBJTYPE_BACKUP is a
combination of ESS_OBJTYPE_ASCBACKUP and ESS_OBJTYPE_BINBACKUP.
90
Data Type Essbase Description
Type
typedef ESS_ Security access level. Possible bit values are:

unsigned ACCESS_T
ESS_PRIV_NONE - 0x0000 - no privilege
short
l
l ESS_PRIV_READ - 0x0001 - read data

l ESS_PRIV_WRITE - 0x0002 - write data
l ESS_PRIV_CALC - 0x0004 - calculate data
l ESS_PRIV_DBLOAD - 0x0010 - load and unload databases
l ESS_PRIV_DBDESIGN - 0x0020 - manage databases
l ESS_PRIV_DBCREATE - 0x0040 - create, delete, and edit databases
l ESS_PRIV_APPLOAD - 0x0100 - load and unload applications
l ESS_PRIV_APPDESIGN - 0x0200 - manage applications
l ESS_PRIV_APPCREATE - 0x0400 - create, delete, and edit applications
l ESS_PRIV_USERCREATE - 0x1000 - create, delete, and edit users
The access types are combinations of privileges. The valid values are:
l ESS_ACCESS_NONE - 0x0000
l ESS_ACCESS_READ - 0x0111
l ESS_ACCESS_WRITE - 0x0113
l ESS_ACCESS_CALC - 0x0117
l ESS_ACCESS_METAREAD - 0x0118
l ESS_ACCESS_DBMANAGE - 0x0137 (also known as ESS_ACCESS_DBDESIGN, preserved for backward
compatibility)
l ESS_ACCESS_DBCREATE - 0x0177
l ESS_ACCESS_APPDESIGN - 0x0377
l ESS_ACCESS_APPCREATE - 0x0777
l ESS_ACCESS_FILTER - 0x0110
l ESS_ACCESS_DBALL - 0x00ff - full database access
l ESS_ACCESS_APPALL - 0x0fff - full application/database access
l ESS_ACCESS_ADMIN - 0xffff - administrator (unrestricted access) (also known as ESS_ACCESS_SUPER,
preserved for backward compatibility)
The Oracle Hyperion Shared Services security role mappings are:
l ESS_USERPROVROLE_NONE = ESS_ACCESS_NONE = 0x0000
l ESS_USERPROVROLE_USERCREATE = ESS_PRIV_USERCREATE = 0x1000
Note: This role cannot be set by Essbase in Shared Services mode; it can only be set in Shared Services.
l ESS_USERPROVROLE_APPCREATE = ESS_PRIV_APPCREATE = 0x0400
l ESS_USERPROVROLE_APPMANAGER = ESS_ACCESS_APPMANAGE or ESS_ACCESS_APPDESIGN =
0x0377
l ESS_USERPROVROLE_APPLOAD = ESS_PRIV_APPLOAD = 0x0100
l ESS_USERPROVROLE_DBFILTER = ESS_ACCESS_FILTER = 0x0110
l ESS_USERPROVROLE_DBREAD = ESS_ACCESS_READ = 0x0111
l ESS_USERPROVROLE_DBWRITE = ESS_ACCESS_WRITE = 0x0113
l ESS_USERPROVROLE_DBCALC = ESS_ACCESS_CALC = 0x0117
91
Data Type Essbase Description
Type
l ESS_USERPROVROLE_DBMANAGER = ESS_ACCESS_DBMANAGE or ESS_ACCESS_DBDESIGN = 0x0137
l ESS_USERPROVROLE_ADMINISTRATOR = ESS_ACCESS_ADMIN or ESS_ACCESS_SUPER = 0xffff
typedef ESS_ File object type.

unsigned OBJTYPE_T
Single object types are:
long
l ESS_OBJTYPE_NONE
l ESS_OBJTYPE_OUTLINE
l ESS_OBJTYPE_CALCSCRIPT
l ESS_OBJTYPE_REPORT
l ESS_OBJTYPE_RULES
l ESS_OBJTYPE_ALIAS
l ESS_OBJTYPE_STRUCTURE
l ESS_OBJTYPE_ASCBACKUP
l ESS_OBJTYPE_BINBACKUP
l ESS_OBJTYPE_EXCEL
l ESS_OBJTYPE_LOTUS2 (No longer supported)
l ESS_OBJTYPE_TEXT
l ESS_OBJTYPE_PARTITION
l ESS_OBJTYPE_WIZARD
l ESS_OBJTYPE_OTL_E
l ESS_OBJTYPE_SELECTION
l ESS_OBJTYPE_LRO
#define ESS_OBJTYPE_MAX 0x08000000 /* maximum single object type value */ Combined object types
are:
l ESS_OBJTYPE_BACKUP
l ESS_OBJTYPE_WORKSHEET
l ESS_OBJTYPE_DATA
l ESS_OBJTYPE_ALL
Pointer Types (C)
char *ESS_PCHAR_T pointer to char
unsigned char *ESS_PUCHAR_T pointer to unsigned char
short *ESS_PSHORT_T pointer to short
92
unsigned short *ESS_PUSHORT_T pointer to unsigned short
long *ESS_PLONG_T pointer to long
unsigned long *ESS_PULONG_T pointer to unsigned long
double *ESS_PDOUBLE_T pointer to double
float *ESS_PFLOAT_T pointer to float
ESS_ACCESS_T *ESS_PACCESS_T pointer to security access level
ESS_BOOL_T *ESS_PBOOL_T pointer to boolean
ESS_HCTX_T *ESS_PHCTX_T pointer to API context handle
ESS_HINST_T *ESS_PHINST_T pointer to API instance handle
ESS_SIZE_T *ESS_PSIZE_T pointer to size of a memory block
ESS_STR_T *ESS_PSTR_T pointer to string
ESS_VOID_T *ESS_PVOID_T pointer to void
Miscellaneous Types (C)
typedef long ESS_STS_T return value from API functions
typedef ESS_STS_T (*ESS_FUNC_T)() pointer to function
Array Types (C)

The following array types are defined using the appropriate maximum string length. For
example, the type ESS_USERNAME_T is defined as typedef char
ESS_USERNAME_T[ESS_USERNAME_LEN].
typedef char ESS_USERNAME_T user name
typedef char ESS_PASSWORD_T password
typedef char ESS_SVRNAME_T server name
typedef char ESS_APPNAME_T application name
93
typedef char ESS_DBNAME_T database name
typedef char ESS_OBJNAME_T object name
typedef char ESS_MBRNAME_T member name
typedef char ESS_FTRNAME_T filter name
typedef char ESS_ALIASNAME_T alias table name
typedef char ESS_PATH_T file path name
typedef char ESS_DESC_T app/database description
API Definitions (C)

Essbase Type Value
#define ESS_TRUE 1
#define ESS_FALSE 0
#define ESS_NULL NULL
#define ESS_NATIVE_SECURITY1 1
#define ESS_SS_SECURITY 2
1Essbase native security mode is no longer supported.
Constant Definitions (C)

The following constants are defined in the Essbase API:
l “Attributes Constants (C)” on page 95
l “Dimension Tag Constants (C)” on page 97
l “Information Flag Constants (C)” on page 98
l “List Option Constants (C)” on page 99
l “Maximum String Lengths (C)” on page 99
l “Request Type Constants (C)” on page 100
l “Size Flag Constants (C)” on page 100
94
Attributes Constants (C)
The following constants define the data type of the member queried and returned for the
usInputMemberType and usOutputMemberType fields of the “ESS_ATTRIBUTEQUERY_T” on
page 707 structure.
Value Definition
ESS_BASE_DIMENSION A dimension that is not an attribute dimension
ESS_BASE_MEMBER A member that is not an attribute member
ESS_ATTRIBUTE_DIMENSION An attribute dimension
ESS_ATTRIBUTE_MEMBER An attribute member
ESS_ATTRIBUTED_MEMBER A base member or dimension that has attributes associated with it. Also called a standard member or
dimension.
The following constant defines the attribute member status for the Status field of the
“ESS_MBRINFO_T” on page 709 structure.
Value Definition
ESS_MBRSTS_ATTRIBUTE Attribute member status
The following constants define the attribute dimension tag type for the DimTag field of the
“ESS_DIMENSIONINFO_T” on page 126 structure.
Value Definition
ESS_TTYPE_ATTRIBUTE Attribute tag
ESS_TTYPE_ATTRCALC Attribute calculation tag. Used internally for aggregation.
The following constants define the attribute member data type for the usDataType field of the
“ESS_ATTRIBUTEVALUE_T” on page 113 structure and the DimDataType field of the
Value Definition
ESS_ATTRMBRDT_BOOL Boolean data type
ESS_ATTRMBRDT_DATETIME Datetime data type
ESS_ATTRMBRDT_DOUBLE Double data type
ESS_ATTRMBRDT_STRING String data type
ESS_ATTRMBRDT_NONE No data type
The following constants define the type of attribute query operation for the usOperation field of
the “ESS_ATTRIBUTEQUERY_T” on page 707 structure.
95
Value Definition
ESS_EQ Equal to
ESS_NEQ Not equal to
ESS_GT Greater than
ESS_LT Less than
ESS_GTE Greater than or equal to
ESS_LTE Lesser than or equal to
ESS_TYPEOF Type of
ESS_ALL All
Table 6 C API Attributes Terminology
Term Definition
bucketing type When building a dimension, you can associate a zero-level attribute member of type ESS_ATTRMBRDT_DOUBLE with
a range of data in a relational source.
Bucketing type determines the upper or lower limit of the data range.
See usBucketingType.
ESS_ATTRIBUTE_ ESS_ATTRIBUTE_DIMENSION is an attribute dimension.

DIMENSION
ESS_ATTRIBUTE_MEMBER is a member of an attribute dimension.
ESS_ATTRIBUTE_
See “ESS_ATTRIBUTEQUERY_T” on page 707.
MEMBER
Also see EssCheckAttributes.
ESS_ ESS_ATTRIBUTED_MEMBER is a member (of a base dimension) which has an attribute member associated with it.
ATTRIBUTED_
MEMBER
ESS_BASE_ ESS_BASE_DIMENSION is a standard dimension that has an attribute dimension associated with it.
DIMENSION
ESS_BASE_MEMBER is a member of a base dimension.
ESS_BASE_
MEMBER
ESS_STANDARD_ ESS_STANDARD_DIMENSION is any dimension that is not an attribute dimension.

DIMENSION
ESS_STANDARD_MEMBER is a member of a standard dimension.
ESS_STANDARD_
MEMBER
96
Term Definition
long name A zero-level attribute member that is not of type ESS_ATTRMBRDT_STRING is uniquely identified by a long name.
A zero-level attribute member of type ESS_ATTRMBRDT_STRING must itself be unique.
See the following structures:
l “ESS_ATTRSPECS_T” on page 113
l “ESS_ATTRIBUTEINFO_T” on page 112
Also see the following functions:

l EssGetAttributeSpecifications
l EssOtlGetAttributeSpecifications
l EssOtlSetAttributeSpecifications
And, see Notes on Adding an Attribute Member.
short name A zero-level attribute member that is not of type ESS_ATTRMBRDT_STRING is called a short name.
It is provided to a function as a parameter of type ESS_STR_T.
See EssOtlFindAttributeMembers.
Dimension Tag Constants (C)

The following constants define the available information flags used in the DimTag field of the
Constant Definition
ESS_TTYPE_NONE No dimension type. Value for DimTag field of ESS_DIMENSIONINFO_T.
ESS_TTYPE_CCATEGORY Accounts: Currency ACCOUNTS tag. Value for DimTag field of ESS_DIMENSIONINFO_T
ESS_TTYPE_CNAME Country: Currency COUNTRY tag. Value for DimTag field of ESS_DIMENSIONINFO_T
ESS_TTYPE_CTIME Time: Currency TIME tag. Value for DimTag field of ESS_DIMENSIONINFO_T
ESS_TTYPE_CTYPE Type: Currency TYPE tag. Value for DimTag field of ESS_DIMENSIONINFO_T
ESS_TTYPE_CPARTITION Currency PARTITION tag. Value DimTag field of ESS_DIMENSIONINFO_T
Implied Share Setting (C)

Implied Share settings can apply to a specific outline, using the EssOtlGetImpliedShare and
EssOtlSetImpliedShare functions.
No changes take effect until the outline is saved and restructured.
97
Note: The explicit settings are especially useful if the application later is copied, as the setting
would be “sticky” and follow the outline independent of any application name specific
entry in the Essbase.cfg file.
The setting can have the following values:
Value Description
ESS_IMPLIEDSHARE_DEFAULT Can be set using EssOtlSetImpliedShare.

When set, immediately gets converted to either _ON or _OFF.
If returned:
l Outline has no Implied Share setting
l Implied Share is ON
ESS_IMPLIEDSHARE_DEFAULT_ON Return value only available with EssOtlGetImpliedShare.

If returned:
l Outline uses Implied Share default setting in Essbase.cfg
l Essbase.cfg might contain an Implied Share entry (ON)
l Essbase.cfg should contain no entry
l Implied Share is ON
ESS_IMPLIEDSHARE_DEFAULT_OFF Return value only available with EssOtlGetImpliedShare.

If returned:
l Outline uses Implied Share default setting in Essbase.cfg
l Essbase.cfg contains an Implied Share entry (OFF)
l Implied Share is OFF
ESS_IMPLIEDSHARE _FORCE_ON Can be set using EssOtlSetImpliedShare.

An explicit setting indicating the outline always has Implied Share ON.
ESS_IMPLIEDSHARE _FORCE_OFF Can be set using EssOtlSetImpliedShare.

An explicit setting indicating the outline always has Implied Share OFF.
Information Flag Constants (C)

The following constants define the available information flags used in the DbReqFlags (Data
Load) field of the “ESS_DBREQINFO_T” on page 120 structure.
Constant Definition
ESS_DBREQFLAG_CALCDEF Default flag for DbReqFlags field. Used the default calc script. Value: 0x00000001.
ESS_DBREQFLAG_CALCDSCR Custom calc script flag for DbReqFlags field. Used a custom calc script. Value: 0x00000002.
98
List Option Constants (C)
The following constants define request types used by the ListOption field of the
EssListTransactions function.
Constant Definition
ESS_LIST_TRANSACTIONS_TOCLIENT Write the output to the screen.
LIST_TRANSACTIONS_TOFILE l Write output to a CSV file.

l Output is not returned in ppResults.
l pCount and ppResults will be NULL.
l Content is written to the FileName as comma separated file.
l If the specified file name exists, the command fails.
ESS_LIST_TRANSACTIONS_FORCETOFILE l Write output to a CSV file.

l Output is not returned in ppResults.
l pCount and ppResults will be NULL.
l Content is written to the FileName as comma separated file.
l If the specified file name exists, it is overwritten with the new output.
Maximum String Lengths (C)

The following constants define the maximum lengths of various string types in the Essbase API.
All of these constants include the terminating NULL character:
Constant Definition
ESS_ALIASNAMELEN Maximum length of an alias table name
ESS_APPNAMELEN Maximum length of an application name
ESS_CRDB_MAXIMUM Maximum dimension number for a Currency database
ESS_DBNAMELEN Maximum length of a database name
ESS_DESCLEN Maximum length of an application or database description
ESS_FTRNAMELEN Maximum length of a filter name
ESS_LINELEN Maximum length of a line in a report
ESS_MBRCOMMENTEXLEN Maximum length of an extended member comment
ESS_MBRNAMELEN Maximum length of a member name
ESS_NAMELEN Maximum length of a general name
ESS_PASSWORDLEN Maximum length of a user password
ESS_PATHLEN Maximum length of a file path name
99
Constant Definition
ESS_OBJNAMELEN Maximum length of an object name
ESS_SVRNAMELEN Maximum length of a server name
ESS_USERNAMELEN Maximum length of a user or group name
Request Type Constants (C)

The following constants define request types used by the ucReqType field of the
“ESS_TRANSACTION_REQSPECIFIC_T” on page 182 structure.
Constant Definition
ESS_TRLOG_CALCSCRIPT_SERVER Calculation script name
ESS_TRLOG_CALCSCRIPT_IMMEDIATE No data
ESS_TRLOG_CALCSCRIPT_DEFAULT No data
ESS_TRLOG_CALCSCRIPT_SETDEFAULT No data
ESS_TRLOG_DATALOAD_SERVER Server side data load file
ESS_TRLOG_DATALOAD_IMMEDIATE Data was input from client side
ESS_TRLOG_DATALOAD_SQL SQL data source
ESS_TRLOG_DATALOAD_CLEARDB Clear all data
ESS_TRLOG_DATALOAD_RESETDB Clear all data and out line
ESS_TRLOG_SSUPDATE Grid client updates
ESS_TRLOG_DATALOAD_FTP FTP data source
Size Flag Constants (C)

The following constants define the maximum and minimum size for the MaxMemIndex and
IndexPageSize fields of the “ESS_DBSTATE_T” on page 121 structure.
Constant Definition
ESS_INDEXCACHEMIN_SIZE Minimum index cache size for the MaxMemIndex field of the ESS_DBSTATE_T structure. Value: 1048576.
No maximum value is defined.
ESS_INDEXPAGEMAX_SIZE Maximum index page size for the IndexPageSize field of the ESS_DBSTATE_T structure. Value: 8192
ESS_INDEXPAGEMIN_SIZE Minimum index page size for the IndexPageSizeMin field of the ESS_DBSTATE_T structure. Value: 1024
100
Unicode Mode Constants (C)
The following constants enable Unicode-mode client programs. These constants are the valid
values for the usApiType field of the ESS_INIT_T structure. The ESS_INIT_T structure is used
by EssInit() and defines whether the client program is in Unicode mode. Only Unicode-mode
client programs can send UTF-8 encoded text to Essbase Server.
Constant Definition Description
ESS_API_NONUNICODE 0x0002 The program is a non-Unicode mode client program. The client program is passing a non_Unicode
encoded argument to the API. This is the default value.
ESS_API_UTF8 0x0003 The program is a Unicode mode client program. The client program is passing a UTF-8 encoded
argument to the API.
LRO Constant and Structure Definitions (C)

The following constants and structures are defined specifically for use with Linked Reporting
Objects (LROs):
l “Constants for LROs (C)” on page 101
l “ESS_CELLADDR_API_T” on page 102
l “ESS_LRODESC_API_T” on page 102
l “ESS_LROHANDLE_API_T” on page 103
l “ESS_LROINFO_API_T” on page 103
Constants for LROs (C)

The following constants define various values used by LRO functions and structures in the
Essbase API.
Data Type Field Description
ESS_LRODESCLEN_API 79 Maximum length of an object description
ESS_LRONOTELEN_API 599 Maximum length of a cell note
ESS_ONAMELEN_API 511 Length of an object name consisting of file name and path
ESS_DATESIZE 12 Size of date string
ESS_STORE_OBJECT_API 0x0010 Value to store a linked object on the server
ESS_NOSTORE_OBJECT_API 0x0001 Value to not store a linked object on the server
ESS_LROTYPE_CELLNOTE_API 0 Value specifying that a linked object is a cell note
ESS_LROTYPE_WINAPP_API 1 Value specifying that a linked object is a Windows application
101
ESS_LROTYPE_URL_API 2 Value specifying that a linked object is a URL
ESS_CELLADDR_API_T
Contains information about the address of a data cell in an Essbase database. Essbase derives the
cell address from the member combination and uses the address to keep track of objects linked
to data cells. You cannot modify fields in this structure through the API. The fields are described
as follows:
ESS_ULONG_T cellOffset Cell offset within a data block
ESS_SECPART_T blkOffset Block offset
ESS_SECPART_T segment Segment number
ESS_LRODESC_API_T
Contains information describing a specific object linked to a data cell in an Essbase database.
The fields are described as follows:
struct ESS_LRODESC_API_T next (The next field is for internal use only.)
ESS_USHORT_T usObjType The object type
ESS_USHORT_T status The catalog entry status
ESS_LROHANDLE_API_T linkId Link ID of the LRO
ESS_CHAR_T userName[ESS_USERNAMELEN] The name of the last user to modify the object
ESS_TIME_T updateDate The last date the object was modified
ESS_ACCESS_T accessLevel The access level of the member combination
ESS_ULONG_T memCount The number of members in the member combination
ESS_PMBRNAME_NONUNI_T pMemComb The member combination associated with the object
ESS_LROINFO_API_T lroInfo The LRO information structure, associated by union
ESS_CHAR_T note[ESS_LRONOTELEN_API] A cell note, associated by union
102
ESS_LROHANDLE_API_T
Provides an identifier for a linked object. The identifier consists of a cell address and an internal
object handle. You should not modify fields in this structure because it contains information
concerning the linked object. The fields are described as follows:
ESS_CELLADDR_API_T cellKey Cell address
ESS_LONG_T hObject Internal object handle
ESS_LROINFO_API_T
Contains information about a specific object linked to a data cell in an Essbase database. You
should not modify fields in this structure because it contains information concerning the linked
object. The fields are described as follows:
ESS_CHAR_T objName[ESS_ONAMELEN_API] Source file name of object linked to a data cell. ESS_ONAMELEN_API specifies the
maximum length of an object name; the default value is 511.
ESS_CHAR_T objDesc[ESSW_LRODESCLEN_API] Description of an object linked to a data cell. ESS_LRODESCLEN_API specifies the
maximum length of the description; the default value is 79.
Constant and Structure Definitions for Partitions (C)

“ESS_PART_T” on page 146
“ESS_PART_CONNECT_INFO_T” on page 147
“ESS_PART_DEFINED_T” on page 147
“ESS_PART_INFO_T” on page 148
“ESS_PART_REPL_T” on page 149
“ESS_PARTDEF_INVALID_T” on page 149
“ESS_PARTDEF_CONNECT_T” on page 150
“ESS_PARTDEF_MAP_T” on page 151
“ESS_PARTDEF_T” on page 151
“ESS_PARTDEF_AREAS_T” on page 152
“ESS_PARTDEF_TYPE_T” on page 152
“ESS_PARTHDR_T” on page 153
“ESS_PARTOTL_DIMASSOCCHG_API_T” on page 156
“ESS_PARTOTL_DIM_ATTRIB_API_T” on page 155
103
“ESS_PARTOTL_MBRASSOCCHG_API_T” on page 158
“ESS_PARTOTL_MBRATTR_API_T” on page 158
“ESS_PARTOTL_MBRCHG_API_T” on page 159
“ESS_PARTOTL_MBR_RSRVD_API_T” on page 157
“ESS_PARTOTL_CHG_FILE_T” on page 154
“ESS_PARTOTL_QRY_FILTER_T” on page 163“ESS_PARTOTL_QUERY_T” on page 163
“ESS_PARTOTL_READ_T” on page 164
“ESS_PARTOTL_NAMECHG_API_T” on page 160
“ESS_PARTOTL_NAMED_GENLEV_API_T” on page 161
“ESS_PARTOTL_NAMEMAP_API_T” on page 161
“ESS_PARTOTL_CHANGE_API_T” on page 154
“ESS_PARTOTL_DIMCHG_API_T” on page 156
“ESS_PARTOTL_SELECT_APPLY_T” on page 165
“ESS_PARTOTL_SELECT_CHG_T” on page 165
“ESS_PARTSLCT_T” on page 165
“ESS_PARTSLCT_VALIDATE_T” on page 166
Drill-Through Constant and Structure Definitions

These topics discuss the C Main API constants and structures that are defined specifically for
use with Drill-Through:
l “C Main API Drill-Through Constants and Structures (essdt.dll)” on page 104
l “C Main Drill-Through Constants and Structures (essdtapi.dll)” on page 106
C Main API Drill-Through Constants and Structures

(essdt.dll)
Structures
l “ESS_DTBUFFER_T” on page 130
l “ESS_DTDATA_T” on page 131
l “ESS_DTHEADER_T” on page 131
Constants for Maximum String Length

104
Constant Definition
ESS_DESCRIPTION_LEN Maximum string length (255) used for drill-through
ESS_DTREPORT_NAME Maximum string length (80) used for drill-through
ESS_MAX_DATALEN Maximum string length (255) used for drill-through
ESS_MAX_NAME Maximum string length (30) used for drill-through
Pointer Types
105
ESS_DTAPIHINST_T *ESS_PDTAPIHINST_T pointer to a drill-through initialization structure
ESS_DTHINST_T *ESS_PDTHINST_T pointer to a drill-through initialization structure
C Main Drill-Through Constants and Structures (essdtapi.dll)

Structures
l “ESS_DTAPICOLUMN_T” on page 128
l “ESS_DTAPIDATA_T” on page 129
l “ESS_DTAPIHEADER_T” on page 129
l “ESS_DTAPIINFO_T” on page 129
l “ESS_DTAPIREPORT_T” on page 130
Constants for Maximum String Length

Constant Definition
ESS_DESCRIPTION_LEN Maximum string length (255) used for drill-through
106
Constant Definition
ESS_DTREPORT_NAME Maximum string length (80) used for drill-through
ESS_MAX_DATALEN Maximum string length (255) used for drill-through
ESS_MAX_NAME Maximum string length (30) used for drill-through
Drill-Through Connection Values for uInputOption in ESS_DTAPIINFO_T

The following constants define input values to connect to Oracle Essbase Studio for drill-
through.
Constant Definition
ESS_DTAPI_PROMPT_HISNAME A value for uInputOption which means that the user can connect to Essbase Studio to perform a drill-
through
ESS_DTAPI_PROMPT_LOGIN A value for uInputOption which means that a password is required to connect to Essbase Studio to
perform a drill-through
Pointer Types
107
ESS_DTAPIHINST_T *ESS_PDTAPIHINST_T pointer to a drill-through initialization structure
ESS_DTHINST_T *ESS_PDTHINST_T pointer to a drill-through initialization structure
C Main API Structures

Consult the Contents pane for the list of C Main API structures.
ESS_APPDB_T
This application and database name structure returns application and database names. The fields
are:
typedef struct ESS_APPDB_T
{
ESS_APPNAME_T AppName;
ESS_DBNAME_T DbName;
} ESS_APPDB_T, *ESS_PAPPDB_T, **ESS_PPAPPDB_T;
ESS_APPNAME_T AppName The application name
ESS_DBNAME_T DbName The database name
108
ESS_APPINFO_T
This Application Info Structure returns information about a specific application. Fields in this
structure cannot be modified using the API. See the “ESS_APPSTATE_T” on page 111structure,
which contains additional application state parameters that can be modified. The fields are:
Note: Refer also to the locale-specific extended Application Info structure,

“ESS_APPINFOEX_T” on page 110.
typedef struct ESS_APPINFO_T

{
ESS_APPNAME_T Name;
ESS_SVRNAME_T Server;
ESS_USHORT_T Status;
ESS_USHORT_T, AppType;
ESS_CHAR_T, AppLocale, ESS_LOCALESTRING_LENGTH;
ESS_USHORT_T nConnects;
ESS_TIME_T ElapsedAppTime;
ESS_USHORT_T nDbs;
ESS_DATA_STORAGE_T StorageType;
ESS_DBNAME_T DbNames[1];
} ESS_APPINFO_T, *ESS_PAPPINFO_T, **ESS_PPAPPINFO_T;
ESS_APPNAME_T Name The application name
ESS_SVRNAME_T Server The server name
ESS_USHORT_T Status The application load status (loaded or not loaded). This field can contain the following values:
l ESS_STATUS_NOTLOADED
l ESS_STATUS_LOADING
l ESS_STATUS_LOADED
l ESS_STATUS_UNLOADING
ESS_USHORT_T AppType The type of application. Valid values are:

l ESS_APP_UNICODE - 0x0003 - The program is a Unicode client program. The function fails
if the server is not in Unicode mode. This is the default value.
l ESS_APP_NONUNICODE - 0x0002 - The program is a non-Unicode mode client program.
ESS_CHAR_T AppLocale The application locale description, of type ESS_LOCALESTRING_LENGTH.
ESS_USHORT_T nConnects The number of users currently connected to the application
ESS_TIME_T ElapsedAppTime Elapsed number of seconds since application loading
ESS_USHORT_T nDbs The number of databases in this application
109
ESS_DATA_ StorageType The storage type. The valid values are:

STORAGE_T
l 0 - the default (same as 1)
l 1 - multidimensional (block storage)
l 4 - aggregate storage
l 1000 - Undefined
ESS_DBNAME_T DbNames [1] A dynamic array (with nDb elements) of database name strings listing all the databases in the
application.
ESS_APPINFOEX_T
This extended Application Info structure is slightly different from the standard
“ESS_APPINFO_T” on page 109 structure used by EssGetApplicationInfo. This extended
structure is used by EssGetApplicationInfoEx.
The fields are:
typedef struct ESS_APPINFOEX_T
{
ESS_APPNAME_T Name;
ESS_USHORT_T, AppType;
ESS_CHAR_T, AppLocale, ESS_LOCALESTRING_LENGTH;
ESS_TIME_T ElapsedAppTime;
ESS_DATA_STORAGE_T StorageType;
} ESS_APPINFOEX_T, *ESS_PAPPINFOEX_T, **ESS_PPAPPINFOEX_T;
ESS_APPNAME_ Name Application name

T
ESS_SVRNAME_ Server Server name

T
ESS_USHORT_T AppType The type of application.

Valid values are:
l ESS_APP_UNICODE - 0x0003 - The program is a Unicode client program. The function fails if
the server is not in Unicode mode. This is the default value.
l ESS_APP_NONUNICODE - 0x0002 - The program is a non-Unicode mode client program.
ESS_CHAR_T AppLocale The application locale description, of type ESS_LOCALESTRING_LENGTH.
110
ESS_USHORT_T Status The application load status (loaded or not loaded). This field can contain the following values:
l ESS_STATUS_LOADED
ESS_USHORT_T nConnects The number of users currently connected to the application
ESS_TIME_T ElapsedAppTime Elapsed number of seconds since application loading
ESS_DATA_ StorageType The storage type. The valid values are:

STORAGE_T
l 0 - the default (same as 1)
l 1 - multidimensional (block storage)
l 4 - aggregate storage
l 1000 - Undefined
ESS_APPSTATE_T
This Application State Structure gets and sets the state parameters for a specific application. All
fields in this structure can be modified using the API, with the exception that some fields do not
apply to aggregate storage databases. See also the “ESS_APPINFO_T” on page 109 structure,
which contains additional application information that cannot be modified. The fields are:
typedef struct ESS_APPSTATE_T
{
ESS_DESC_T Description;
ESS_BOOL_T Loadable;
ESS_BOOL_T Autoload;
ESS_BOOL_T Connects;
ESS_BOOL_T Commands;
ESS_BOOL_T Updates;
ESS_BOOL_T Security;
ESS_ULONG_T LockTimeout;
ESS_ULONG_T lroSizeLimit;
} ESS_APPSTATE_T, *ESS_PAPPSTATE_T, **ESS_PPAPPSTATE_T;
ESS_DESC_T Description The application description (up to 80 characters)
ESS_BOOL_T Loadable Flag to indicate whether application can be loaded (ESS_TRUE : application is loadable)
ESS_BOOL_T Autoload Flag to indicate whether the application is loaded automatically when Essbase is started (ESS_TRUE if
the application will be automatically loaded)
111
ESS_ACCESS_T Access The default access to databases in the application (the lowest possible level of access for all users).
This field can contain the following values:
l ESS_PRIV_NONE
l ESS_PRIV_DBDESIGN
l ESS_PRIV_CALC
l ESS_PRIV_WRITE
l ESS_PRIV_READ
ESS_BOOL_T Connects Flag to indicate whether users can connect to the application (ESS_TRUE if users can connect).
ESS_BOOL_T Commands Flag to indicate whether users can issue commands to the application (ESS_TRUE if the application is
accepting user commands).
ESS_BOOL_T Updates Flag to indicate whether users can update data in the application (ESS_TRUE if the application is
accepting user update commands).
ESS_BOOL_T Security Flag to indicate whether application security is enabled (ESS_TRUE if security is enabled).
ESS_ULONG_T LockTimeout Timeout period (in seconds) after which block-level locks are automatically removed. This field does
not apply to aggregate storage databases.
ESS_ULONG_T lroSizeLimit Limit on the size of LRO files. This limit is set for each application and enables the administrator or
program to protect the server from overly large linked files. Essbase itself does not limit the size or have
a default value. This limit does not apply to LRO URLs (limited to 512 characters) or to LRO cell notes
(limited to 599 characters). This field does not apply to aggregate storage databases.
ESS_ATTRIBUTEINFO_T
Contains attribute information on a specific member. ESS_ATTRIBUTEINFO_T is used by
EssGetAttributeInfo.
typedef struct ESS_ATTRIBUTEINFO_T
{
ESS_MBRNAME_T MbrName;
ESS_MBRNAME_T DimName;
ESS_ATTRIBUTEVALUE_T Attribute;
} ESS_ATTRIBUTEINFO_T, *ESS_PATTRIBUTEINFO_T, **ESS_PPATTRIBUTEINFO_T;
ESS_MBRNAME_T MbrName Attribute member name from “ESS_MEMBERINFO_T” on page 143 or

“ESS_MBRINFO_T” on page 709, including a long name
ESS_MBRNAME_T DimName Attribute dimension name
the section called Attribute Attribute value

“ESS_ATTRIBUTEVALUE_T”
112
ESS_ATTRIBUTEVALUE_T
Contains information on the type and value of attribute members.
typedef struct ESS_ATTRIBUTEVALUE_T
{
ESS_USHORT_T usDataType;
union
{
ESS_BOOL_T bData;
ESS_STR_T strData;
ESS_DATETIME_T dtData;
ESS_DOUBLE_T dblData;
}
value;
} ESS_ATTRIBUTEVALUE_T, *ESS_PATTRIBUTEVALUE_T, **ESS_PPATTRIBUTEVALUE_T;
ESS_USHORT_T usDataType A constant identifier indicating the data type of an attribute dimension or member.
One of the following values for an attribute dimension or zero-level (leaf node) attribute member:
l ESS_ATTRMBRDT_BOOL
l ESS_ATTRMBRDT_STRING
l ESS_ATTRMBRDT_DATETIME
l ESS_ATTRMBRDT_DOUBLE
l One of the following values for an attribute member, but not an attribute dimension:
l ESS_ATTRMBRDT_NONE
l ESS_ATTRMBRDT_AUTO
ESS_BOOL_T value A union variable for the following attribute member values:
ESS_STR_T value.bData l Boolean value
ESS_DATETIME_T value.strData l String value
ESS_DOUBLE_T value.dtData l Date and time value

Double value
value.dblData
l
ESS_ATTRSPECS_T
Used by EssOtlSetAttributeSpecifications() to set attribute specifications for the outline, and
by EssOtlGetAttributeSpecifications() and EssGetAttributeSpecifications() to get attribute
specifications for the outline.
typedef struct ESS_ATTRSPECS_T
{
ESS_USHORT_T usGenNameBy;
ESS_USHORT_T usUseNameOf;
ESS_CHAR_T cDelimiter;
ESS_USHORT_T usDateFormat;
ESS_USHORT_T usBucketingType;
ESS_STR_T pszDefaultTrueString;
ESS_STR_T pszDefaultFalseString;
113
ESS_STR_T pszDefaultAttrCalcDimName;
ESS_STR_T pszDefaultSumMbrName;
ESS_STR_T pszDefaultCountMbrName;
ESS_STR_T pszDefaultAverageMbrName;
ESS_STR_T pszDefaultMinMbrName;
ESS_STR_T pszDefaultMaxMbrName;
} ESS_ATTRSPECS_T, *ESS_PATTRSPECS_T, **ESS_PPATTRSPECS_T;
ESS_ usGenNameBy A constant identifier indicating whether to use the generation(s) of the zero-level member
USHORT_T as the prefix or the suffix when generating a long name:
l ESS_GENNAMEBY_PREFIX (the default value)
l ESS_GENNAMEBY_SUFFIX
ESS_ usUseNameOf A constant identifier indicating which generation(s) of the zero-level member to use when
USHORT_T generating a long name:
l ESS_USENAMEOF_NONE (the default value)
l ESS_USENAMEOF_PARENT
l ESS_USENAMEOF_GRANDPARENTANDPARENT
l ESS_USENAMEOF_ALLANCESTORS
l ESS_USENAMEOF_DIMENSION
ESS_CHAR_T cDelimiter A constant identifier indicating the delimiter to use when generating a long name:
l ESS_DELIMITER_UNDERSCORE (the default value)
l ESS_DELIMITER_PIPE
l ESS_DELIMITER_CARET
ESS_ usDateFormat A constant identifier indicating the format for a datetime attribute:
USHORT_T
l ESS_DATEFORMAT_MMDDYYYY (the default value)
l ESS_DATEFORMAT_DDMMYYYY
ESS_ usBucketingType A constant identifier indicating a numeric attribute's bucketing type:

USHORT_T
l ESS_UPPERBOUNDINCLUSIVE (the default value)
l ESS_UPPERBOUNDNONINCLUSIVE
l ESS_LOWERBOUNDINCLUSIVE
l ESS_LOWERBOUNDNONINCLUSIVE
ESS_STR_T pszDefaultTrueString The string used with the boolean attribute to indicate TRUE. The default value is ESS_
DEFAULT_TRUESTRING ("True").
ESS_STR_T pszDefaultFalseString The string used with the boolean attribute to indicate FALSE. The default value is ESS_
DEFAULT_FALSESTRING ("False").
ESS_STR_T pszDefaultAttrCalcDimName The name of the attribute calculations (aggregate) dimension. The default value is ESS_
DEFAULT_ATTRIBUTECALCULATIONS ("Attribute Calculations").
ESS_STR_T pszDefaultSumMbrName The name used with the attribute calculations (aggregate) dimension to indicate SUM.
The default value is ESS_DEFAULT_SUM ("Sum").
114
ESS_STR_T pszDefaultCountMbrName The name used with the attribute calculations (aggregate) dimension to indicate COUNT.
The default value is ESS_DEFAULT_COUNT ("Count").
ESS_STR_T pszDefaultAverageMbrName The name used with the attribute calculations (aggregate) dimension to indicate
AVERAGE. The default value is ESS_DEFAULT_AVERAGE ("Average").
ESS_STR_T pszDefaultMinMbrName The name used with the attribute calculations (aggregate) dimension to indicate
MINIMUM. The default value is ESS_DEFAULT_MIN ("Min").
ESS_STR_T pszDefaultMaxMbrName The name used with the attribute calculations (aggregate) dimension to indicate
MAXIMUM. The default value is ESS_DEFAULT_MAX ("Max").
ESS_BLDDL_STATE_T
Contains information about dimension-build and data-load progress.
typedef struct ESS_BLDDL_STATE_T

{
ESS_USHORT_T usProcessState;
ESS_USHORT_T usProcessStage;
ESS_LONG_T ilProcessStatus;
ESS_ULONG_T ulRecordsProcessed;
ESS_ULONG_T ulRecordsRejected;
} ESS_BLDDL_STATE_T, *ESS_PBLDDL_STATE_T;
ESS_USHORT_T usProcessState The state of dimension build/data load process: whether it is in progress, in the final stages,
or completed. For values, see "Constant Values for usProcessState.
ESS_USHORT_T usProcessStage The stage of the dimension build/data load process: whether opening the data source, reading
the outline, building dimensions, verifying an outline, or writing an outline. For values, see
"Constant Values for usProcessStage."
ESS_LONG_T ilProcessStatus The status of the dimension build/data load process (same as function return status)
ESS_ULONG_T ulRecordsProcessed The number of data records processed so far
ESS_ULONG_T ulRecordsRejected The number of data records rejected so far
Constant Values for usProcessState
#define ESS_BLDDL_STATE_DONE 0 /* No process, or process complete */

#define ESS_BLDDL_STATE_INPROGRESS 1 /* Process is in progress */
#define ESS_BLDDL_STATE_FINALSTAGE 5 /* Process at final stage */
Constant Values for usProcessStage
#define ESS_BLDDL_STAGE_NONE 0 /* No process */

#define ESS_BLDDL_STAGE_OPENDATASOURCE 1 /* Process at opening data source */
115
#define ESS_BLDDL_STAGE_OPENOTL 2 /* Process at reading outline */
#define ESS_BLDDL_STAGE_BUILDOTL 3 /* Process at building dimension */
#define ESS_BLDDL_STAGE_VERIFYOTL 4 /* Process at verifying outline */
#define ESS_BLDDL_STAGE_WRITEOTL 5 /* Process at writing outline */
#define ESS_BLDDL_STAGE_RESTRUCT 6 /* Process at restructuring database */
#define ESS_BLDDL_STAGE_DATALOAD 7 /* Process at loading data */
#define ESS_BLDDL_STAGE_FINALIZE 8 /* Process at finalizing*/
ESS_CONNECTINFO_T
Stores information about the processes connected to a specific server.
typedef struct ESS_CONNECTINFO_T
{
ESS_USERNAME_T Name; /* logged in user name */
ESS_APPNAME_T AppName; /* connected application */
ESS_DBNAME_T DbName; /* connected database */
ESS_SVRNAME_T LoginMachine; /* login machine name */
ESS_ULONG_T LoginIP; /* IPv4 address of the login machine */
ESS_TIME_T LastLogin; /* login time */
}
ESS_CONNECTINFO_T, *ESS_CONNECTINFO_T, **ESS_CONNECTINFO_T;
ESS_USERNAME_T Name The name of the logged in user.
ESS_APPNAME_T AppName Name of currently connected application (if applicable).
ESS_DBNAME_T DbName Name of the currently connected database(if applicable).
ESS_SVRNAME_T LoginMachine The name of the logged in machine. If the machine name cannot be resolved on the network this
field contains the IP address formatted as a string. An asterisk (*) denotes the session which called
EssListLogins.
ESS_ULONG_T LoginIP The IP address of the logged in machine.
ESS_TIME_T LastLogin The time of the last login.
ESS_CONNECTINFOEX_T
Stores information about the processes connected to a specific server. This structure is similar
to ESS_CONNECTINFO_T, with the addition of the ProviderName and connparam fields.
typedef struct ESS_CONNECTINFOEX_T
{
ESS_USERNAME_T Name;
ESS_USERNAME_T ProviderName;
ESS_CONNPARAM_T connparam;
ESS_SVRNAME_T LoginMachine;
ESS_ULONG_T LoginIP;
ESS_TIME_T LastLogin;
116
}
ESS_CONNECTINFOEX_T, *ESS_PCONNECTINFOEX_T, **ESS_PPCONNECTINFOEX_T;
ESS_USERNAME_T Name Name of the logged in user
ESS_USERNAME_T ProviderName Name of the user directory. Example: @Native Directory
ESS_CONNPARAM_T connparam Unique identity attribute identifying user or group in a directory. Example:
native://nvid=f0ed2a6d7fb07688:5a342200:1265973105c:-7f46?
USER
ESS_APPNAME_T AppName Name of the currently connected application (if applicable)
ESS_DBNAME_T DbName Database name
ESS_SVRNAME_T LoginMachine Name of the logged in machine. If the machine name cannot be resolved on the network, this
field contains the IP address formatted as a string. An asterisk (*) denotes the session that called
EssListLogins.
ESS_ULONG_T LoginIP IP address of the logged in machine
ESS_TIME_T LastLogin Time of the last login
ESS_DBFILEINFO_T
Contains information on an index or data file retrieved by EssListDbFiles.
typedef struct ess_dbfileinfo_t
{
ESS_FILENAME_T FilePath;
ESS_SIZE_T FileSize;
ESS_USHORT_T FileSequenceNum;
ESS_USHORT_T FileCount;
ESS_USHORT_T FileType;
ESS_BOOL_T FileOpen;
} ESS_DBFILEINFO_T, *ESS_PDBFILEINFO_T, **ESS_PPDBFILEINFO_T;
ESS_APPNAME_T AppName Application name
ESS_FILENAME_T FilePath File path
ESS_SIZE_T FileSize File size in bytes
ESS_USHORT_T FileSequenceNum The 1-based sequence number of the file within the set of files of its FileType for the specified
database
ESS_USHORT_T FileCount Number of files of its FileType returned
117
ESS_USHORT_T FileType One of the following file types:

l ESS_FILETYPE_INDEX
l ESS_FILETYPE_DATA
ESS_BOOL_T FileOpen Flag indicating whether the file is open: 0 if the file is closed, nonzero if the file is open
ESS_DBINFO_T
This structure gets information about a specific database. Fields in this structure cannot be
modified using the API. See also the “ESS_DBSTATE_T” on page 121structure, which contains
additional database state parameters that can be modified, and the “ESS_DBSTATS_T” on page
124 structure. The fields are:
typedef struct ESS_DBINFO_T
{
ESS_DBNAME_T Name;
ESS_USHORT_T DbType;
ESS_USHORT_T nLocks;
ESS_ULONG_T nDims;
ESS_USHORT_T Data;
ESS_MBRNAME_T Country;
ESS_MBRNAME_T Time;
ESS_MBRNAME_T Category;
ESS_MBRNAME_T Type;
ESS_MBRNAME_T CrPartition;
ESS_TIME_T ElapsedDbTime;
ESS_ULONG64_T DataFileCacheSetting;
ESS_ULONG64_T DataFileCacheSize;
ESS_ULONG64_T DataCacheSetting;
ESS_ULONG64_T DataCacheSize;
ESS_ULONG_T IndexCacheSetting;
ESS_ULONG64_T IndexCacheSize;
ESS_ULONG_T IndexPageSetting;
ESS_ULONG_T IndexPageSize;
ESS_DBREQINFO_T DbReqInfoAry[ESS_DBREQNUM];
ESS_BOOL_T bDbReadOnly;
ESS_BOOL_T bDataCompress;
ESS_USHORT_T usDataCompressType;
ESS_ULONG_T ulRetrievalBuffer;
ESS_ULONG_T ulRetrievalSortBuffer;
ESS_BOOL_T bCacheMemLocking;
ESS_BOOL_T bPreImage;
ESS_USHORT_T usIsolationLevel;
ESS_LONG_T lTimeOut;
ESS_ULONG_T ulCommitBlocks;
ESS_ULONG_T ulCommitRows;
ESS_ULONG_T ulDiskVolumeCount;
ESS_DISKVOLUME_T aDiskVolume[1];
118
} ESS_DBINFO_T, *ESS_PDBINFO_T, **ESS_PPDBINFO_T;
ESS_APPNAME_T AppName The associated application name
ESS_DBNAME_T Name The database name
ESS_USHORT_T DbType Database type. Values:

l ESS_DBTYPE_NORMAL
l ESS_DBTYTPE_CURRENCY
ESS_USHORT_T Status DatabaseLoad status (loaded or not loaded . Values:

l ESS_STATUS_LOADED
ESS_USHORT_T nConnects Number of users currently connected to the database
ESS_USHORT_T nLocks Number of data blocks currently exclusively locked
ESS_ULONG_T nDims Number of dimensions in database
ESS_USHORT_T Data Flag indicating loading state of the data in the database.
Values:
ESS_DBDATA_NONE: no data loaded
ESS_DBDATA_LOADNOCALC: data loaded but not calculated
ESS_DBDATA_CLEAN: data loaded and calculated
ESS_MBRNAME_T Country The currency country dimension member, if any. If none, the
first byte is NULL.
ESS_MBRNAME_T Time Currency time dimension member, if any. If none, the first byte
is NULL.
ESS_MBRNAME_T Category The currency category dimension member, if any. If none, the
first byte is NULL.
ESS_MBRNAME_T Type Currency type dimension member (currency databases only).

If none exists, the first byte is NULL.
ESS_MBRNAME_T CrPartition The currency partition member (non-currency databases only)
ESS_TIME_T ElapsedDbTime Number of seconds the database has been loaded
ESS_ULONG64_T DataFileCacheSetting The Data File Cache Size setting value currently in effect.
ESS_ULONG64_T DataFileCacheSize The Run-time data file cache size (in KB) currently in use by
database. Note that once you have changed the data file
cache size you must stop and restart the database in order
for the new data file cache size to take effect.
119
ESS_ULONG64_T DataCacheSetting The Data Cache Size setting value (in KB) currently in effect.
ESS_ULONG64_T DataCacheSize The run-time size (in KB) of the Data Cache/
ESS_ULONG_T IndexCacheSetting The Index Cache Size (in KB) setting value currently in effect.
ESS_ULONG64_T IndexCacheSize Run-time size (in KB) of the Index Cache.
ESS_ULONG_T IndexPageSetting The Index Page Size setting (in KB) currently in effect.
ESS_ULONG_T IndexPageSize Run-time size (in KB) of an Index Page.
“ESS_DBREQINFO_T” on page 120 DbReqInfo, Ary[ESS_DBREQNUM] Array for request information, including last calc, dataLoad,
and outline update
ESS_BOOL_T bDbReadOnly TRUE if the database is in read-only mode; FALSE otherwise.
ESS_BOOL_T bDataCompress Optional compression flag (the default is YES).
ESS_USHORT_T usDataCompressType The data compression type if the optional compression flag is
set (the default is BitMap).
ESS_ULONG_T ulRetrievalBuffer Retrieval buffer size allocated per retrieval request (the default
is 2048 bytes).
ESS_ULONG_T ulRetrievalSortBuffer Retrieval sort buffer size allocated per retrieval request (the
default is 10240 bytes).
ESS_BOOL_T bCacheMemLocking TRUE if index and data cache memory pages are locked into
physical memory.
ESS_BOOL_T bPreImage Flag to read previously committed.
ESS_USHORT_T usIsolationLevel Isolation level (the default is UNCOMMITTED).
ESS_LONG_T lTimeOut Time out set in seconds for COMMITTED access only.
ESS_ULONG_T ulCommitBlocks The number of data blocks updated before the explicit commit
is performed (during calculation and grid updates).
ESS_ULONG_T ulCommitRows The number of rows of the input file processed before the
explicit commit is performed during the dataload.
ESS_ULONG_T ulDiskVolumeCount The number of disk volume settings for this database.
ESS_DISKVOLUME_T aDiskVolume[1] an array of disk volume settings
ESS_DBREQINFO_T
Used by EssGetDatabaseInfo(). Essbase has three types of requests for which information exists:
data load, calculation, and outline update. The following Essbase API constants identify each
type of request:
120
typedef struct ESS_DBREQINFO_T
{
ESS_ULONG_T DbReqType;
ESS_USERNAME_T User;
ESS_TIMERECORD_T StartTimeRec;
ESS_TIMERECORD_T EndTimeRec;
ESS_ULONG_T DbReqFlags;
} ESS_DBREQINFO_T, *ESS_PDBREQINFO_T;
Data Type Value Description
ESS_DBREQTYPE_DATLOAD 0 Data Load
ESS_DBREQTYPE_CALC 1 Calculation
ESS_DBREQTYPE_OTLUPD 2 Outline Update
The fields are:
ESS_ULONG_T DbReqType Type of database request
ESS_USERNAME_T User User name
“ESS_TIMERECORD_T” on page StartTimeRec Request start time

180
“ESS_TIMERECORD_T” on page EndTimeRec Request end time

180
ESS_ULONG_T DbReqFlags Bit map of information flags that provide additional information about the
database request. Used when DbReqType is CALC. Available flags:
l Default (currently contains no information). ESS API constant: ESS_
DBREQFLAG_CALCDEF (default calc was run)
l Custom calc script. ESS API constant: ESS_DBREQFLAG_CALCDSCR (custom
calc was run)
ESS_DBSTATE_T
This database state structure gets and sets the state parameters for a specific database. All fields
in this structure can be modified using the API. See also the “ESS_DBINFO_T” on page 118 and
“ESS_DBSTATS_T” on page 124 structures, which contain additional database information
that cannot be modified.
typedef struct ESS_DBSTATE_T
{
ESS_BOOL_T Loadable;
ESS_BOOL_T Autoload;
ESS_SHORT_T IndexType;
ESS_ULONG64_T MaxMem;
ESS_ULONG64_T MaxMemDataFileCache;
121
ESS_BOOL_T CalcNoAggMissing;
ESS_BOOL_T CalcNoAvgMissing;
ESS_BOOL_T CalcTwoPass;
ESS_BOOL_T CalcCreateBlock;
ESS_DBNAME_T CrDbName;
ESS_MBRNAME_T CrTypeMember;
ESS_USHORT_T CrConvType;
ESS_ULONG64_T MaxMemIndex;
ESS_ULONG_T IndexPageSize;
ESS_BOOL_T DataCompress;
ESS_USHORT_T DataCompressType;
ESS_ULONG_T RetrievalBuffer;
ESS_ULONG_T RetrievalSortBuffer;
ESS_BYTE_T cIOAccessFlagInUse; /* new for 6.5
ESS_BOOL_T bNoWaitIO; /* new for 6.5
ESS_USHORT_T IsolationLevel;
ESS_BOOL_T PreImage;
ESS_BYTE_T cIOAccessFlagPending; /* new for 6.5
ESS_LONG_T TimeOut;
ESS_ULONG_T CommitBlocks;
ESS_ULONG_T CommitRows;
ESS_ULONG_T nVolumes;
ESS_DISKVOLUME_T DiskVolume[1];
} ESS_DBSTATE_T, *ESS_PDBSTATE_T, **ESS_PPDBSTATE_T;
The fields are:
ESS_DESC_T Description The database description (up to 80 characters)
ESS_BOOL_T Loadable Flag to indicate whether the database can be loaded (ESS_TRUE if the database is
loadable)
ESS_BOOL_T Autoload Flag to indicate whether the database will be loaded automatically be loaded when the
application is started (ESS_TRUE if the database will be automatically loaded)
ESS_ACCESS_T Access The default access level to the database. See “Bitmask Data Types (C)” on page 90 for
a list of values this field can contain.
ESS_USHORT_T IndexType The database index type (array or tree). This field can contain the following values:
l ESS_INDEXTYPE_ARRAY
l ESS_INDEXTYPE_AVL
For API releases 4 and later, the IndexType field is obsolete.
ESS_ULONG64_T MaxMem The maximum memory reserved for non-compressed data blocks in the database (in
bytes)
ESS_ULONG64_T MaxMemDataFileCache The maximum memory reserved for the data file cache (in bytes)
ESS_BOOL_T CalcNoAggMissing Flag to suppress aggregation of members if all their children are missing (ESS_TRUE if
missing values are not aggregated)
ESS_BOOL_T CalcNoAvgMissing Flag to suppress inclusion of missing members in calculating averages (ESS_TRUE if
missing values are not included)
122
ESS_BOOL_T CalcTwoPass Flag to force two pass calculation when running full calculation of database (ESS_TRUE
if two pass calculation is enabled)
ESS_BOOL_T CalcCreateBlock Flag to force creation of data block on constant assignment calc equation (only valid
for sparse dimensions). Set to ESS_TRUE if blocks are forcibly created.
ESS_DBNAME_T CrDbName The name of associated currency database (valid in non-currency databases).
ESS_MBRNAME_T CrTypeMember The name of Currency Conversion type member (valid in non-currency databases)
ESS_USHORT_T CrConvType Currency Conversion type (whether currency conversions are calculated by
multiplication or division). Values:
l ESS_CRCTYPE_DIV
l ESS_CRCTYPE_MULT
ESS_ULONG64_T MaxMemIndex Minimum index cache size. Value: 1048576. Set using the constant ESS_
INDEXCACHEMIN_SIZE.
ESS_ULONG_T IndexPageSize Size of index page in which buffer pool is constructed in (in bytes).
Minimum index page size. Value: 1024. Set using the constant ESS_INDEXPAGEMIN_
SIZE
Maximum page size for the IndexPageSize field. Value: 8192. Set using the constant
ESS_INDEXPAGEMAX_SIZE
ESS_BOOL_T DataCompress Optional Flag to determine whether to compress blocks for this database.
ESS_USHORT_T DataCompressType The data compression type used for write operations if the optional compression flag
is set.
l Bitmap—Uses a bitmap to represent data cells (the default).
l Run-Length Encoding—Compresses any consecutive repetitive values.
l No Compression—Does not compress the data.
ESS_ULONG_T RetrievalBuffer Specifies the size, in bytes, of the server buffer that holds extracted row data cells before
they are evaluated by the RESTRICT, TOP, or BOTTOM commands. The default is 10240
bytes. The minimum is 2048 bytes and the maximum is 102400000 bytes.
ESS_ULONG_T RetrievalSortBuffer Specifies the size, in bytes, of the server buffer that holds the data to be sorted during
a retrieval. The minimum is 2048 bytes and the maximum is 102400000 bytes.
ESS_BYTE_T cIOAccessFlagInUse The type of I/O Access in use by the active current database. The two types of access
are ESS_IO_ACCESS_BUFFERED and ESS_IO_ACCESS_DIRECT. Even when
cIOAccessFlagPending has been set to ESS_IO_ACCESS_DIRECT, some operations
might still require buffering. Also direct access may not be supported on a given
platform. This field is read only.
ESS_BOOL_T bNoWaitIO This controls whether or not Essbase will wait for certain direct I/O operations to finish.
This only applies on platforms that support direct I/O and if cIOAccessFlag is ESS_IO_
ACCESS_DIRECT. This field is read only. The default is TRUE.
123
ESS_USHORT_T IsolationLevel The isolation level:

l COMMITTED—Write locks on all affected data blocks restrict access until the
transaction commits.
l UNCOMMITTED(default)—Write locks are acquired and released as needed during
the transaction.
ESS_BOOL_T PreImage The flag to read previously committed data during read-only requests. This flag can only
be set for COMMITTED access. The default is YES.
ESS_BYTE_T cIOAccessFlagPending The type of I/O Access (direct or buffered) that Essbase will use. This setting takes effect
after the next DBLoad (open operation).
ESS_LONG_T TimeOut The timeout interval in seconds. This can only be set for COMMITTED access.
-1 is Indefinite wait.
0 is Immediate access, no wait (the default).
n is the specified interval in seconds.
ESS_ULONG_T CommitBlocks The number of data blocks modified before performing the explicit commit (only used
when isolation level is UNCOMMITTED).
ESS_ULONG_T CommitRows The number of rows of the input file to data load before performing the explicit commit
(only used when isolation level is UNCOMMITTED).
ESS_ULONG_T nVolumes The number of disk volume settings for this database.
ESS_DISKVOLUME_T DiskVolume[1] An array of disk volume settings.
ESS_DBSTATS_T
This database statistics structure gets run-time statistical information about a specific database.
Fields in this structure cannot be modified using the API. See also the “ESS_DBSTATE_T” on
page 121 structure, which contains additional database state parameters that can be modified,
and the “ESS_DBINFO_T” on page 118 structure. The fields are:
typedef struct ESS_DBSTATS_T
{
ESS_USHORT_T IndexType;
ESS_ULONG_T nDims;
ESS_ULONG_T DeclaredBlockSize;
ESS_ULONG_T ActualBlockSize;
ESS_DOUBLE_T DeclaredMaxBlocks;
ESS_DOUBLE_T ActualMaxBlocks;
ESS_DOUBLE_T NonMissingLeafBlocks;
ESS_DOUBLE_T NonMissingNonLeafBlocks;
ESS_DOUBLE_T NonMissingBlocks;
ESS_DOUBLE_T PagedOutBlocks;
ESS_DOUBLE_T PagedInBlocks;
ESS_DOUBLE_T InMemCompBlocks;
ESS_DOUBLE_T TotalBlocks;
ESS_DOUBLE_T AverageFragmentationQuotient;
ESS_DOUBLE_T BytesOfRecoverableFreeSpace;
124
ESS_DOUBLE_T TotMemPagedInBlocks;
ESS_DOUBLE_T TotMemBlocks;
ESS_DOUBLE_T TotMemIndex;
ESS_DOUBLE_T TotMemInMemCompBlocks;
ESS_DOUBLE_T BlockDensity;
ESS_DOUBLE_T SparseDensity;
ESS_DOUBLE_T CompressionRatio;
ESS_DOUBLE_T ClusterRatio;
ESS_DIMSTATS_T DimStatsAry[1];
} ESS_DBSTATS_T, *ESS_PDBSTATS_T, **ESS_PPDBSTATS_T;
Note: Some application and database statistics may not be accurate when parallel data load,
parallel calculation, or parallel restructuring are in use. In particular, diagnostic statistics
(such as average clustering ratio, cache hit ratios, and data block density statistics) should
not be considered accurate in environments using parallel operations.
ESS_USHORT_T IndexType The database index type (array or tree). This field can contain the
following values:
l ESS_INDEXTYPE_ARRAY
l ESS_INDEXTYPE_AVL
ESS_ULONG_T nDims The number of dimensions in database.
ESS_ULONG_T DeclaredBlockSize The declared data block size.
ESS_ULONG_T ActualBlockSize The actual data block size
ESS_DOUBLE_T DeclaredMaxBlocks The declared maximum number of blocks in the database.
ESS_DOUBLE_T ActualMaxBlocks The actual maximum number of blocks in the database.
ESS_DOUBLE_T NonMissingLeafBlocks The number of non-missing leaf (lowest level) blocks in the
database.
ESS_DOUBLE_T NonMissingNonLeafBlocks The number of non-missing, non-leaf (upper level) blocks in the
database.
ESS_DOUBLE_T NonMissingBlocks Obsolete. Returns zero.
ESS_DOUBLE_T PagedOutBlocks The number of database blocks currently paged out to disk.
ESS_DOUBLE_T PagedInBlocks The total number of database blocks currently paged into memory.
ESS_DOUBLE_T InMemCompBlocks The number of database blocks currently paged into compressed
memory.
ESS_DOUBLE_T TotalBlocks Total number of existing data blocks (not the maximum).
ESS_DOUBLE_T AverageFragmentationQuotient Percentage of space within the data file that is free space or not
used by Essbase.
125
ESS_DOUBLE_T BytesOfRecoverableFreeSpace l Estimated bytes of recoverable free space

l -1 if free space recovery is not necessary
ESS_DOUBLE_T TotMemPagedIn-Blocks The total memory used for all paged-in (uncompressed) database
blocks.
ESS_DOUBLE_T TotMemBlocks The total memory used for all database blocks.
ESS_DOUBLE_T TotMemIndex The total memory used for the database index.
ESS_DOUBLE_T TotMemInMemCompBlocks The total memory used for database blocks currently paged into
compressed memory.
ESS_DOUBLE_T BlockDensity The average database block density (calculated using all currently
loaded blocks).
ESS_DOUBLE_T SparseDensity Average density of the sparse dimensions in the database.
ESS_DOUBLE_T CompressionRatio Average data block compression ratio on the disk.
ESS_DOUBLE_T ClusterRatio A measure of the fragmentation of the page file. A value close to
1 indicates the degree of fragmentation is low. A value close to
zero indicates a high degree of fragmentation that could affect
calculation and query performance.
“ESS_DIMSTATS_T” on page 127 DimStatsAry [1] Dynamic array (with nDim elements) of Dimension Statistical
Structures, of type ESS_DIMSTATS_T. See the structure definition.
ESS_DIMENSIONINFO_T
Used in EssGetDimensionInfo(). The fields are:
typedef struct ESS_DIMENSIONINFO_T
{
ESS_DIMNUM_T DimNumber;
ESS_USHORT_T DimType;
ESS_USHORT_T DimTag;
ESS_ULONG_T DeclaredDimSize;
ESS_ULONG_T ActualDimSize;
ESS_USHORT_T DimDataType;
} ESS_DIMENSIONINFO_T, *ESS_PDIMENSIONINFO_T, **ESS_PPDIMENSIONINFO_T;
ESS_MBRNAME_T DimName Dimension name
ESS_DIMNUM_T DimNumber Dimension number
126
ESS_USHORT_T DimType Dimension type. Values:

l ESS_DIMTYPE_DENSE
l ESS_DIMTYPE_SPARSE
ESS_USHORT_T DimTag Dimension tag type. Values:

l ESS_TTYPE_ATTRCALC
l ESS_TTYPE_ATTRIBUTE
l ESS_TTYPE_CCATEGORY
l ESS_TTYPE_CNAME
l ESS_TTYPE_CTIME
l ESS_TTYPE_NONE
l ESS_TTYPE_CPARTITION
l ESS_TTYPE_CTYPE
ESS_ULONG_T DeclaredDimSize Declared dimension size
ESS_ULONG_T ActualDimSize Actual dimension size
ESS_DESC_T Description Reserved (not currently supported)
ESS_USHORT_T DimDataType Attribute dimension data type. Values:

l ESS_ATTRMBRDT_BOOL
l ESS_ATTRMBRDT_DATETIME
l ESS_ATTRMBRDT_DOUBLE
l ESS_ATTRMBRDT_STRING
ESS_DIMSTATS_T
This is a Dimension Statistical Structure used to get information about a specific database
dimension. Fields in this structure cannot be modified using the API. An array of these structures
is included at the end of the “ESS_DBSTATS_T” on page 124 structure to provide information
about each dimension in the database. The fields are:
typedef struct ESS_DIMSTATS_T
{
ESS_USHORT_T DimType;
ESS_ULONG_T DeclaredDimSize;
ESS_ULONG_T ActualDimSize;
} ESS_DIMSTATS_T, *ESS_PDIMSTATS_T;
ESS_MBRNAME_T DimName The dimension member name
127
ESS_USHORT_T DimType The dimension type (sparse or dense). This field can contain the following values:
l ESS_DIMTYPE_DENSE
ESS_ULONG_T DeclaredDimSize The declared dimension size (the number of members declared in the specified dimension,
including any label only or shared members in that dimension)
ESS_ULONG_T ActualDimSize The actual dimension size (the number of members in the specified dimension, excluding any
label only or shared members in that dimension)
ESS_DTAPICOLUMN_T
Defines the header information for a specific column.
typedef struct ESS_DTAPICOLUMN_T
{
ESS_LONG_T nColumnIdx;
ESS_LONG_T nDisplayOrder
ESS_CHAR_T sViewName[ESS_MBRNAMELEN];
ESS_CHAR_T sColumnName[ESS_MBRNAMELEN];
ESS_USHORT_T uDatatype;
ESS_LONG_T nSortOrder;
ESS_LONG_T nSortSequence;
ESS_BOOL_T bFilterOnly;
ESS_CHAR_T sFilter[ESS_MAX_DATALEN + 1];
} ESS_DTAPICOLUMN_T, *ESS_PDTAPICOLUMN_T, **ESS_PPDTAPICOLUMN_T;
ESS_LONG_T nColumnIdx 0-based index of the column position (read only)
ESS_LONG_T nDisplayOrder The order in which columns are displayed
ESS_CHAR_T sViewName [ESS_MBRNAMELEN] (read only)
ESS_CHAR_T sColumnName [ESS_MBRNAMELEN] Heading text for the given column of data (read only)
ESS_USHORT_T uDataType Data type of the given column of data

l ESS_DT_STRING
l ESS_DT_DATETIME
l ESS_DT_DOUBLE
ESS_LONG_T nSortOrder
ESS_LONG_T nSortSequence
ESS_BOOL_T bFilterOnly ESS_TRUE = filter only.
ESS_CHAR_T sFilter [ESS_MAX_DATALEN + 1]
128
ESS_DTAPIDATA_T
Defines the report data for a specific data cell.
typedef struct ESS_DTAPIDATA_T
{
ESS_ULONG_T nRowIdx;
ESS_ULONG_T nColumnIdx;
ESS_CHAR_T sData[ESS_MAX_DATALEN + 1];
} ESS_DTAPIDATA_T, *ESS_PDTAPIDATA_T, **ESS_PPDTAPIDATA_T;
ESS_ULONG_T nRowIdx 0-indexed row number for the given data block
ESS_ULONG_T nColumnIdx 0-indexed column number for the given data block
ESS_CHAR_T sData [ESS_MAX_DATALEN + 1] Data value for the given data block
ESS_DTAPIHEADER_T
Defines header information for a specific column.
typedef struct __ess_dtapiheader_t
{
ESS_ULONG_T nColumnIdx ;
ESS_CHAR_T sViewName[ESS_MBRNAMELEN] ;
ESS_CHAR_T sColumnName[ESS_MBRNAMELEN] ;
ESS_USHORT_T uDatatype ;
} ESS_DTAPIHEADER_T, *ESS_PDTAPIHEADER_T, **ESS_PPDTAPIHEADER_T ;
ESS_ULONG_T nColumnIdx 0-indexed column number for the given data block.
ESS_CHAR_T sViewName [ESS_MBRNAMELEN]
ESS_CHAR_T sColumnName [ESS_DESCRIPTION_LEN + 1] Data value for the given data block.
ESS_USHORT_T uDatatype
ESS_DTAPIINFO_T
Defines the connection information for a range of data cells.
typedef struct ESS_DTAPIINFO_T
{
ESS_CHAR_T sHisName[ESS_MAX_NAME + 1];
ESS_CHAR_T sUsername[ESS_MAX_NAME + 1];
ESS_CHAR_T sPassword[ESS_MAX_NAME + 1];
ESS_USHORT_T uInputOption;
} ESS_DTAPIINFO_T, *ESS_PDTAPIINFO_T, **ESS_PPDTAPIINFO_T;
129
ESS_CHAR_T sHisName [ESS_MAX_NAME + 1]
ESS_CHAR_T sUsername [ESS_MAX_NAME + 1]
ESS_CHAR_T sPassword [ESS_MAX_NAME + 1] (write only)
ESS_USHORT_T uInputOption (read only)
ESS_DTAPIREPORT_T
Defines the header information for a specific column.
typedef struct ESS_DTAPIREPORT_T
{
ESS_LONG_T nReportId;
ESS_CHAR_T sName[ESS_DTREPORT_NAME + 1];
ESS_LONG_T nCustomize;
ESS_LONG_T nRowGovernor;
ESS_LONG_T nTimeGovernor;
} ESS_DTAPIREPORT_T, *ESS_PDTAPIREPORT_T, **ESS_PPDTAPIREPORT_T;
ESS_LONG_T nReportId
ESS_CHAR_T sName [ESS_DTREPORT_NAME + 1]
ESS_LONG_T nCustomize
ESS_LONG_T nRowGovernor
ESS_LONG_T nTimeGovernor
ESS_DTBUFFER_T
Defines a report data cell.
typedef struct ESS_DTBUFFER_T
{
ESS_ULONG_T row;
ESS_ULONG_T column;
ESS_CHAR_T data[ESS_DESCRIPTION_LEN + 1];
} ESS_DTBUFFER_T, *ESS_PDTBUFFER_T, **ESS_PPDTBUFFER_T;
ESS_ULONG_T row 0-indexed row number for the given data block.
ESS_ULONG_T column 0-indexed column number for the given data block.
ESS_CHAR_T data [ESS_DESCRIPTION_LEN + 1] Data value for the given data block.
130
ESS_DTDATA_T
typedef struct ESS_DTDATA_T
{
ESS_ULONG_T row;
ESS_ULONG_T column;
} ESS_DTDATA_T, *ESS_PDTDATA_T, **ESS_PPDTDATA_T;
ESS_ULONG_T row 0-indexed row number for the given data block.
ESS_ULONG_T column 0-indexed column number for the given data block.
ESS_CHAR_T data [ESS_DESCRIPTION_LEN + 1] Data value for the given data block.
ESS_DTHEADER_T
typedef struct ESS_DTHEADER_T
{
ESS_ULONG_T colIndex;
ESSDTREPORTDATATYPE dataType;
} ESS_DTHEADER_T, *ESS_PDTHEADER_T, **ESS_PPDTHEADER_T;
ESS_ULONG_T colIndex 0-based index of the column position.
ESSDTREPORTDATATYPE dataType Data type of the given column of data.
ESS_CHAR_T data [ESS_DESCRIPTION_LEN + 1] Heading text for the given column of data.
ESS_DISKVOLUME_REPLACE_T
Contains the names of the source and destination disk volume labels. The source currently exists,
and will be replaced with the destination.
typedef_struct ess_diskvolume_replace_t
{
ESS_FILENAME_T, szPartition_Src;
ESS_FILENAME_T, szPartition_Dest;
} ESS_DISKVOLUME_REPLACE_T;
ESS_FILENAME_T szPartition_Src Name of disk partition to be replaced.
131
ESS_FILENAME_T szPartition_Dest Name of disk partition with which to replace szPartition_Src
ESS_DURLINFO_T
Captures drill-through URL information.
See “Drill-through URL Limits” on page 1257.
typedef struct url
{
ESS_CHAR_T bIsLevel0;
ESS_STR_T cpURLName;
ESS_USHORT_T iURLXmlSize;
ESS_BYTE_T* cpURLXml;
ESS_USHORT_T iCountOfDrillRegions;
ESS_PSTR_T cppDrillRegions;
} ESS_DURLINFO_T;
ESS_CHAR_T bIsLevel0 If 1, then URL definition is restricted to level-0 data; if 0, there is no restriction
ESS_STR_T cpURLName Name of the drill-through URL
ESS_USHORT_T iURLXmlSize Size of the URL XML text
ESS_BYTE_T* cpURLXml Pointer to the URL XML text
ESS_USHORT_T icountOfDrillRegions Number of regions referenced by the drill-through URL

The number of drillable regions in a drill-through URL is limited to 256.
ESS_PSTR_T cppdrillRegions List of regions referenced by the drill-through URL
ESS_EXTUSERINFO_T
Stores information about an externally authenticated user. The fields are:
typedef struct ESS_EXTUSERINFO_T
{
ESS_BOOL_T Login;
ESS_USHORT_T Type;
ESS_ACCESS_T MaxAccess;
ESS_DATE_T Expiration;
ESS_TIME_T DbConnectTime;
ESS_USHORT_T FailCount;
ESS_LOGINID_T LoginId;
132
ESS_EMAIL_T EMailID;
ESS_BOOL_T LockedOut;
ESS_BOOL_T PwdChgNow;
ESS_USHORT_T authType;
ESS_PROTOCOL_T protocol;
ESS_CONNPARAM_T connParam;
} ESS_EXTUSERINFO_T, *ESS_PEXTUSERINFO_T, **ESS_PPEXTUSERINFO_T,;
ESS_USERNAME_T Name User name
ESS_APPNAME_T AppName Name of currently connected application (if applicable)
ESS_DBNAME_T DbName Name of the currently connected database (if applicable)
ESS_BOOL_T Login Flag to indicate login status.
ESS_USHORT_T Typ Type of the structure. This field can contain the following values:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
ESS_ACCESS_T Access User assigned default access privileges. Values: any combination of the following bit values:
l ESS_ACCESS_SUPER /* Supervisor, all bits set */
l ESS_PRIV_APPCREATE /* App create/delete privilege */
l ESS_PRIV_USERCREATE /* user create/delete privilege */
ESS_ACCESS_T MaxAccess User's maximum access privileges (including individual access and access levels due to group
membership).
ESS_DATE_T Expiration User's password expiration date.
ESS_TIME_T LastLogin Date of user's last successful login stated as Greenwich Mean Time.
ESS_TIME_T DbConnectTime Local (server) time of database connection. Read-only. Cannot be set by EssSetUser.
ESS_USHORT_T FailCount Count of the failed login attempts since the last successful login.
ESS_LOGINID_T LoginId The user login identification tag.
ESS_DESC_T Description User description.
ESS_EMAIL_T EMailID User email address.
ESS_BOOL_T LockedOut Flag that user is locked out.
ESS_BOOL_T PwdChgNow Flag that user must change password.
ESS_USHORT_T authType Authentication type.
ESS_PROTOCOL_T protocol External authentication protocol: CSS for Shared Services mode.
ESS_CONNPARAM_T connParam External authentication connection parameters. Null if protocol is CSS.
133
ESS_GENLEVELNAMEEX_T
Contains information about generation or level names and the member-name uniqueness
settings for generation and levels. The fields are:
typedef_struct ESS_GENLEVELNAMEEX_T)
{
ESS_USHORT_T, usNumber;
ESS_BOOL_T, bNameUnique;
ESS_MBRNAME_T, szName;
} ESS_GENLEVELNAMEEX_T, ESS_PGENLEVELNAMEEX_T, ESS_GENLEVELNAMEEX_T **,

ESS_PPGENLEVELNAMEEX_T;
ESS_USHORT_T usNumber Generation or level number
ESS_BOOL_T bNameUnique Generation or level member-name uniqueness
ESS_MBRNAME_T szName Generation or level name
ESS_GLOBAL_T
Contains global server system parameters used for administrative purposes. All of the fields in
this structure except Currency can be modified using the API. The fields are:
typedef struct ESS_GLOBAL_T
{
ESS_BOOL_T Security;
ESS_BOOL_T Logins;
ESS_USHORT_T Validity;
ESS_BOOL_T Currency;
ESS_USHORT_T PwMin;
ESS_TIME_T InactivityTime;
ESS_TIME_T InactivityCheck;
ESS_USHORT_T InvalidAttempts;
ESS_USHORT_T InactivityLockout;
ESS_USHORT_T NumPwExpWarn;
ESS_USHORT_T PwStoredNum;
} ESS_GLOBAL_T, *ESS_PGLOBAL_T, **ESS_PPGLOBAL_T;
ESS_BOOL_T Security Flag to indicate whether global security is enabled (default is ESS_TRUE, indicating security is
enabled)
ESS_BOOL_T Logins Flag to indicate whether user logins are enabled (default is ESS_TRUE, indicating logins are
enabled).
134
ESS_ACCESS_T Access The default access level for newly-created applications (default is ESS_ACCESS_NONE). See
“Bitmask Data Types (C)” on page 90 for a list of possible values.
ESS_USHORT_T Validity The default password validity period (default is 365 days).
ESS_BOOL_T Currency Flag to indicate whether currency option is supported (this flag is read only). Set to ESS_TRUE if
the currency option is enabled.
ESS_USHORT_T PwMin The minimum permitted password length (default is 6 characters).
ESS_TIME_T InactivityTime Maximum length of time, in seconds, the user can be inactive before automatic logout from all
applications and the Agent. Default value: 3600 seconds. Minimum value: 300 seconds. To disable
auto logout, set InactivityTime to 0.
ESS_TIME_T InactivityCheck Frequency of checks for auto logout, in seconds. Default value: 300 seconds. Minimum value: 30
seconds. Must be smaller than InactivityTime setting or InactivityCheck is set to the value of
InactivityTime and a warning message occurs. To disable auto logout, set InactivityCheck to 0.
ESS_USHORT_T InvalidAttempts The number of invalid attempts allowed by a user before the system administrator is warned and
the user is locked out.
ESS_USHORT_T InactivityLockout The duration of a period of inactivity (betweeen logins) for any user before that user is locked out
(default is 365 days)
ESS_USHORT_T NumPwExpWarn The number of expired password warnings issued to a user before that user is locked out.
ESS_USHORT_T PwStoredNum The number of passwords stored for any user.
ESS_INIT_T
Passed to the API initialization function EssInit() and contains fields that let API developers
customize their usage of the API. If any of the fields of the structure are set to zero (or NULL
for pointers), the API defaults are used. (See “Using Memory in C Programs” on page 78 for
more information.).
typedef struct ESS_INIT_T

{
ESS_ULONG_T Version;
ESS_PVOID_T UserContext;
ESS_USHORT_T MaxHandles;
ESS_SIZE_T MaxBuffer;
ESS_STR_T LocalPath;
ESS_STR_T MessageFile;
ESS_PFUNC_T AllocFunc;
ESS_PFUNC_T ReallocFunc;
ESS_PFUNC_T FreeFunc;
ESS_PFUNC_T MessageFunc;
ESS_STR_T HelpFile;
ESS_ULONG_T Ess_System;
#ifdef AD_UTF8
ESS_USHORT_T, usApiType;
#endif
ESS_PCATCHFUNC_T, CatchFunc;
135
ESS_PCATCH_INIT_FUNC_T, CatchInitFunc;
ESS_PCATCH_TERM_FUNC_T, CatchTermFunc;
ESS_PCOOKIE_CREATE_FUNC_T, CookieCreateFunc;
ESS_PCOOKIE_DELETE_FUNC_T, CookieDeleteFunc;
} ESS_INIT_T, *ESS_PINIT_T;
ESS_ULONG_T Version Version of Essbase API used to compile the application. Should be set to ESS_API_VERSION.
Used for backward compatibility.
ESS_PVOID_T UserContext An optional pointer to a user-defined message context (passed as argument to a user-defined
MessageFunction)
ESS_USHORT_T MaxHandles The maximum number of simultaneous context handles required by the API program (between
1 and 255). The default is 255. Reducing this number may decrease the amount of client
memory used within the API for your program.
ESS_SIZE_T MaxBuffer The maximum size buffer that can be allocated in the client program (typically 64 KB). The
default is 64 KB.
ESS_STR_T LocalPath The default local path name to use for file and object operations on the client. If this is not set,
Essbase uses the ESSBASEPATH environment variable by default, and appends \CLIENT to
the directory name passed in. .
ESS_STR_T MessageFile Qualified path name of the message database file, ESSBASE.MDB. If this is not set, Essbase
first tries to use the fully qualified path in the ARBORMSGPATH environment variable, otherwise,
it uses (ESSBASEPATH)\BIN\ESSBASE.MDB. If ESSBASEPATH is not defined, an error is
returned at run time.
ESS_PFUNC_T AllocFunc Pointer to the user-defined memory allocation function. All platforms: memory allocation
functions use the malloc() function.
ESS_PFUNC_T ReallocFunc Pointer to the user-defined memory reallocation function. All platforms: memory allocation
functions use the realloc() function.
ESS_PFUNC_T FreeFunc A pointer to the user-defined memory free function. All platforms: memory allocation functions
use the free() function.
ESS_PFUNC_T MessageFunc A pointer to the user-defined message callback function. Messages sent to the user-defined
Callback function are passed to Essbase in EssInit. Previous to Release 6.2, if a message
contained NLS characters (foreign language characters, such as accented characters), Essbase
provided them in OEM (DOS) format. In Release 6.2 and later, these messages are completely
in character (Windows) format, to avoid the misinterpretation of certain characters. This only
affects localized versions of Essbase.
ESS_STR_T HelpFile Fully-qualified path name of the user-defined application help file, used for help for the
AutoLogin dialog box. The login help context must be defined in the help file.
See Chapter 3, “Integrating Essbase With Your Product.”
If ESSBASEPATH is not defined, the help file name is set to null.
ESS_ULONG_T Ess_System Reserved for internal use. Set to NULL
ESS_USHORT_T usApiType Required. Defines whether the program is in Unicode or non-Unicode mode. For valid values,
see “Unicode Mode Constants (C)” on page 101.
136
typedef ESS_ CatchFunc If implemented by the client, Essbase calls this function intermittently (every few seconds)
BOOL_T (*ESS_ during queries. If the routine retuns TRUE, the API call gets canceled.
PCATCHFUNC_T)
(ESS_HCTX_T);
typedef ESS_STS_ CatchInitFunc This function initializes resources for whatever state is needed for the CatchFunc call. For
T (*ESS_PCATCH_ example, if you want to terminate a query based on whether a user hits the ESC key, and
INIT_FUNC_T) CatchFunc calls on a routine to get data from the keyboard, you may need to pre-initialize
(ESS_ HCTX _T); memory so that it is not initialized for every CatchFunc call.
Essbase executes the following process during a query:
1. Calls CatchInitFunc, if it is non NULL.
2. Executes query, intermittently calling CatchFunc.
3. Calls CatchTermFunc, if it is non NULL.
typedef ESS_STS_ CatchTermFunc This function terminates resources initialized by CatchInitFunc.

T (*ESS_PCATCH_
TERM_FUNC_T)
(ESS_ HCTX _T);
typedef ESS_STS_ CookieCreateFunc Essbase calls this function at SetActive time. You would use this function if user information is
T (*ESS_ required for the CatchFunc, CatchInitFunc, or CatchTermFunc calls. For example, if you want to
PCOOKIE_ terminate a query based on certain user activities, you may need to create a cookie to be used
CREATE_FUNC_T) by the CatchFunc call. You obtain the cookie by calling EssGetCookie.
(ESS_HCTX_T);
typedef ESS_STS_ CookieDeleteFunc This function deletes the cookie created by CookieCreateFunc. Essbase calls this function at
T (*ESS_ ClearActive time.
PCOOKIE_
DELETE_FUNC_T)
(ESS_HCTX_T);
Query Cancellation Using Essbase API

Programs developed using the Essbase API can optionally register custom query-cancellation
functions at initialization. ESS_INIT_T has five fields that enable development of custom
callback functions for query cancellation. These fields are CatchFunc, CatchInitFunc,
CatchTermFunc, CookieCreateFunc, and CookieDeleteFunc. By default, they are set to null.
Query Cancellation Usage Example

The following code enables query cancellation when the Escape key is hit. KbdHitEx gets the
next key that was entered from the keyboard, and writes the value of the key to
kbfinfo.chChar.
ESS_INIT_STRUCT InitStruct;
InitStruct.CatchFunc = KillReqCatcher;
ESS_BOOL_T KillReqCatcher(ESS_HCTX_T hCtx)

{
KBDINFO_T kbinfo;
if (KbdHitEx(&kbfinfo) && kbfinfo.chChar == KB_ESC)
return ESS_TRUE;
137
else
return ESS_FALSE;
}
However, suppose the routine KdbHitEx requires that an initialization routine

InitializeMyKeyboard be called first, and a terminate TerminateMyKeyboard routine be
called later. Here you would use CatchInitFunc and CatchTermFunc.
InitStruct.CatchInitFunc = InitKeyboard;
InitStruct.CatchTermFunc = TerminateKeyboard;
ESS_STS_T InitKeyboard (ESS_HCTX_T hCtx)

{
return InitializeMyKeyboard ();
}
ESS_STS_T TerminateKeyboard (ESS_HCTX_T hCtx)
{
return TerminateMyKeyboard ();
}
Now suppose that the InitializeMyKeyboard and TerminateMyKeyboard routines need

to retain status information. You can use a cookie to retain the status. The cookie created by
CookieCreateFunc can be accessed in CatchFunc, CatchInitFunc, and CatchTermFunc by
EssGetCookie.
InitStruct.CatchInitFunc = InitKeyboard2;
InitStruct.CatchTermFunc = TerminateKeyboard2;
InitStruct.CookieCreateFunc = AllocKeyboardState;
InitStruct.CookieDeleteFunc = FreeKeyboardState;
ESS_STS_T InitKeyboard2 (ESS_HCTX_T hCtx)

{
ESS_PVOID_T cookie;
ESS_STS_T sts;
sts = EssGetCookie(hCtx, &cookie);
if (sts)
return sts;
return InitializeMyKeyboard (cookie);
}
ESS_STS_T TerminateKeyboard2 (ESS_HCTX_T hCtx)

{
ESS_PVOID_T cookie;
ESS_STS_T sts;
sts = EssGetCookie(hCtx, &cookie);
if (sts)
return sts;
return TerminateMyKeyboard (cookie);

}
ESS_STS_T AllocKeyboardState(ESS_PVOID_T pKbdState)
{
*pKbdState = malloc(KBDSTRUCT_SIZE);
if (*pKbdState)
return 0;
else
return -1;
138
}
ESS_STS_T FreeKeyboardState (ESS_PVOID_T kbdState)
{
if (kbdState)
free(kbdState);
return 0;
}
ESS_LOAD_BUFFER_T
Contains information about aggregate storage data load buffers. It is used by
EssListExistingLoadBuffers.
typedef struct ESS_LOAD_BUFFER_T
{
ESS_ULONG_T ulBufferId;
ESS_ULONG_T ulDuplicateAggregationMethod;
ESS_ULONG_T ulOptionFlags;
ESS_ULONG_T ulSize;
ESS_BOOL_T bInternal;
ESS_BOOL_T bActive;
ESS_BOOL_T bReserved01;
ESS_BOOL_T bReserved02;
ESS_ULONG_T ulReserved01;
} ESS_LOAD_BUFFER_T;
ESS_ ulBufferId ID of a data load buffer (a number between 1 and 4294967296).

ULONG_T
ESS_ ulDuplicateAggregationMethod One of the following constants describing how to combine multiple values for the same
ULONG_T cell within the buffer:
l ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD: Add values when the
buffer contains multiple values for the same cell.
l ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ASSUME_EQUAL: Verify that
multiple values for the same cells are identical, and ignore the duplicates if they
are. Stop the data load with an error message if they differ.
l ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_USE_LAST: Use the last value
loaded into the buffer as the final value for the cell.
ESS_ ulOptionFlags Either (or a combination) of the following load buffer options:
ULONG_T
l ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES
l ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES
ESS_ ulSize The percentage of the aggregate storage cache that the data load buffer is allowed to
ULONG_T use (a number between 1 and 100, inclusive)
ESS_BOOL_T bInternal ESS_TRUE if the buffer was created by Essbase; ESS_FALSE for user-created buffers
ESS_BOOL_T bActive ESS_TRUE if the buffer is currently in use by a data load
139
ESS_BOOL_T bReserved01 Not used
ESS_BOOL_T bReserved02 Not used
ESS_ ulReserved01 Not used

ULONG_T

ULONG_T

ULONG_T
ESS_LOCKINFO_T
Contains information about data blocks exclusively locked, as returned by the istLocks()
function. Fields in this structure cannot be modified using the API.
typedef struct ESS_LOCKINFO_T
{
ESS_USERNAME_T UserName;
ESS_TIME_T Time;
} ESS_LOCKINFO_T, *ESS_PLOCKINFO_T, **ESS_PPLOCKINFO_T;
ESS_USERNAME_T UserName The user name
ESS_USHORT_T nLocks The number of blocks exclusively locked by this user
ESS_TIME_T Time The maximum time (in seconds) that blocks have been exclusively locked
ESS_LOGINID_T LoginId The user login identification tag
ESS_LOCKINFOEX_T
Contains information about data blocks exclusively locked, as returned by the ListLocks()
function. This structure is similar to ESS_LOCKINFO_T, with the addition of the
ProviderName and connparam fields. Fields in this structure cannot be modified using the API.
typedef struct ESS_LOCKINFOEX_T
{
ESS_CONNPARAM_T connparam
ESS_TIME_T Time;
} ESS_LOCKINFOEX_T, *ESS_PLOCKINFOEX_T, **ESS_PPLOCKINFOEX_T;
140
ESS_USERNAME_T UserName User name
ESS_CONNPARAM_T connparam Unique identity attribute identifying user or group in a directory. Example:
USER
ESS_USHORT_T nLocks Number of blocks exclusively locked by the user
ESS_TIME_T Time Maximum time (in seconds) that blocks have been exclusively locked
ESS_LOGINID_T LoginId User login identification tag
ESS_LOG_DATALOAD_T
Contains metadata describing dataloads.
typedef_struct ESS_LOG_DATALOAD_T
{
ESS_OBJTYPE_T, datfile_type;
ESS_UCHAR_T, datfile_loc;
ESS_FILENAME_T, dat_filename;
ESS_UCHAR_T, isRuleFile;
ESS_UCHAR_T, rulfile_loc;
ESS_FILENAME_T, rul_filename;
ESS_USERNAME_T, sql_username;
ESS_PASSWORD_T, sql_password;
ESS_UCHAR_T, isAbortOnErr;
ESS_ULONG_T, reserved0;
} ESS_LOG_DATALOAD_T;
ESS_OBJTYPE_T datfile_type Data file type
ESS_UCHAR_T datfile_loc Data file location/SQL
ESS_FILENAME_T dat_filename Data file name
ESS_UCHAR_T isRuleFile Is there a rule file
ESS_UCHAR_T rulfile_loc Rule file location
ESS_FILENAME_T rul_filename Rule file name
ESS_USERNAME_T sql_username SQL connection username
ESS_PASSWORD_T sql_password SQL connection password
ESS_UCHAR_T isAbortOnErr Is there an error file name required
141
ESS_ULONG_T reserved0–2 Reserved for future use
ESS_MBRALT_T
Contains information about a specified member alias table. Fields in this structure cannot be
modified using the API. The fields are:
typedef struct ESS_MBRALT_T
{
ESS_MBRNAME_T AltName;
} ESS_MBRALT_T, *ESS_PMBRALT_T, **ESS_PPMBRALT_T;
ESS_MBRNAME_T MbrName The member name
ESS_MBRNAME_T AltName The associated alias name
ESS_MBRERR_T
Used for a linked list of member errors.
typedef struct ESS_MBRERR_T
{
struct ess_mbrerr_t *pNext;
ESS_USHORT_T ErrType;
ESS_STR_T Name;
ESS_STR_T Record;
} ESS_MBRERR_T, *ESS_PMBRERR_T, **ESS_PPMBRERR_T;
struct ESS_MBRERR_T *pNext Pointer to next structure in list
ESS_USHORT_T ErrType The type of error
ESS_STR_T Name The member name
ESS_STR_T Record The file record containing the error
ESS_MBRUSER_T
An external data source user information structure. Fields in this structure cannot be modified
by the API. The fields are:
typedef struct ESS_MBRUSER_T
{
ESS_STR_T User;
142
ESS_STR_T Password;
} ESS_MBRUSER_T, *ESS_PMBRUSER_T;
ESS_STR_T User The external data source user name
ESS_STR_T Password The external data source password
ESS_MEMBERINFO_T
Contains information about a specified database member. Fields in this structure cannot be
modified using the API. The fields are:
typedef struct ESS_MEMBERINFO_T
{
ESS_MEMNUM_T MbrNumber;
ESS_DIMNUM_T DimNumber;
ESS_SHORT_T Level;
ESS_SHORT_T Generation;
ESS_SHORT_T UnaryCalc;
ESS_USHORT_T MbrTagType;
ESS_BOOL_T CurrConvert;
ESS_MBRNAME_T CrMbrName;
ESS_MBRNAME_T ParentMbrName;
ESS_MBRNAME_T ChildMbrName;
ESS_MBRNAME_T PrevMbrName;
ESS_MBRNAME_T NextMbrName;
ESS_BOOL_T fAttributed;
} ESS_MEMBERINFO_T, *ESS_PMEMBERINFO_T, **ESS_PPMEMBERINFO_T;
ESS_MBRNAME_T MbrName The member name
ESS_MEMNUM_T MbrNumber The member number in the database outline
ESS_MBRNAME_T DimName The member's dimension name
ESS_DIMNUM_T DimNumber The member's dimension number
143
ESS_USHORT_T Status The member's share status is derived by performing a logical AND between the
contents of this field and each of the constant values of the form
l ESS_MBRSTS_xxx:
l ESS_MBRSTS_NOTSET
l ESS_MBRSTS_NEVER
l ESS_MBRSTS_LABEL
l ESS_MBRSTS_REFER
l ESS_MBRSTS_REFNME
l ESS_MBRSTS_SHARE
l ESS_MBRSTS_VIRTSTORE
l ESS_MBRSTS_VIRTNOSTORE
ESS_SHORT_T Level The member level number (zero-based), counting up from the lowest descendent
of the specified member
ESS_SHORT_T Generation The member generation number (one-based), counting down from the specified
member's dimension member
ESS_SHORT_T UnaryCalc The default unary rollup for this member. A value of the form ESS_UCALC_xxx
(add, subtract, multiply, divide, percent, none, or never).
ESS_UCALC_ADD
ESS_UCALC_SUB
ESS_UCALC_MULT
ESS_UCALC_DIV
ESS_UCALC_PERCENT
ESS_UCALC_NOOP
ESS_UCALC_NEVER
ESS_USHORT_T MbrTagType A 16 bit mask for the member's tagged types. A value of the form ESS_ATYPE_
xxx.
ESS_BOOL_T CurrConvert Currency Conversion. Values: ESS_TRUE and ESS_FALSE
ESS_MBRNAME_T CrMbrName Name of the tagged currency database member.

l For Time dimension, gives the name of the tagged time member.
l For Country dimension, gives the name of the tagged currency member.
l For Accounts dimension, gives the name of the tagged category member.
ESS_DESC_T Description Member description
ESS_MBRNAME_T ParentMbrName Specified member's parent member name or empty string if member has no parent
ESS_MBRNAME_T ChildMbrName Specified member's first child member name
ESS_MBRNAME_T PrevMbrName Specified member's previous sibling member name
ESS_MBRNAME_T NextMbrName Specified member's next sibling member name
ESS_BOOL_T fAttributed Indicates whether the member has attributes associated with it. Values: ESS_
TRUE and ESS_FALSE.
144
“ESS_ATTRIBUTEVALUE_T” on Attribute Attribute value

page 113
ESS_NEWSHAREDSERVICESNATIVEUSERINFO_T
Contains the user names and corresponding passwords resulting from a migration of users and
groups to Shared Services using the option of automatically generated password assignment.
Users were created as new Shared Services users during migration because there were no
matching names found. The fields are:
typedef struct ESS_NEWSHAREDSERVICESNATIVEUSERINFO_T)
{
ESS_USERNAME_T, Name;
ESS_PASSWORD_T, Password;
} ESS_NEWHUBNATIVEUSERINFO_T;
ESS_USERNAME_T Name User or group name.
ESS_PASSWORD_T Password User password.
ESS_OBJDEF_T
Provides summary object information. It is used by EssImport and EssBuildDimension. The
fields in this structure cannot be modified by the API.
typedef struct ESS_OBJDEF_T
{
ESS_HCTX_T hCtx;
ESS_OBJTYPE_T ObjType;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
} ESS_OBJDEF_T, *ESS_POBJDEF_T;
ESS_HCTX_T hCtx Object context handle
ESS_OBJTYPE_T ObjType Object type. See “Bitmask Data Types (C)” on page 90 for a list of object types.
ESS_STR_T AppName Application name
ESS_STR_T DbName Database name
145
ESS_STR_T FileName 8-character object file name with no extension. This name is a local file name when all of the following
apply:
l hCtx is a local context handle
l AppName and DbName are NULL
l FileName points to the full path name of a local file
ESS_OBJINFO_T
Contains information about a specific file object. You cannot modify fields in this structure
through the API. The fields are:
typedef struct ESS_OBJINFO_T
{
ESS_OBJNAME_T Name;
ESS_OBJTYPE_T Type;
ESS_ULONG_T FileSize;
ESS_BOOL_T Locked;
ESS_USERNAME_T User;
ESS_TIME_T TimeStamp;
ESS_TIMERECORD_T TimeModified;
} ESS_OBJINFO_T, *ESS_POBJINFO_T, **ESS_PPOBJINFO_T;
ESS_OBJNAME_T Name Object name
ESS_OBJTYPE_T Type Object type. See “Bitmask Data Types (C)” on page 90 for a list of object types.
ESS_APPNAME_T AppName Application name
ESS_ULONG_T FileSize Object's allocated file size on disk (in bytes)
ESS_BOOL_T Locked Flag to indicate whether object is locked on the server (ESS_TRUE indicates the
object is locked)
ESS_USERNAME_T User Name of the user who has the object locked (if locked), otherwise undefined
ESS_TIME_T TimeStamp Date and time object was locked (if locked), otherwise undefined
“ESS_TIMERECORD_T” on page 180 TimeModified Date and time of last modification
ESS_PART_T
Main shared partition data structure.
typedef struct ESS_PART_T
{
146
ESS_PARTHDR_T file_header;
ESS_USHORT_T part_count;
ESS_PARTDEF_T *parts;
ESS_ULONG_T maxserialno;
} ESS_PART_T, *ESS_PPART_T, **ESS_PPPART_T;
“ESS_PARTHDR_T” on page 153 file_header File header.
ESS_USHORT_T partition_count Number of shared partitions.
“ESS_PARTDEF_T” on page 151 partitions Array of shared partition definitions.
ESS_ULONG_T maxserialno High water mark for serial number.
ESS_PART_CONNECT_INFO_T
Specifies a database.
typedef struct ESS_PART_CONNECT_INFO_T
{
ESS_STR_T pszHostName;
ESS_STR_T pszAppName;
ESS_STR_T pszDbName;
} ESS_PART_CONNECT_INFO_T, *ESS_PPART_CONNECT_INFO_T, **ESS_PPPART_CONNECT_INFO_T;
ESS_STR_T pszHostName Host name.
ESS_STR_T pszAppName Application name.
ESS_STR_T pszDbName Database name.
ESS_PART_DEFINED_T
Specifies a shared partition.
typedef struct ESS_PART_DEFINED_T
{
ESS_USHORT_T usType;
ESS_USHORT_T usDirection;
ESS_PART_CONNECT_INFO_T HostDatabase;
} ESS_PART_DEFINED_T, *ESS_PPART_DEFINED_T, **ESS_PPPART_DEFINED_T;
ESS_USHORT_T usType One of the Operation Type constants listed below.
ESS_USHORT_T usDirection One of the Directions constants listed below.
“ESS_PART_CONNECT_INFO_T” on page 147 HostDatabase The host server.
147
Operation Type Constants
define ESS_PARTITION_OP_REPLICATED 0x0001
define ESS_PARTITION_OP_LINKED 0x0002
define ESS_PARTITION_OP_TRANSPARENT 0x0004
define ESS_PARTITION_OP_ALLTYPES (ESS_PARTITION_OP_REPLICATED |
ESS_PARTITION_OP_LINKED |
ESS_PARTITION_OP_TRANSPARENT)
Direction Constants
define ESS_PARTITION_DATA_SOURCE 0x0001
define ESS_PARTITION_DATA_TARGET 0x0002
define ESS_PARTITION_DATA_BOTH (ESS_PARTITION_DATA_SOURCE |
ESS_PARTITION_DATA_TARGET)
ESS_PART_INFO_T
Holds the multicube shared partition information.
typedef struct ESS_PART_INFO_T
{
ESS_USHORT_T OperationType;
ESS_USHORT_T DataDirection;
ESS_USHORT_T MetaDirection;
ESS_SVRNAME_T SvrName;
ESS_TIME_T LastMetaUpdateTime;
ESS_TIME_T LastRefreshTime;
ESS_BOOL_T AreaUpdatable;
ESS_BOOL_T IncrRefreshAllowed;
ESS_TIME_T LastUpdateTime;
} ESS_PART_INFO_T, *ESS_PPART_INFO_T, **ESS_PPPART_INFO_T;
ESS_USHORT_T OperationType Operation type supported by this partition.
ESS_USHORT_T DataDirection Remote connection information (is this the source or target side?).
ESS_SVRNAME_T SvrName Host for the other side of the partition definition.
ESS_APPNAME_T AppName Application for the other side of the partition definition.
ESS_DBNAME_T DbName Database for other side of the partition definition; meta data change information.
ESS_TIME_T LastMetaUpdateTime Last time meta data was updated.
The following fields only apply to replication data targets
ESS_TIME_T LastRefreshTime Last time data at target was refreshed.
ESS_BOOL_T partitionUpdatable Are changes allowed to replicated data?
148
The following fields only apply to replication data sources
ESS_BOOL_T IncrRefreshAllowed Can we refresh only the changed data?
ESS_TIME_T LastUpdateTime Time of last change to data in the partition.

#define ESS_PARTITION_OP_REPLICATED 0x0001
#define ESS_PARTITION_OP_LINKED 0x0002
#define ESS_PARTITION_OP_TRANSPARENT 0x0004
#define ESS_PARTITION_OP_ALLTYPES (ESS_PARTITION_OP_REPLICATED |
Direction Constants
#define ESS_PARTITION_DATA_SOURCE 0x0001
#define ESS_PARTITION_DATA_TARGET 0x0002
#define ESS_PARTITION_DATA_BOTH (ESS_PARTITION_DATA_SOURCE |
ESS_PART_REPL_T
Queries shared partitions.
typedef struct ESS_PART_REPL_T
{
ESS_LONG_T lAreaCount;
ESS_BOOL_T bUpdatedOnly;
ESS_PPART_CONNECT_INFO_T pHostDatabase;
} ESS_PART_REPL_T, *ESS_PPART_REPL_T, **ESS_PPPART_REPL_T;
ESS_LONG_T lPartitionCount Number of partitions to refresh from (-1 == ALL)
ESS_BOOL_T bUpdatedOnly Refreshes only the cells modified at the source since the last refresh
operation.
“ESS_PART_CONNECT_INFO_T” on page 147 pHostDatabase Array of partition specifications.
ESS_PARTDEF_INVALID_T
This is the shared partition verification structure.
typedef struct ESS_PARTDEF_INVALID_T
{
ESS_USHORT_T error_type;
ESS_ULONG_T line_number;
ESS_ULONG_T overlap_number;
ESS_CHAR_T member_name[ESS_MBRNAMELEN];
149
ESS_CHAR_T error_message[ESS_LINELEN];
} ESS_PARTDEF_INVALID_T, *ESS_PPARTDEF_INVALID_T, **ESS_PPPARTDEF_INVALID_T;
ESS_USHORT_T error_type One of the Error constants listed below.
ESS_ULONG_T line_number Line number for the erroneous line.

For partition defn: line number
For global map: line number
For slice map: slice number.
ESS_ULONG_T overlap_number Slice number for overlapped slices, partition number for overlapped partition.
ESS_CHAR_T member_name[ESS_MBRNAMELEN] Erroneous member name, used only for mapping rules.
ESS_CHAR_T error_message[ESS_LINELEN] One of the Error constants listed below.
Error Constants
define ESS_PARTITION_DEF_ERROR = 1
define ESS_PARTITION_GLOBAL_MAP_ERROR = 2
define ESS_PARTITION_AREA_MAP_ERROR = 3
define ESS_PARITITON_AREA_OVERLAP_ERROR = 4
define ESS_PARTITION_OVERLAP_ERROR = 5
define ESS_PARTITION_CELLCOUNT_MISMATCH = 6
define ESS_PARTITION_TYPE_CONFLICT = 8
define ESS_PARTITION_DEFAULT_LOGIN_ERROR = 9
define ESS_PARTITION_INVALID_USER = 10
define ESS_PARTITION_INVALID_PW = 11
ESS_PARTDEF_CONNECT_T
Holds connection information.
typedef struct ESS_PARTDEF_CONNECT_T
{
ESS_CHAR_T svrname[ESS_SVRNAMELEN];
ESS_CHAR_T appname[ESS_APPNAMELEN];
ESS_CHAR_T dbname[ESS_DBNAMELEN];
ESS_CHAR_T username[ESS_USERNAMELEN];
ESS_CHAR_T password[ESS_PASSWORDLEN];
} ESS_PARTDEF_CONNECT_T, *ESS_PPARTDEF_CONNECT_T, **ESS_PPPARTDEF_CONNECT_T;
ESS_CHAR_T svrname [ESS_SVRNAMELEN] Server name.
ESS_CHAR_T appname [ESS_APPNAMELEN] Application name.
ESS_CHAR_T dbname [ESS_DBNAMELEN] Database name.
ESS_CHAR_T username [ESS_USERNAMELEN] Administrator username.
150
ESS_CHAR_T password [ESS_PASSWORDLEN] Administrator password.
ESS_PARTDEF_MAP_T
Holds mapping information.
typedef struct ESS_PARTDEF_MAP_T
{
ESS_ULONG_T mbr_count;
ESS_STR_T *src_mbrs;
ESS_STR_T *dest_mbrs;
} ESS_PARTDEF_MAP_T, *ESS_PPARTDEF_MAP_T, **ESS_PPPARTDEF_MAP_T;
ESS_ULONG_T mbr_count Size of remapping arrays.
ESS_STR_T src_mbrs Array of member names at src.
ESS_STR_T dest_mbrs Array of member names at target.
ESS_PARTDEF_T
Contains the partition definition.
typedef struct ESS_PARTDEF_T
{
ESS_PARTDEF_CONNECT_T connection;
ESS_STR_T description;
ESS_PARTDEF_AREAS_T shape_defn;
ESS_PARTDEF_TYPE_T typedata;
ESS_ULONG_T serialno;
ESS_TIME_T meta_last_updated;
} ESS_PARTDEF_T, *ESS_PPARTDEF_T, **ESS_PPPARTDEF_T;
“ESS_PARTDEF_CONNECT_T” on page 150 connection Connection information.
ESS_STR_T description User's description of partition.
“ESS_PARTDEF_AREAS_T” on page 152 shape_defn Shape definition.
“ESS_PARTDEF_TYPE_T” on page 152 typedata Type-specific data.
ESS_ULONG_T serialno 1-based ID for shared partitions.
ESS_TIME_T meta_last_updated Last restructure affecting this partition.
151
ESS_PARTDEF_AREAS_T
Holds shape definitions. A shape is composed of multiple slices.
typedef struct ESS_PARTDEF_AREAS_T
{
ESS_USHORT_T slice_count;
ESS_STR_T *slices;
} ESS_PARTDEF_AREAS_T, *ESS_PPARTDEF_AREAS_T, **ESS_PPPARTDEF_AREAS_T;
ESS_USHORT_T slice_count Number of slices.
ESS_STR_T slices Array of slice definition strings.
ESS_PARTDEF_TYPE_T
Holds partition type-specific information.
typedef struct ESS_PARTDEF_TYPE_T
{
ESS_USHORT_T operation_type;
ESS_USHORT_T direction_type;
ESS_USHORT_T meta_direction_type;
ESS_PARTDEF_MAP_T area_map;
ESS_PARTDEF_MAP_T *slice_maps;
ESS_TIME_T last_refreshed;
ESS_BOOL_T incr_refresh;
ESS_BOOL_T updatable;
ESS_CHAR_T defaultuser[ESS_USERNAMELEN];
ESS_CHAR_T defaultpass[ESS_PASSWORDLEN];
} ESS_PARTDEF_TYPE_T, *ESS_PPARTDEF_TYPE_T, **ESS_PPPARTDEF_TYPE_T;
ESS_USHORT_T operation_type One of the Operation Type constants listed below.
ESS_USHORT_T direction_type One of the Direction constants listed below.

Note: Fields marked as SVR: should only be modified by
server code.
ESS_USHORT_T meta_direction_type Source of metadata identified by one of the Direction

constants listed below.
The following fields are applicable for replication sources
ESS_BOOL_T incr_refresh SVR: incr. refresh allowed?
The following fields are applicable for all targets
“ESS_PARTDEF_MAP_T” on page 151 partition_map Main shared partition member map.
“ESS_PARTDEF_MAP_T” on page 151 slice_maps Slice-specific mappings.
152
The following fields are applicable to replication targets
ESS_TIME_T last_refreshed SVR: time of last refresh.
ESS_BOOL_T updatable Is data at target updatable?
The following fields are applicable to link targets
ESS_CHAR_T defaultuser [ESS_USERNAMELEN] Default username
ESS_CHAR_T defaultpass [ESS_PASSWORDLEN] Default password
define ESS_PARTITION_OP_REPLICATED 0x0001

define ESS_PARTITION_OP_LINKED 0x0002
define ESS_PARTITION_OP_TRANSPARENT 0x0004
define ESS_PARTITION_OP_ALLTYPES (ESS_PARTITION_OP_REPLICATED |
define ESS_PARTITION_DATA_SOURCE 0x0001

define ESS_PARTITION_DATA_TARGET 0x0002
define ESS_PARTITION_DATA_BOTH (ESS_PARTITION_DATA_SOURCE |
ESS_PARTHDR_T
Specifies an Essbase database and application.
typedef struct ESS_PARTHDR_T
{
ESS_SVRNAME_T zServer;
ESS_APPNAME_T zApplication;
ESS_DBNAME_T zDatabase;
ESS_USERNAME_T zUser;
ESS_TIME_T tTime;
} ESS_PARTHDR_T, *ESS_PPARTHDR_T, *ESS_PPPARTHDR_T;
ESS_SVRNAME_T zServer The server name.
ESS_APPNAME_T zApplication The application name.
ESS_DBNAME_T zDatabase The database name.
ESS_USERNAME_T zUser The user name.
ESS_TIME_T tTime Last restructure affecting this partition.
153
ESS_PARTOTL_CHANGE_API_T
typedef struct ESS_PARTOTL_CHANGE_API_T
{
ESS_ULONG_T ulDimensionCount;
ESS_PPARTOTL_DIMCHG_API_T pDimchg;
ESS_ULONG_T ulAliasTableCount;
ESS_PPARTOTL_NAMEMAP_API_T pAliasTableChg;
} ESS_PARTOTL_CHANGE_API_T, *ESS_PPARTOTL_CHANGE_API_T, **ESS_PPPARTOTL_CHANGE_API_T;
ESS_ULONG_T ulDimensionCount Number of dimension changes.
“ESS_PARTOTL_DIMCHG_API_T” on page 156 pDimchg Pointer to a link list of dimension changes.
ESS_ULONG_T ulAliasTableCount Count of alias table changes.
“ESS_PARTOTL_NAMEMAP_API_T” on page 161 pAliasTableChg Linked list of table changes.
Notes
The ESS_PARTOTL_CHANGE_API_T structure categorizes database outline changes by
dimensions. This structure is passed in when EssSmDbOtlRestruct() is called. An outline change
is composed of a set of dimension changes and a set of alias table changes. Dimension changes
are passed as a linked list pointed to by pDimChg. Each item in the linked list represents the
changes made to the dimension; it also has a root pointer pMemberChange which points to a
linked list of member changes.
Alias table changes are passed as a linked list pointed to by pAliasTableChg. Each item in the
linked list represents the changes in an alias table. Currently, only Add, and Delete operations
are supported. The following highlights the alias table change operations
When an alias table is deleted, changed records show an alias table deletion. There is no change
record for any alias which is deleted along with the alias table. Alias changes are recorded as
member updates. Alias changes are reflected regardless of the status of the alias table, that is, the
alias table does not have to be "active".
Renaming an alias table is interpreted as deleting an alias table with the old name and adding
an alias table with the new name. Aliases in the renamed alias table are new aliases.
ESS_PARTOTL_CHG_FILE_T
Specifies metadata change files.
typedef struct ESS_PARTOTL_CHG_FILE_T
{
ESS_USHORT_T usFileNum;
ESS_PSTR_T ppszFileName;
} ESS_PARTOTL_CHG_FILE_T, *ESS_PPARTOTL_CHG_FILE_T, **ESS_PPPARTOTL_CHG_FILE_T;
154
ESS_USHORT_T usFileNum Number of meta change files.
ESS_PSTR_T ppszFileName Array of meta change file names.
ESS_PARTOTL_DIM_ATTRIB_API_T
Specifies the attributes of the specified dimension.
typedef struct ESS_PARTOTL_DIM_ATTRIB_API_T
{
ESS_USHORT_T usDimType;
ESS_USHORT_T usDimTag;
ESS_ULONG_T ulOldDimNo;
ESS_ULONG_T ulNewDimNo;
ESS_ULONG_T ulNamedLevNum;
ESS_PARTOTL_NAMED_GENLEV_API_T *pNamedLev;
ESS_ULONG_T ulNamedGenNum;
ESS_PARTOTL_NAMED_GENLEV_API_T *pNamedGen;
ESS_STR_T pszBasememberName;
ESS_STR_T pszOldName;
ESS_STR_T pszNewName;
} ESS_PARTOTL_DIM_ATTRIB_API_T, *ESS_PPARTOTL_DIM_ATTRIB_API_T,
**ESS_PPPARTOTL_DIM_ATTRIB_API_T;
ESS_USHORT_T usDimType One of the Dimension Type constants listed below.
ESS_USHORT_T usDimTag One of the Dimension Tag constants listed as type

ESS_TTYPE_XXX below.
ESS_ULONG_T ulOldDimNo The dimension number in the old outline.
ESS_ULONG_T ulNewDimNo The dimension number in the new outline.
ESS_ULONG_T ulNamedLevNum The number of named levels.
“ESS_PARTOTL_NAMED_GENLEV_API_T” on page 161 pNamedLev The pointer to an array of named level structures.
ESS_ULONG_T ulNamedGenNum The number of named generations.
“ESS_PARTOTL_NAMED_GENLEV_API_T” on page 161 pNamedGen The pointer to an array of named generations

structures.
ESS_STR_T pszBasememberName The base member name for the add and delete
dimensions.
ESS_STR_T pszOldName The old dimension name.
155
ESS_STR_T pszNewName The new dimension names pszOldName and

pszNewName are used only for rename. Note that a
dimension rename implies renaming both the
dimension and the top-most member in this
dimension
Dimension Type Constants (usDimType)

define ESS_DIMTYPE_DENSE 0
define ESS_DIMTYPE_SPARSE 1
Dimension Tag Constants (usDimTag)

#define ESS_TTYPE_NONE 0
#define ESS_TTYPE_CCATEGORY 1 /* Accounts - currency ACCOUNTS tag */
#define ESS_TTYPE_CNAME 2 /* Country - currency COUNTRY tag */
#define ESS_TTYPE_CTIME 3 /* Time - currency TIME tag */
#define ESS_TTYPE_CTYPE 4 /* Type - currency TYPE tag */
#define ESS_TTYPE_CPARTITION 5 /* Currency Partition tag */
#define ESS_TTYPE_ATTRIBUTE 6 /* Attribute tag */
#define ESS_TTYPE_ATTRCALC 7 /* Attribute calc tag(Internal) */
ESS_PARTOTL_DIMASSOCCHG_API_T
Contains information on the attribute dimension name and level as well as the dimension
association change type.
typedef struct ESS_PARTOTL_DIMASSOCCHG_API_T
{
ESS_SHORT_T usDimAssocChgType;
ESS_CHAR_T *pszAttrDimName;
ESS_SHORT_T usLevel;
struct ess_partotl_dimassocchg_api_t *pNext;
} ESS_PARTOTL_DIMASSOCCHG_API_T;
ESS_SHORT_T usDimAssocChgType Dimension association change type
ESS_CHAR_T pszAttrDimName Attribute dimension name
ESS_SHORT_T usLevel Dimension association level
ESS_PARTOTL_DIMASSOCCHG_API_T pNext Pointer to the next structure
ESS_PARTOTL_DIMCHG_API_T
Specifies a change to the outline, specifically a change to a dimension.
typedef struct ESS_PARTOTL_DIMCHG_API_T
{
ESS_USHORT_T usDimChgType;
156
ESS_PARTOTL_DIM_ATTRIB_API_T DimAttribute;
ESS_PARTOTL_MBR_RSRVD_API_T MemberReserved;
ESS_ULONG_T ulMemberChanges;
ESS_PPARTOTL_MBRCHG_API_T pMemberChange;
ESS_USHORT_T usAttrType;
ESS_USHORT_T usDimAssocChgCnt;
ESS_PARTOTL_DIMASSOCCHG_API_T *pDimAssocChg;
struct ess_partotl_dimchg_api_t *pNext;
} ESS_PARTOTL_DIMCHG_API_T, *ESS_PPARTOTL_DIMCHG_API_T, **ESS_PPPARTOTL_DIMCHG_API_T;
ESS_USHORT_T usDimChgType One of the dimension change

(ESS_OTL_DIMCHG_T)
constants listed below
“ESS_PARTOTL_DIM_ATTRIB_API_T” on page 155 DimAttribute Dimension attributes
“ESS_PARTOTL_MBR_RSRVD_API_T” on page 157 MemberReserved Reserved
The following two fields are only valid when ESS_PARTITION_OTLDIM_MBRCHG

is one of the dimension change types.
ESS_ULONG_T ulMemberChanges Number of member changes
“ESS_PARTOTL_MBRCHG_API_T” on page 159 pMemberChange Pointer to the linked list of

member changes
ESS_USHORT_T usAttrType Attribute type
ESS_USHORT_T usDimAssocChgCnt Number of dimension

associations
“ESS_PARTOTL_DIMASSOCCHG_API_T” on page 156 pDimAssocChg Linked list of dimension

associations
ESS_PARTOTL_DIMCHG_API_T pNext Pointer to the next dimension

change
Dimension Change (ESS_OTL_DIMCHG_T) Constants

The following constants are defined for the usDimChgType field of the
ESS_PARTOTL_DIMCHG_API_T structure:
ESS_PARTITION_OTLDIM_ADD /* Add dimensions */
ESS_PARTITION_OTLDIM_DELETE /* Delete dimensions */
ESS_PARTITION_OTLDIM_UPDATE /* Update dimensions */
ESS_PARTITION_OTLDIM_MOVE /* Move dimensions */
ESS_PARTITION_OTLDIM_RENAME /* Rename dimensions */
ESS_PARTITION_OTLDIM_MBRCHG /* */
ESS_PARTITION_OTLDIM_ALL /* All of the above */
ESS_PARTOTL_MBR_RSRVD_API_T
Specifies reserved member operations.
157
typedef struct ESS_PARTOTL_MBR_RSRVD_API_T
{
ESS_BOOL_T breject;
ESS_PARTOTL_OSN_RELATIVES_API_T *pSrcRelatives;
ESS_PARTOTL_OSN_RELATIVES_API_T *pDstRelatives;
ESS_VOID_T *unused;
} ESS_PARTOTL_MBR_RSRVD_API_T, *ESS_PPARTOTL_MBR_RSRVD_API_T,
**ESS_PPPARTOTL_MBR_RSRVD_API_T;
ESS_BOOL_T breject TRUE rejects this record (for Outline Synchronization only).
“ESS_PARTOTL_OSN_RELATIVES_API_T” on page 162 *pSrcRelatives Source parent and sibling
“ESS_PARTOTL_OSN_RELATIVES_API_T” on page 162 *pDstRelatives Destination parent and sibling
ESS_VOID_T *unused (Unused)
ESS_PARTOTL_MBRASSOCCHG_API_T
Contains information on the attribute dimension and member name, as well as the attribute
value.
typedef struct ESS_PARTOTL_MBRASSOCCHG_API_T
{
ESS_CHAR_T *pszAttrDimName;
ESS_CHAR_T *pszAttrMbrName;
ESS_CHAR_T *pszAttrParName;
ESS_ATTRIBUTEVALUE_T AttrValue;
struct ess_partotl_mbrassocchg_api_t *pNext;
} ESS_PARTOTL_MBRASSOCCHG_API_T;
ESS_CHAR_T pszAttrDimName Attribute dimension name
ESS_CHAR_T pszAttrMbrName Attribute member name
ESS_CHAR_T pszAttrParName Attribute parent name
“ESS_ATTRIBUTEVALUE_T” on page 113 AttrValue Attribute value
ESS_PARTOTL_MBRASSOCCHG_API_T pNext Pointer to the next structure
ESS_PARTOTL_MBRATTR_API_T
Stores member attribute information.
typedef struct ESS_PARTOTL_MBRATTR_API_T
{
ESS_STS_T status;
ESS_SHORT_T level;
ESS_SHORT_T generation;
158
ESS_CHAR_T *calc;
ESS_SHORT_T ucal;
ESS_USHORT_T atype;
ESS_BOOL_T nocconvert;
ESS_CHAR_T *crMbrName;
ESS_PARTOTL_NAMECHG_API_T *pUdaChange;
ESS_PARTOTL_NAMECHG_API_T *pAliasChange;
} ESS_PARTOTL_MBRATTR_API_T,*ESS_PPARTOTL_MBRATTR_API_T,**ESS_PPPARTOTL_MBRATTR_API_T;
ESS_STS_T status Member status.
ESS_SHORT_T level Level number.
ESS_SHORT_T generation Generation.
ESS_CHAR_T calc Calculation equation.
ESS_SHORT_T ucalc Unary calculation symbol for this member.
ESS_USHORT_T atype A 16 bit mask for members of the dimension tagged as ACCOUNT.
This is not used elsewhere. By default, they are all OFF.
ESS_BOOL_T nocconvert Default to FALSE, do currency conversion.
ESS_CHAR_T crMbrName The name of the tagged currency database member

FOR TIME -- tagged Time Member
FOR COUNTRY -- tagged currency Member
FOR ACCOUNTS -- tagged category Member
“ESS_PARTOTL_NAMECHG_API_T” on page 160 pUdaChange User defined attributes changes.
“ESS_PARTOTL_NAMECHG_API_T” on page 160 pAliasChange Alias changes.
ESS_PARTOTL_MBRCHG_API_T
Specifies a member change operation.
typedef struct ESS_PARTOTL_MBRCHG_API_T
{
ESS_ULONG_T ulOperator;
ESS_CHAR_T *pszOperand1;
ESS_ULONG_T ulOperand1;
ESS_PARTOTL_MBRATTR_API_T *pMemberAttribute;
ESS_PARTOTL_MBR_RSRVD_API_T MemberReserved;
ESS_ULONG_T ulMbrAssocChgCnt;
ESS_PARTOTL_MBRASSOCCHG_API_T *pMbrAssocChg;
struct ess_partotl_mbrchg_api_t *pNext;
} ESS_PARTOTL_MBRCHG_API_T,*ESS_PPARTOTL_MBRCHG_API_T, **ESS_PPPARTOTL_MBRCHG_API_T;
159
ESS_ULONG_T ulOperator One of the member change (ESS_MBR_CHANGE_T)

constants listed below
ESS_CHAR_T pszOperand1 Alphabetic operand 1
ESS_ULONG_T ulOperand1 A bit-field operand that indicates updated attributes of the

given member. This field is only used when the member
change operator is ESS_PARTITION_OTLMBR_UPDATE.
“ESS_PARTOTL_MBRATTR_API_T” on page 158 pMemberAttribute The pointer to a member attribute structure. The value is
null for delete and rename.
“ESS_PARTOTL_MBR_RSRVD_API_T” on page 157 MemberReserved Reserved
ESS_ULONG_T ulMbrAssocChgCnt Number of member associations
“ESS_PARTOTL_MBRASSOCCHG_API_T” on page 158 pMbrAssocChg Linked list of member associations
ESS_PARTOTL_MBRCHG_API_T pNext Pointer to the next structure
Member Change (ESS_MBR_CHANGE_T) Constants

The following constants are defined for the ulOperator field of the
ESS_PARTOTL_MBRCHG_API_T structure:
ESS_PARTITION_OTLMBR_ADD /* Add members */
ESS_PARTITION_OTLMBR_DELETE /* Delete members */
ESS_PARTITION_OTLMBR_RENAME /* Rename members */
ESS_PARTITION_OTLMBR_MOVE /* Move members */
ESS_PARTITION_OTLMBR_UPDATE /* Update members */
ESS_PARTITION_OTLMBRATTR_STATUS /* Status changes */
ESS_PARTITION_OTLMBRATTR_ALIAS /* Alias changes */
ESS_PARTITION_OTLMBRATTR_UCALC /* Unary calc symbol changes */
ESS_PARTITION_OTLMBRATTR_ATYPE /* Account type changes */
ESS_PARTITION_OTLMBRATTR_CCONVERT /* Currency conversion flag */
ESS_PARTITION_OTLMBRATTR_CRMBRNAME /* Tagged currency database member */
ESS_PARTITION_OTLMBRATTR_UDA /* User defined attribute changes */
ESS_PARTITION_OTLMBRATTR_CALC /* Calc formula changes */
ESS_PARTITION_OTLMBRATTR_LEVEL /* Level number changes */
ESS_PARTITION_OTLMBRATTR_GENERATION /* Generation number changes */
ESS_PARTITION_OTLMBRATTR_ATTRIBUTE /* Attribute changes */
ESS_PARTITION_OTLMBRATTR_ALL /* All of the above */
ESS_PARTOTL_NAMECHG_API_T
Records name changes.
160
typedef struct ESS_PARTOTL_NAMECHG_API_T
{
ESS_USHORT_T usCount;
ESS_PPARTOTL_NAMEMAP_API_T pNameMap;
} ESS_PARTOTL_NAMECHG_API_T, *ESS_PPARTOTL_NAMECHG_API_T, **ESS_PPPARTOTL_NAMECHG_API_T;
ESS_USHORT_T usCount The number of changes.
“ESS_PARTOTL_NAMEMAP_API_T” on page 161 pNameMap Array of name maps.
ESS_PARTOTL_NAMED_GENLEV_API_T
Specifies a name for a level or generation.
typedef struct ESS_PARTOTL_NAMED_GENLEV_API_T
{
ESS_USHORT_T usOperator;
ESS_SHORT_T sGenLev;
ESS_STR_T pszName;
struct ess_partotl_named_genlev_api_t *pNext;
} ESS_PARTOTL_NAMED_GENLEV_API_T, *ESS_PPARTOTL_NAMED_GENLEV_API_T,
**ESS_PPPARTOTL_NAMED_GENLEV_API_T;
ESS_USHORT_T usOperator One of the Name Operation Type constants listed below.
ESS_SHORT_T sGenLev Generation or Level number.
ESS_STR_T pszName Generation or Level name.
ESS_PARTOTL_NAMED_GENLEV_API_T pNext Pointer to the next structure.
Name Operation Type Constants

#define ESS_NAME_ADD 0x01
#define ESS_NAME_DELETE 0x02
#define ESS_NAME_UPDATE 0x04
ESS_PARTOTL_NAMEMAP_API_T
Charts name changes.
typedef struct ESS_PARTOTL_NAMEMAP_API_T
{
ESS_USHORT_T usOperator;
ESS_CHAR_T *name;
ESS_CHAR_T *name2;
struct ess_partotl_namemap_api_t *pNext;
} ESS_PARTOTL_NAMEMAP_API_T, *ESS_PPARTOTL_NAMEMAP_API_T,
**ESS_PPPARTOTL_NAMEMAP_API_T;
161
ESS_USHORT_T usOperator One of the Name Operation Type constants listed below.
ESS_CHAR_T name Name of uda, for alias changes, the alias table name.
ESS_CHAR_T name2 Not used for uda changes, for alias changes, use the alias name.
ESS__PARTOTL_NAMEMAP_API_T pNext Pointer to the next structure.
Name Operation Type Constants

#define ESB_NAME_ADD 0x01
#define ESB_NAME_DELETE 0x02
#define ESB_NAME_UPDATE 0x04
ESS_PARTOTL_OSN_RELATIVES_API_T
Contains the names of the member, its parent, and its siblings.
typedef struct ESS_PARTOTL_OSN_RELATIVES_API_T
{
ESS_UCHAR_T statuses[ESS_PARTOTL_OSN_NUM_RELATIVES];
ESS_PCHAR_T names[ESS_PARTOTL_OSN_NUM_RELATIVES];
ESS_ATTRIBUTEVALUE_T values[ESS_PARTOTL_OSN_NUM_RELATIVES];
} ESS_PARTOTL_OSN_RELATIVES_API_T;
ESS_UCHAR_T statuses An array containing the status of each relative
ESS_PCHAR_T names An array containing the name of each relative
“ESS_ATTRIBUTEVALUE_T” on page 113 values An array containing the attribute value structure for each relative
Constants for ESS_PARTOTL_OSN_RELATIVES_API_T
typedef enum ESS_PARTOTL_OSN_REL_TYPE_API_T (Indices for the statuses,

names and values arrays)
{
ESS_PARTOTL_OSN_MEMBER
ESS_PARTOTL_OSN_PARENT
ESS_PARTOTL_OSN_LSIBLING
ESS_PARTOTL_OSN_RSIBLING
ESS_PARTOTL_OSN_REGION_PARENT
ESS_PARTOTL_OSN_LEVEL_REGION_LSIBLING
ESS_PARTOTL_OSN_LEVEL_REGION_RSIBLING
ESS_PARTOTL_OSN_GENER_REGION_LSIBLING
ESS_PARTOTL_OSN_GENER_REGION_RSIBLING
ESS_PARTOTL_OSN_RESERVED1
ESS_PARTOTL_OSN_RESERVED2
ESS_PARTOTL_OSN_NUM_RELATIVES
}
#define ESS_PARTOTL_OSN_REGION_LSIBLING ESS_PARTOTL_OSN_GENER_REGION_LSIBLING
162
#define ESS_PARTOTL_OSN_REGION_RSIBLING ESS_PARTOTL_OSN_GENER_REGION_RSIBLING
typedef enum ESS_PARTOTL_OSN_REL_TYPE_API_T (Values for statuses)

{
ESS_PARTOTL_OSN_REL_NONE
ESS_PARTOTL_OSN_REL_SAME_AS_ADJACENT /* The name of the region sibling is the
same as the name of the sibling. */
ESS_PARTOTL_OSN_REL_SHARED
ESS_PARTOTL_OSN_REL_REAL
}
ESS_PARTOTL_QUERY_T
Queries metadata changes.
typedef struct ESS_PARTOTL_QUERY_T
{
ESS_USHORT_T usOperationType;
ESS_USHORT_T, usDataDirectionType;
ESS_PARTOTL_QRY_FILTER_T MetaFilter;
} ESS_PARTOTL_QUERY_T, *ESS_PPARTOTL_QUERY_T, **ESS_PPPARTOTL_QUERY_T;
“ESS_PART_CONNECT_INFO_T” on page 147 HostDatabase The host database.
ESS_USHORT_T usOperationType One of the Operation Type constants listed below.
ESS_USHORT_T usDataDirectionType One of the Direction Type constants listed below.
“ESS_PARTOTL_QRY_FILTER_T” on page 163 MetaFilter Criteria to further define names.

Direction Type Constants

ESS_PARTOTL_QRY_FILTER_T
Further defines the metadata retrieval criteria.
typedef struct ESS_PARTOTL_QRY_FILTER_T
{
163
ESS_ULONG_T ulDimFilter;
ESS_ULONG_T ulMbrFilter;
ESS_ULONG_T ulMbrAttrFilter;
} ESS_PARTOTL_QRY_FILTER_T, *ESS_PPARTOTL_QRY_FILTER_T, **ESS_PPPARTOTL_QRY_FILTER_T;
ESS_TIME_T TimeStamp Query meta change happens after this time.
ESS_ULONG_T ulDimFilter Bitfield to select dimension changes.
ESS_ULONG_T ulMbrFilter Bitfield to select member changes.
ESS_ULONG_T ulMbrAttrFilter Bitfield to select member attribute changes.
Member Attribute Change Constants

#define ESS_PARTITION_OTLMBRATTR_STATUS 0x0001 /* status changes */
#define ESS_PARTITION_OTLMBRATTR_ALIAS 0x0002 /* alias changes */
#define ESS_PARTITION_OTLMBRATTR_UCALC 0x0004 /* unary calc symbol changes */
#define ESS_PARTITION_OTLMBRATTR_ATYPE 0x0008 /* account type changes */
#define ESS_PARTITION_OTLMBRATTR_CCONVERT 0x0010 /* currency conversion flag */
#define ESS_PARTITION_OTLMBRATTR_CRMBRNAME 0x0020 /* tagged currency db member */
#define ESS_PARTITION_OTLMBRATTR_UDA 0x0040 /* user defined attribute
changes */
#define ESS_PARTITION_OTLMBRATTR_CALC 0x0080 /* calc formula changes */
#define ESS_PARTITION_OTLMBRATTR_LEVEL 0x0100 /* level number changes */
#define ESS_PARTITION_OTLMBRATTR_GENERATION 0x0200 /* generation number changes */
#define ESS_PARTITION_OTLMBRATTR_ALL (ESS_PARTITION_OTLMBRATTR_STATUS |
ESS_PARTITION_OTLMBRATTR_ALIAS |
ESS_PARTITION_OTLMBRATTR_UCALC |
ESS_PARTITION_OTLMBRATTR_ATYPE |
ESS_PARTITION_OTLMBRATTR_CCONVERT |
ESS_MBRATTR_CRMBR_NAME |
ESS_PARTITION_OTLMBRATTR_UDA |
ESS_PARTITION_OTLMBRATTR_CALC |
ESS_PARTITION_OTLMBRATTR_LEVEL |
ESS_PARTITION_OTLMBRATTR_GENERATION)
#define ESS_ALLCHG (ESS_PARTITION_OTLMBR_ALL | ESS_DIMCHG_ALL)
ESS_PARTOTL_READ_T
Reads metadata changes.
typedef struct ESS_PARTOTL_READ_T
{
ESS_PPARTOTL_CHANGE_API_T pOtlChg;
ESS_TIME_T SourceTime;
} ESS_PARTOTL_READ_T, *ESS_PPARTOTL_READ_T, **ESS_PPPARTOTL_READ_T;
“ESS_PARTOTL_CHANGE_API_T” on page 154 pOtlChg Meta change records.
ESS_TIME_T SourceTime Time when source outline is changed.
164
ESS_PARTOTL_SELECT_APPLY_T
Applies metadata changes.
typedef struct ESS_PARTOTL_SELECT_APPLY_T
{
ESS_STR_T pszFileName;
ESS_PPARTOTL_CHANGE_API_T pOtlChg;
ESS_TIME_T SourceTime;
} ESS_PARTOTL_SELECT_APPLY_T, *ESS_PPARTOTL_SELECT_APPLY_T,
**ESS_PPPARTOTL_SELECT_APPLY_T;
ESS_STR_T pszFileName Outline change file name.
“ESS_PARTOTL_CHANGE_API_T” on page 154 pOtlChg Outline change records (from

EssPartitionReadOtlChangeFile).
ESS_TIME_T SourceTime Timestamp from outline change source.
ESS_PARTOTL_SELECT_CHG_T
Queries metadata.
typedef struct ESS_PARTOTL_SELECT_CHG_T
{
ESS_PARTOTL_QRY_FILTER_T QueryFilter;
} ESS_PARTOTL_SELECT_CHG_T, *ESS_PPARTOTL_SELECT_CHG_T, **ESS_PPPARTOTL_SELECT_CHG_T;
ESS_STR_T pszFileName Meta change file name.
“ESS_PARTOTL_QRY_FILTER_T” on page 163 QueryFilter Only reads records which satisfy the criteria.
ESS_PARTSLCT_T
Queries shared partitions for a given site.
typedef struct ESS_PARTSLCT_T
{
ESS_USHORT_T usOperationTypes;
ESS_USHORT_T usDirectionTypes;
ESS_USHORT_T usMetaDirectionTypes;
} ESS_PARTSLCT_T, *ESS_PPARTSLCT_T, **ESS_PPPARTSLCT_T;
ESS_USHORT_T usOperationTypes One of the Operation Type constants listed below.
ESS_USHORT_T usDirectionTypes One of the Direction constants listed below.
165
Direction Constants
#define ESS_PARTITION_DATA_BOTH (ESS_PARTITION_DATA_SOURCE |
ESS_PARTSLCT_VALIDATE_T
Specifies a partition to verify.
typedef struct ESS_PARTSLCT_VALIDATE_T
{
ESS_USHORT_T usLoc;
ESS_PART_DEFINED_T Part;
} ESS_PARTSLCT_VALIDATE_T, *ESS_PPARTSLCT_VALIDATE_T, **ESS_PPPARTSLCT_VALIDATE_T;
ESS_USHORT_T usLoc Either ESS_FILE_CLIENT or ESS_FILE_SERVER
ESS_STR_T pszFileName Partition definition file name.
“ESS_PART_DEFINED_T” on page 147 Partition Partition to verify.
ESS_PERF_ALLOC_ARG_T
This structure contains information about where errors occur for allocations or custom
calculations.
typedef_enum ESS_PERF_ALLOC_ARG_T
{
ESS_PERF_ALLOC_ARG_NA,0,
ESS_PERF_ALLOC_ARG_POV,1,
ESS_PERF_ALLOC_ARG_AMOUNT,2,
ESS_PERF_ALLOC_ARG_AMOUNTCONTEXT,3,
ESS_PERF_ALLOC_ARG_AMOUNTTIMESPAN,4,
ESS_PERF_ALLOC_ARG_TARGET,5,
ESS_PERF_ALLOC_ARG_TARGETTIMESPAN,6,
ESS_PERF_ALLOC_ARG_TARGETTIMESPANOPTION,7,
ESS_PERF_ALLOC_ARG_OFFSET,8,
ESS_PERF_ALLOC_ARG_DEBITMEMBER,9,
ESS_PERF_ALLOC_ARG_CREDITMEMBER,10,
ESS_PERF_ALLOC_ARG_RANGE,11,
ESS_PERF_ALLOC_ARG_EXCLUDEDRANGE,12,
166
ESS_PERF_ALLOC_ARG_BASIS,13,
ESS_PERF_ALLOC_ARG_BASISTIMESPAN,14,
ESS_PERF_ALLOC_ARG_BASISTIMESPANOPTION,15,
ESS_PERF_ALLOC_ARG_ALLOCATIONMETHOD,16,
ESS_PERF_ALLOC_ARG_SPREADSKIPOPTION,17,
ESS_PERF_ALLOC_ARG_ZEROAMOUNTOPTION,18,
ESS_PERF_ALLOC_ARG_ZEROBASISOPTION,19,
ESS_PERF_ALLOC_ARG_NEGATIVEBASISOPTION,20,
ESS_PERF_ALLOC_ARG_ROUNDMETHOD,21,
ESS_PERF_ALLOC_ARG_ROUNDDIGITS,22,
ESS_PERF_ALLOC_ARG_ROUNDTOLOCATION,23,
ESS_PERF_ALLOC_ARG_SCRIPT,24,
ESS_PERF_ALLOC_ARG_SOURCEREGION,25,
ESS_PERF_ALLOC_ARG_GROUPID,26,
ESS_PERF_ALLOC_ARG_RULEID,27
} ESS_PERF_ALLOC_ARG_T;
ESS_PERF_ALLOC_ERROR_T
This structure returns information about warnings and errors returned by the allocations
functions. This information is used by the calling function to determine which argument has an
error and on which line number and token it occurs. Only some warnings or errors will generate
an error structure. The messageNumber indicates which structure goes with which message. If
more than one message has the same number, then the corresponding error structures (if any)
will be in the same order in which the messages were given.
typedef struct ESS_PERF_ALLOC_ERROR_T
{
struct ESS_PERF_ALLOC_ERROR_T *nextError;
ESS_ULONG_T messageNumber;
ESS_PERF_ALLOC_ARG_T argument;
ESS_ULONG_T lineNumber;
ESS_CHAR_T token[8192];
} ESS_PERF_ALLOC_ERROR_T;
ESS_PERF_ALLOC_ERROR_T nextError Pointer to the next error structure, if any
ESS_ULONG_T messageNumber The number of the corresponding error or warning message
ESS_PERF_ALLOC_ARG_T argument Indicates which parameter contains the error
ESS_ULONG_T lineNumber Indicates which line of the argument contains the error. If zero, this is not applicable.
ESS_CHAR_T token Indicates which part of the argument contains a parsing error; empty if not applicable
ESS_PERF_ALLOC_T
This structure stores information to be used for performing allocations.
typedef struct ESS_PERF_ALLOC_T
{
ESS_STR_T pov;
167
ESS_STR_T amount;
ESS_STR_T amountContext;
ESS_STR_T amountTimeSpan;
ESS_STR_T target;
ESS_STR_T targetTimeSpan;
ESS_ALLOCATION_TARGETTIMESPAN_OPTION targetTimeSpanOption;
ESS_STR_T offset;
ESS_STR_T debitMember;
ESS_STR_T creditMember;
ESS_STR_T range;
ESS_STR_T excludedRange;
ESS_STR_T basis;
ESS_STR_T basisTimeSpan;
ESS_ALLOCATION_BASISTIMESPAN_OPTION basisTimeSpanOption;
ESS_ALLOCATION_METHOD_OPTION allocationMethod;
ESS_ULONG_T spreadSkipOption;
ESS_ALLOCATION_ZEROAMT_OPTION zeroAmountOption;
ESS_ALLOCATION_ZEROBASIS_OPTION zeroBasisOption;
ESS_ALLOCATION_NEGBASIS_OPTION negativeBasisOption;
ESS_ALLOCATION_ROUND_OPTION roundMethod;
ESS_STR_T roundDigits;
ESS_STR_T roundToLocation;
ESS_ULONG64_T groupID;
ESS_ULONG64_T ruleID;
} ESS_PERF_ALLOC_T;
ESS_STR_T pov MDX set expression specifying allocation area within the database
ESS_STR_T amount MDX tuple or numeric value expression specifying amount or amounts to be allocated
ESS_STR_T amountContext Optional: MDX tuple expression:

l If amount is a numeric value expression, specifies context for amount
l If amount is a tuple or constant, this argument is empty
ESS_STR_T amountTimeSpan Optional: MDX set expression of level 0 members specifying time periods from which
amount is summed before allocation
ESS_STR_T target MDX tuple expression specifying target locations for allocation
ESS_STR_T targetTimeSpan Optional: MDX set expression specifying time periods for target; used with
targetTimeSpanOption
ESS_ALLOCATION_ targetTimeSpanOption Optional: Specifies how values are allocated to targetTimeSpan members:
TARGETTIMESPAN_
ESS_ASO_ALLOCATION_TIMESPAN_DIVIDEAMT (divide)
OPTION_T
l
l ESS_ASO_ALLOCATION_TIMESPAN_REPEATAMT (repeat)
l Ignored if empty
ESS_STR_T offset Optional: MDX tuple expression specifying location for offsetting entries
ESS_STR_T debitMember Optional: MDX member expression specifying where positive result values should be
written. If empty, debit/credit processing is not performed.
168
ESS_STR_T creditMember Optional: MDX member expression specifying where negative result values should be
written. If empty, debit/credit processing is not performed.
ESS_STR_T range MDX set expression specifying database region for allocation
ESS_STR_T excludedRange Optional: MDX set expression specifying a subset of range; a region included in the
allocation but not written to
ESS_STR_T basis MDX tuple expression specifying the basis location. If allocationMethod = ESS_ASO_
ALLOCATION_METHOD_SPREAD and spreadSkipOptions = 0, then basis must be
empty.
ESS_STR_T basisTimeSpan Optional: MDX set expression specifying time periods to be considered with basis. With
basisTimeSpanOption, determines basis for allocation.
ESS_ALLOCATION_ basisTimeSpanOption Optional: Specifies how basis is computed across time periods from the following
BASISTIMESPAN_ options:
OPTION_T
l ESS_ASO_ALLOCATION_TIMESPAN_SPLITBASIS—Process basis value for
each time period individually
l ESS_ASO_ALLOCATION_TIMESPAN_COMBINEBASIS—Sum basis value across
time periods in basisTimeSpan and use the combined basis for allocation
ESS_ALLOCATION_ allocationMethod Allocation method:

METHOD_OPTION_T
l ESS_ASO_ALLOCATION_METHOD_SHARE—allocate proportional to basis values
l ESS_ASO_ALLOCATION_METHOD_SPREAD—allocate evenly across the target
region
ESS_ULONG_T spreadSkipOption Optional:

l If allocationMethod = ESS_ASO_ALLOCATION_METHOD_SHARE, then this value
equals 0.
l If allocationMethod = ESS_ASO_ALLOCATION_METHOD_SPREAD, specifies which
basis values should be skipped. Select one or more of the following bitwise
arguments:
m ESS_ASO_ALLOCATION_SPREAD_SKIPMISSING—Excludes all cells in
allocationRange for which the basis member is #missing
m ESS_ASO_ALLOCATION_SPREAD_SKIPZERO—Excludes all cells in
allocationRange for which the basisMbr is zero
m ESS_ASO_ALLOCATION_SPREAD_SKIPNEGATIVE—Excludes all cells in
allocationRange for which the basisMbr is negative
These arguments can be combined bitwise; for example ESS_ASO_ALLOCATION_

SPREAD_SKIPZERO | ESS_ASO_ALLOCATION_SPREAD_SKIPNEGATIVE
ESS_ALLOCATION_ zeroAmountOption Specifies what to do when an amount value is zero or #MISSING:

ZEROAMT_OPTION_T
l ESS_ASO_ALLOCATION_ZEROAMT_DEFAULT—Allocate zero values
l ESS_ASO_ALLOCATION_ZEROAMT_NEXTAMT—Skip to the next amount value
l ESS_ASO_ALLOCATION_ZEROAMT_ABORT—Cancel the entire allocation
169
ESS_ALLOCATION_ zeroBasisOption l If allocationMethod=ESS_ASO_ALLOCATION_METHOD_SHARE—Tells Essbase

ZEROBASIS_ what to do when the aggregate sum of basis is zero
OPTION_T
l If allocationMethod=ESS_ASO_ALLOCATION_METHOD_SPREAD—Tells Essbase
what to do when all basis values have been skipped
Specify an option:
l ESS_ASO_ALLOCATION_ZEROBASIS_NEXTAMT—Skip to the next amount value
l ESS_ASO_ALLOCATION_ZEROBASIS_ABORT—Cancel the allocation
ESS_ALLOCATION_ negativeBasisOption Tells Essbase what to do when a negative basis value is encountered:
NEGBASIS_OPTION_
ESS_ASO_ALLOCATION_NEGBASIS_DEFAULT—Calculate as normal
T
l
l ESS_ASO_ALLOCATION_NEGBASIS_NEXTAMT—Skip to next amount value. No

data is allocated for the current amount value.
l ESS_ASO_ALLOCATION_NEGBASIS_ABORT—Cancel the allocation; no data is
written.
The following values are only valid when allocationMethod==ESS_ASO_ALLOCATION_

METHOD_SHARE
l ESS_ASO_ALLOCATION_NEGBASIS_ABS—Use the absolute value

l ESS_ASO_ALLOCATION_NEGBASIS_MISSING—Treat the basis as #missing
l ESS_ASO_ALLOCATION_NEGBASIS_ZERO—Treat the basis value as zero
ESS_ALLOCATION_ roundMethod Rounding method for allocated values:

ROUND_OPTION_T
l ESS_ASO_ALLOCATION_ROUND_NONE—Perform no rounding
l ESS_ASO_ALLOCATION_ROUND_DISCARDERRORS—Round, discarding rounding
errors
l ESS_ASO_ALLOCATION_ROUND_ERRORSTOHIGHEST—Round, adding rounding
errors to the target cell with the greatest allocated value
l ESS_ASO_ALLOCATION_ROUND_ERRORSTOLOWEST—Round, adding rounding
errors to the target cell with the lowest allocated value
l ESS_ASO_ALLOCATION_ROUND_ERRORSTOLOCATION—Round, adding
rounding errors to roundToLocation
ESS_STR_T roundDigits Must be empty if roundMethod=ESS_ASO_ALLOCATION_ROUND_NONE. Must be

specified as a MDX numeric value or tuple expression. Value must be a whole number
between 100 and -100.
ESS_STR_T roundToLocation Optional: If roundMethod=ESS_ASO_ALLOCATION_ROUND_ERRORSTOLOCATION,

this is an MDX tuple expression specifying a location within range; empty otherwise
ESS_ULONG64_T groupID Internal use only. Always enter 0.
ESS_ULONG64_T ruleID Internal use only. Always enter 0.
170
ESS_PERF_CUSTCALC_T
This structure stores information to be used for performing custom calculations with aggregate
storage databases.
For complete information about writing and executing custom calculation scripts, see
“Performing Custom Calculations and Allocations on Aggregate Storage Databases” in the
Oracle Essbase Database Administrator's Guide.
typedef struct ESS_PERF_CUSTCALC_T

{
ESS_STR_T pov;
ESS_STR_T script;
ESS_STR_T target;
ESS_STR_T debitMember;
ESS_STR_T creditMember;
ESS_STR_T offset;
ESS_STR_T sourceRegion;
ESS_ULONG64_T groupID;
ESS_ULONG64_T ruleID;
} ESS_PERF_CUSTCALC_T;
ESS_STR_T pov MDX set expression specifying script execution area within the database
ESS_STR_T script Contents of the custom calculation script. Should include multiple assignments of the form
Target := Formula; where Target is an MDX tuple expression and Formula is an MDX numeric
value expression. The script can contain only MDX tuple expressions and arithmetic operators (+ ,
- , * , /). MDX functions are not supported.
ESS_STR_T target Optional: MDX tuple expression specifying location, in combination with pov and the left-hand side
of the assignment statements in script, to which calculation results will be written. If dimensions
overlap , the order for resolving conflicts is assignment statements first, then target, then pov.
ESS_STR_T debitMember Optional: MDX member expression specifying the debit member. Positive results are stored here. If
empty, debit/credit processing is not performed.
ESS_STR_T creditMember Optional: MDX member expression specifying the credit member. Negative results will be stored
here. If empty, debit/credit processing is not performed.
ESS_STR_T offset Optional: MDX tuple expression specifying the location for offset entries, if any, to be written
ESS_STR_T sourceRegion MDX set expression indicating the database region referred to by the right-hand sides of the formulas
in the script
ESS_ULONG64_T groupID Internal use only. Always enter 0.
ESS_ULONG64_T ruleID Internal use only. Always enter 0.
171
ESS_PROCSTATE_T
When you perform asynchronous operations (for example, a calculation), this structure is
returned from calls to EssGetProcessState(). This lets the caller determine the status of the
asynchronous operation.
Note: In this release of the C API, the State field is the only field implemented; all other fields
are reserved for future use.
typedef struct ESS_PROCSTATE_T

{
ESS_USHORT_T Action;
ESS_USHORT_T State;
ESS_USHORT_T Reserved1;
ESS_ULONG_T Reserved2;
ESS_ULONG_T Reserved3;
} ESS_PROCSTATE_T, *ESS_PPROCSTATE_T;
ESS_USHORT_T Action Current process action (not used)
ESS_USHORT_T Stat Current process state (either done or in progress). Values:

l ESS_STATE_DONE (0)
l ESS_STATE_INPROGRESS (1)
l ESS_STATE_FINALSTAGE (5)
ESS_USHORT_T Reserved1 Reserved for future use
ESS_ULONG_T Reserved2 Reserved for future use
ESS_ULONG_T Reserved3 Reserved for future use
ESS_RATEINFO_T
This currency partition rate information structure is used by EssGetCurrencyRateInfo(). The
fields in this structure cannot be modified by the API.
typedef struct ESS_RATEINFO_T
{
ESS_MBRNAME_T RateMbr [ESS_CRDB_MAXDIMNUM];
} ESS_RATEINFO_T, *ESS_PRATEINFO_T, **ESS_PPRATEINFO_T;
ESS_MBRNAME_T MbrName Member name
ESS_MBRNAME_T RateMbr[ESS_CRDB_MAXDIMNUM] Array of rate member names
172
ESS_REQUESTINFO_T
Contains information that can be used to display information about, or terminate, sessions and
requests. A session is the time between login and logout for a user connected to Essbase Server.
A request is a query sent to Essbase by a user or by another process; for example, starting an
application, or restructuring a database outline. Each session can process only one request at a
time; therefore, sessions and requests have a one-to-one relationship.
typedef struct ESS_REQUESTINFO_T
{
ESS_LOGINID_T LoginId; user login identification tag
ESS_USERNAME_T UserName; user name
ESS_SVRNAME_T LoginSourceMachine; Login machine name
ESS_APPNAME_T AppName; connected application
ESS_DBNAME_T DbName; connected database
ESS_USHORT_T DbRequestCode; Request code
ESS_DESC_T RequestString; Request string
ESS_TIME_T TimeStarted; time started (in seconds)
ESS_REQ_STATE_T State; current process state
} ESS_REQUESTINFO_T, *ESS_PREQUESTINFO_T, **ESS_PPREQUESTINFO_T;
ESS_LOGINID_T LoginId A unique number assigned to the user when the user logs in.
ESS_USERNAME_T UserName The name of the requesting user.
ESS_SVRNAME_T LoginSourceMachine Server name from which the session or request is being made
ESS_APPNAME_T AppName The active application (if any) for the session or request
ESS_DBNAME_T DbName The active database (if any) for the session or request
ESS_USHORT_T DbRequestCode A positive integer representing an active session. Example: 774896669
ESS_DESC_T RequestString A string representing the type of request. For possible values, see Request
Types below.
ESS_TIME_T TimeStarted how long the session or request has been in progress (in seconds)
“ESS_REQ_STATE_T” on page 179 State The state of the current session or request: whether it is processing,
terminating, or terminated.
Request Types
l Process xref request
l xref test
l Restructure
l GetCurrencyDb
l SetCurrencyType
l Export
l SQLImport
173
l SQLRetrieve
l Report
l SQLConnect
l SQLDatabases
l Calculate
l SetDefaultCalcScript
l ListCalcFunc
l VerifyFormula
l LoadAlias
l ListAliases
l DumpAlias
l BuildDimFile
l GetMbrInfo
l TestDriver
l GetSmStats
l OtlQueryMbrs
l OtlQueryAttrib
l CheckAttribute
l List location aliases
l ClearData
l SetCurrencyDb
l GetCurrencyType
l ParExport
l Import
l CancelUpdate
l SpreadsheetOperation
l SQLListDsn
l SQLTables
l ParseCalcScript
l GetDefaultCalcScript
l VerifyJavaSpec
l ListUdfs
l RemoveAlias
l SetAlias
l BuildDimStart
174
l GetDSInfo
l GetMbrCalc
l GetDimInfo
l PerfCommand
l OtlQueryMbrs
l OtlGetUpdateTime
l PutReplicatedCells
l Create location alias
l Validate
l GetStats
l SetCurrencyType
l GetCurrencyRate
l DataLoad
l StreamDataload
l ClearUserLocks
l SpreadsheetCellOperation
l SQLColumns
l SQLGetDsn
l RunDefaultCalcScript
l CalcStats
l UpdateCdfCdm
l UdfInfo
l ClearAliases
l GetAlias
l BuildDimension
l GetSelectedMbrInfo
l CheckMbrName
l GetAttributeNameSpecs
l GetOtlInfo
l OtlQueryUDAs
l GetAttrInfo
l GetReplicatedCells
l Delete location alias
175
ESS_REQUESTINFOEX_T
Contains information that can be used to display information about, or terminate, sessions and
requests. A session is the time between login and logout for a user connected to Essbase Server.
time; therefore, sessions and requests have a one-to-one relationship. This structure is similar
to ESS_REQUESTINFO_T, with the addition of the ProviderName and connparam fields.
typedef struct ESS_REQUESTINFOEX_T

{
ESS_SVRNAME_T LoginSourceMachine;
ESS_USHORT_T DbRequestCode;
ESS_DESC_T RequestString;
ESS_TIME_T TimeStarted;
ESS_REQ_STATE_T State;
} ESS_REQUESTINFOEX_T, *ESS_PREQUESTINFOEX_T, **ESS_PPREQUESTINFOEX_T;
ESS_LOGINID_T LoginId A unique number assigned to the user when the user logs in
ESS_USERNAME_T UserName Name of the requesting user
ESS_CONNPARAM_T connparam Unique identity attribute identifying a user or group in a directory. Example:
native://nvid=f0ed2a6d7fb07688:5a342200:
1265973105c:-7f46?USER
ESS_SVRNAME_T LoginSourceMachine Server name from which the session or request is being made
ESS_APPNAME_T AppName Active application (if any) for the session or request
ESS_DBNAME_T DbName Active database (if any) for the session or request
ESS_USHORT_T DbRequestCode A positive integer representing an active session. Example: 774896669
ESS_DESC_T RequestString A string representing the type of request. For possible values, see
“ESS_REQUESTINFOEX_T” on page 176.
ESS_TIME_T TimeStarted How long the session or request has been in progress (in seconds)
ESS_REQ_STATE_T State; State of the current session or request: whether it is processing, terminating, or terminated.
Request Types
l Process xref request
176
l xref test
l Restructure
l GetCurrencyDb
l SetCurrencyType
l Export
l SQLImport
l SQLRetrieve
l Report
l SQLConnect
l SQLDatabases
l Calculate
l SetDefaultCalcScript
l ListCalcFunc
l VerifyFormula
l LoadAlias
l ListAliases
l DumpAlias
l BuildDimFile
l GetMbrInfo
l TestDriver
l GetSmStats
l OtlQueryMbrs
l OtlQueryAttrib
l CheckAttribute
l List location aliases
l ClearData
l SetCurrencyDb
l GetCurrencyType
l ParExport
l Import
l CancelUpdate
l SpreadsheetOperation
l SQLListDsn
l SQLTables
l ParseCalcScript
177
l GetDefaultCalcScript
l VerifyJavaSpec
l ListUdfs
l RemoveAlias
l SetAlias
l BuildDimStart
l GetDSInfo
l GetMbrCalc
l GetDimInfo
l PerfCommand
l OtlQueryMbrs
l OtlGetUpdateTime
l PutReplicatedCells
l Create location alias
l Validate
l GetStats
l SetCurrencyType
l GetCurrencyRate
l DataLoad
l StreamDataload
l ClearUserLocks
l SpreadsheetCellOperation
l SQLColumns
l SQLGetDsn
l RunDefaultCalcScript
l CalcStats
l UpdateCdfCdm
l UdfInfo
l ClearAliases
l GetAlias
l BuildDimension
l GetSelectedMbrInfo
l CheckMbrName
l GetAttributeNameSpecs
l GetOtlInfo
178
l OtlQueryUDAs
l GetAttrInfo
l GetReplicatedCells
l Delete location alias
ESS_REQ_STATE_T
Used by ESS_REQUESTINFO_T. This structure returns information about the state of the
current session or request. Fields in this structure cannot be modified using the API.
typedef ESS_USHORT_T ESS_REQ_STATE_T;
#define ESS_REQ_IN_PROGRESS 0
#define ESS_REQ_TERMINATING 1
#define ESS_REQ_TERMINATED 2
ESS_USHORT_T ESS_REQ_IN_PROGRESS (0) The current session or request is processing.
ESS_USHORT_T ESS_REQ_TERMINATING (1) The current session or request is terminating.
ESS_USHORT_T ESS_REQ_TERMINATED (2) The current session or request is terminated.
ESS_RUNTIMESUBVARS_DESC_T
Used by EssGetRuntimeSubVars API. This structure is the data type for the RtSVList argument,
which is a list (array) of runtime substitution variable structures in the calculation script. Each
structure contains a runtime substitution variable key/value pair. Optionally, each structure can
specify a string in the <RTSV_HINT>rtsv_description</RTSV_HINT> tag that describes the
runtime substitution variable data type and data input limit (for example, an integer not greater
than 100).
typedef_struct (ESS_RUNTIMESUBVARS_DESC_T)
{
(ESS_STR_T, rtsvName);
(ESS_STR_T, rtsvVal);
(ESS_STR_T, rtsvDesc);
} (ESS_RUNTIMESUBVARS_DESC_T);
ESS_STR_T rtsvName Name of the runtime substitution variable
ESS_STR_T rtsvVal Value of the runtime substitution variable
ESS_STR_T rtsvDesc Description of the runtime substitution variable data type and data input limit (for example, an integer not
greater than 100)
See Also
EssGetRuntimeSubVars
179
ESS_SECURITY_MODE_T
Used by EssGetEssbaseSecurityMode. This data type returns information about the security
mode of Essbase Server.
typedef ESS_USHORT_T, ESS_SECURITY_MODE_T;
#define ESS_NATIVE_SECURITY 1
#define ESS_SS_SECURITY 2
Note: Essbase native security mode is no longer supported.
ESS_SEQID_T
Contains an array of sequence ids.
typedef_struct ESS_SEQID_T
{
ESS_ULONG_T, seq_id_start;
ESS_ULONG_T, seq_id_upper_start;
ESS_ULONG_T, seq_id_end;
ESS_ULONG_T, seq_id_upper_end;
} ESS_SEQID_T;
ESS_ULONG_T seq_id_start Start of range
ESS_ULONG_T seq_id_upper_start Upper start of range
ESS_ULONG_T seq_id_end End of range
ESS_ULONG_T seq_id_upper_end Upper end of range
ESS_TIMERECORD_T
typedef struct ESS_TIMERECORD_T
{
ESS_TIME_T TimeValue;
ESS_USHORT_T Seconds;
ESS_USHORT_T Minutes;
ESS_USHORT_T Hours;
ESS_USHORT_T Day;
ESS_USHORT_T Month;
ESS_USHORT_T Year;
ESS_USHORT_T Weekday;
} ESS_TIMERECORD_T, *ESS_PTIMERECORD_T;
Used in the “ESS_DBREQINFO_T” on page 120 structure. The times expressed in this structure
are usually server times. The fields are:
180
ESS_TIME_T TimeValue Time value in seconds after 1/1/70
ESS_USHORT_T Seconds Seconds after the minute. Values: 0-59.
ESS_USHORT_T Minutes Minutes after the hour. Values: 0-59.
ESS_USHORT_T Hours Hours since midnight. Values: 0-23.
ESS_USHORT_T Day Day of the month. Values: 1-31.
ESS_USHORT_T Month Months since January. Values: 0-11. January = 0.
ESS_USHORT_T Year Years since 1900.
ESS_USHORT_T Weekday Days since Sunday. Values: 0-6. Sunday = 0.
ESS_TRANSACTION_ENTRY_T
Contains
typedef_struct ess_transaction_entry_t
{
ESS_ULONG_T, seq_id;
ESS_ULONG_T, seq_id_upper;
ESS_TIME_T, time_start;
ESS_TIME_T, time_end;
ESS_USERNAME_T username;
ESS_UCHAR_T, type;
ESS_UCHAR_T, state;
ESS_CHAR_T, reserved1;
ESS_TRANSACTION_REQSPECIFIC_T, reqSpecDat;
} ESS_TRANSACTION_ENTRY_T
ESS_ULONG_T seq_id Sequence ID
ESS_ULONG_T seq_id_upper Sequence ID upper for future
ESS_TIME_T time_start Operation start time
ESS_TIME_T time_end Operation end time
ESS_USERNAME_T username Executing user
ESS_UCHAR_T type Record type
ESS_UCHAR_T state Do not use this field and client
ESS_CHAR_T reserved1 For future expansion
ESS_TRANSACTION_REQSPECIFIC_T reqSpecDat Request specific data
181
ESS_TRANSACTION_REPLAY_INP_T
Contains information on transaction replays.
typedef_struct ESS_TRANSACTION_REPLAY_INP_T
{
ESS_UCHAR_T, InpType;
ESS_UCHAR_T, reserved1;
union
{
ESS_TIME32_T, InpTime, value;
ESS_ULONG_T, num_seq_id_range, value;
}value;
}ESS_TRANSACTION_REPLAY_INP_T);
ESS_UCHAR_T InpType is it time based or sequence id
ESS_UCHAR_T reserved1 reserved
ESS_TIME32_T InpTime A union variable for the following values:

ESS_ULONG_T num_seq_id_range l Time to start replay
l Number of sequence ID-based input structures to follow
ESS_TRANSACTION_REQSPECIFIC_T
Contains information .
typedef_struct ess_transaction_reqspecific_t
{
ESS_UCHAR_T, ucReqType;
union
{
ESS_FILENAME_T, calcname, value;
ESS_LOG_DATALOAD_T, dataload_info, value;
ESS_LOG_DIMBLD_T, dimbld_info, value);
ESS_FILENAME_T, tmpotlfilename, value);
} value;
} ESS_TRANSACTION_REQSPECIFIC_T;
ESS_UCHAR_T ucReqType Request type
182
ESS_UCHAR_T reserved1 Reserved
ESS_FILENAME_T calcname A union variable for the following values:

ESS_LOG_DATALOAD_T dataload_info l Calc file name
ESS_LOG_DIMBLD_T dimbld_info l Data load details
ESS_FILENAME_T tmpotlfilename l Build load details

l Temporary outline file name
ESS_USERAPP_T, ESS_GROUPAPP_T
Contains access privilege information for a user or group and a specific application. The
Access field is the only field in this structure that can be modified using the API. The fields are:
typedef struct ESS_USERAPP_T
{
} ESS_USERAPP_T, *ESS_PUSERAPP_T, **ESS_PPUSERAPP_T,
ESS_GROUPAPP_T, *ESS_PGROUPAPP_T, **ESS_PPGROUPAPP_T;
ESS_USERNAME_T UserName The user or group name
ESS_ACCESS_T Access The assigned access privilege to the application for the user or group. This field can take any
combination of the following bit values:
l ESS_PRIV_NONE
l ESS_PRIV_APPLOAD
l ESS_PRIV_APPDESIGN
ESS_ACCESS_T MaxAccess The maximum access privilege to the application for the user or group from all sources
ESS_USERAPPEX_T, ESS_GROUPAPPEX_T
Contains access privilege information for a user or group and a specific application. This
structure is similar to ESS_USERAPP_T, ESS_GROUPAPP_T, with the addition of the
ProviderName, Type, and connparam fields.
typedef struct ESS_USERAPPEX_T
{
183
ESS_USHORT_T Type;
} ESS_USERAPPEX_T, *ESS_PUSERAPPEX_T, **ESS_PPUSERAPPEX_T,
ESS_GROUPAPPEX_T, *ESS_PGROUPAPPEX_T, **ESS_PPGROUPAPPEX_T;
ESS_CONNPARAM_ connparam Unique identity attribute identifying user or group in a directory. Example:
T
USER
ESS_USHORT_T Type Type of the structure. This field can contain the following values:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
ESS_ACCESS_T Access The assigned access privilege to the application for the user or group. This field can take any
combination of the following bit values:
l ESS_PRIV_NONE
l ESS_PRIV_APPLOAD
l ESS_PRIV_APPDESIGN
ESS_ACCESS_T MaxAccess The maximum access privilege to the application for the user or group from all sources
ESS_USERDB_T, ESS_GROUPDB_T
Contains access privilege information for a user or group and a specific database. The Access and
Filter fields are the only fields in this structure that can be modified using the API. The fields
are:
typedef struct ESS_USERDB_T
{
ESS_FTRNAME_T FilterName;
} ESS_USERDB_T, *ESS_PUSERDB_T, **ESS_PPUSERDB_T,
ESS_GROUPDB_T, *ESS_PGROUPDB_T, **ESS_PPGROUPDB_T;
184
ESS_USERNAME_T UserName The user or group name.
ESS_APPNAME_T AppName The application name.
ESS_DBNAME_T DbName The database name.
ESS_ACCESS_T Access The assigned access privilege to the database for the user or group. Access privileges are set through
the Administrative Services interface.
This field can take any combination of the following bit values:
l ESS_PRIV_NONE
l ESS_PRIV_READ
l ESS_PRIV_WRITE
l ESS_PRIV_CALC
l ESS_PRIV_DBLOAD
l ESS_PRIV_DBDESIGN
These values are a subset of the “Bitmask Data Types (C)” on page 90.
ESS_ACCESS_T MaxAccess The maximum access privilege to the database for the user or group from all sources. Access privileges
are set through the Administrative Services interface.
ESS_FTRNAME_T FilterName The name of the assigned database filter, if any. If none, the first byte is NULL.
ESS_USERDBEX_T, ESS_GROUPDBEX_T
Contains access privilege information for a user or group and a specific database. This structure
is similar to ESS_USERDB_T, ESS_GROUPDB_T, with the addition of the ProviderName,
connparam and Type fields.
typedef struct ESS_USERDBEX_T
{
ESS_USHORT_T Type;
ESS_FTRNAME_T FilterName;
} ESS_USERDBEX_T, *ESS_PUSERDBEX_T, **ESS_PPUSERDBEX_T,
ESS_GROUPDBEX_T, *ESS_PGROUPDBEX_T, **ESS_PPGROUPDBEX_T;
185
ESS_ connparam Unique identity attribute identifying user or group in a directory. Example:
CONNPARAM_T
USER
ESS_USHORT_T Type Type of the structure. This field can contain the following value:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
ESS_DBNAME_T DbName The database name
ESS_ACCESS_T Access The assigned access privilege to the database for the user or group. Access privileges are set
through the Administrative Services interface.
This field can take any combination of the following bit values:
l ESS_PRIV_NONE
l ESS_PRIV_READ
l ESS_PRIV_WRITE
l ESS_PRIV_CALC
l ESS_PRIV_DBLOAD
l ESS_PRIV_DBDESIGN
These values are a subset of the “Bitmask Data Types (C)” on page 90.
ESS_ACCESS_T MaxAccess The maximum access privilege to the database for the user or group from all sources.
ESS_FTRNAME_T FilterName The name of the assigned database filter, if any. If none, the first byte is NULL.
ESS_USERINFO_T, ESS_GROUPINFO_T
Stores information about a user or group. Some of the fields are specific to users and cannot be
used for groups. The Access, Expiration, and PwdChgNow fields are the only fields in this structure
that can be modified using the API. The fields are:
Note: Refer also to the locale-specific extended User Info structure, “ESS_USERINFOEX_T”
on page 189.
typedef struct ESS_USERINFO_T

{
/* The items below are 4.X and above */
ESS_BOOL_T Login;
ESS_USHORT_T Type;
186
/* The items below are 5.X and above */

} ESS_USERINFO_T, *ESS_PUSERINFO_T, **ESS_PPUSERINFO_T,

ESS_GROUPINFO_T, *ESS_PGROUPINFO_T, **ESS_PPGROUPINFO_T;
ESS_USERNAME_T Name User or group name
ESS_DBNAME_T DbName Name of the currently connected database(if applicable)
ESS_BOOL_T Login Flag to indicate login status (users only)
ESS_USHORT_T Type Type of the structure (user or group). This field can contain the following values:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
ESS_ACCESS_T Access User or group assigned default access privileges. Values: any combination of the following bit
values:
ESS_ACCESS_T MaxAccess User's maximum access privileges (users only, including individual access and access levels due
to group membership.
ESS_TIME_T LastLogin Date of user's last successful login stated as Greenwich Mean Time (users only).
ESS_USHORT_T FailCount Count of the failed login attempts since the last successful login (users only).
ESS_LOGINID_T LoginId The user login identification tag (users only) .
ESS_DESC_T Description User/group description.
ESS_EMAIL_T EMailID User/group email address.
187
ESS_USERINFOID_T, ESS_GROUPINFOID_T
Stores information about a user or group. This structure is similar to ESS_USERINFOEX_T, with
the addition of the ProviderName and connparam fields.
typedef struct ESS_USERINFOID_T
{
ESS_PASSWORD_T Password;
ESS_BOOL_T Login;
ESS_USHORT_T Type;
} ESS_USERINFOID_T, *ESS_PUSERINFOID_T, **ESS_PPUSERINFOID_T,

ESS_GROUPINFOID_T, *ESS_PGROUPINFOID_T, **ESS_PPGROUPINFOID_T;
ESS_USERNAME_T Name User name
ESS_PASSWORD_T Password Password of externally authenticated user. This is used only when setting an externally
authenticated user to the Essbase authenticated mechanisms. This password is ignored in other
situations, including retrieving information from the server on the externally authenticated user.
ESS_APPNAME_T AppName Name of the currently connected application (if applicable)
ESS_DBNAME_T DbName Name of the currently connected database (if applicable)
ESS_BOOL_T Login Flag to indicate login status
ESS_USHORT_T Type Type of the structure. This field can contain the value:
ESS_TYPE_USER
ESS_ACCESS_T Access User assigned default access privileges. Values can be any combination of the following bit
values:
188
ESS_ACCESS_T MaxAccess User's maximum access privileges (including individual access and access levels due to group
membership)
ESS_DATE_T Expiration User's password expiration date
ESS_TIME_T LastLogin Date of user's last successful login stated as Greenwich Mean Time
ESS_USHORT_T FailCount Count of the failed login attempts since the last successful login
ESS_LOGINID_T LoginId User login identification tag
ESS_DESC_T Description User description
ESS_EMAIL_T EMailID User email address
ESS_BOOL_T LockedOut Flag indicating that the user is locked out
ESS_BOOL_T PwdChgNow Flag indicating that the user must change the password
ESS_PROTOCOL_T protocol External authentication protocol.
ESS_CONNPARAM_T connparam Unique identity attribute identifying a user or group in a directory. Example:
USER
ESS_USERINFOEX_T
Stores information about a user or group. Some of the fields are specific to users and cannot be
used for groups. The Access, Expiration, and PwdChgNow fields are the only fields in this structure
that can be modified using the API.
This extended User Info structure is slightly different from the standardESS_USERINFO_T
structure used by EssGetUser (see “ESS_USERINFO_T, ESS_GROUPINFO_T” on page 186).
This extended structure is used by EssGetUserEx.
The fields are:
typedef struct ESS_USERINFOEX_T
{
ESS_PASSWORD_T Password;
ESS_BOOL_T Login;
ESS_USHORT_T Type;
189
} ESS_USERINFOEX_T, *ESS_PUSERINFOEX_T, **ESS_PPUSERINFOEX_T;
ESS_USERNAME_T Name Externally authenticed User name.
ESS_PASSWORD_T Password Password of externally authenticated user. This is used only when setting an externally
authenticated user to the Essbase authenticated mechanisms. This password is ignored in other
situations, including retrieving information from the server on the externally authenticated user.
ESS_DBNAME_T DbName Name of the currently connected database(if applicable)
ESS_BOOL_T Login Flag to indicate login status (users only)
ESS_USHORT_T Type Type of the structure (user or group). This field can contain the following values:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
ESS_ACCESS_T Access User or group assigned default access privileges. Values: any combination of the following bit
values:
l ESS_ACCESS_SUPER /* Administrator, all bits set */
ESS_ACCESS_T MaxAccess User's maximum access privileges (users only, including individual access and access levels
due to group membership.
ESS_TIME_T LastLogin Date of user's last successful login stated as Greenwich Mean Time (users only).
ESS_USHORT_T FailCount Count of the failed login attempts since the last successful login (users only).
ESS_LOGINID_T LoginId The user login identification tag (users only) .
ESS_DESC_T Description User/group description.
ESS_EMAIL_T EMailID User/group email address.
ESS_PROTOCOL_T protocol External authentication protocol.
190
ESS_CONNPARAM_T connparam External authentication connection.
ESS_VARIABLE_T
ESS_VARIABLE_T is the primary substitution variable datatype. It identifies the substitution
variable's value and name, as well as the Essbase database, application, and server where the
variable is defined.
The Server name is optional, but recommended. If not included, the current server is the default.
The AppName is optional. The DbName is optional, but if it exists, then the AppName member
is required. The VarName is required. The VarValue is required.
typedef struct ESS_VARIABLE_T
{
ESS_MBRNAME_T VarName;
ESS_CHAR_T VarValue[ESS_VARVALUELEN];
} ESS_VARIABLE_T, *ESS_PVARIABLE_T, **ESS_PPVARIABLE_T;
ESS_SVRNAME_T Server Name of server where variable is defined (optional)
ESS_APPNAME_T AppName Name of application to restrict variable to
ESS_DBNAME_T DbName Name of database to restrict variable to. If used, it requires that application be set.
ESS_MBRNAME_T VarName Name of substitution variable.
ESS_CHAR_T VarValue[256] Value of substitution variable.
191
192
C Main API Functions
8
In This Chapter
C Main API Function Categories ........................................................................ 194
C Main API Function Reference......................................................................... 210
193
C Main API Function Categories
Subtopics
l C Main API Alias Table Functions
l C Main API Application Functions
l C Main API Attributes Functions
l C Main API Database Functions
l C Main API Database Member Functions
l C Main API Drill-through Functions
l C Main API File Functions
l C Main API Group Administration Functions
l C Main API Initialization and Login Functions
l C Main API LRO Functions
l C Main API Location Aliases Functions
l C Main API Memory Allocation Functions
l C Main API Miscellaneous Functions
l C Main API Object Functions
l C Main API Partition Functions
l C Main API Performance Stats Functions
l C Main API Reporting, Updating, and Calculation Functions
l C Main API Runtime Substitution Variables
l C Main API Security Filter Functions
l C Main API Substitution Variables Functions
l C Main API User Administration Functions
l C Main API User and Group Identity Functions
l C Main API Shared Services Functions
l C Main API Unicode Mode Functions
C Main API Alias Table Functions

Alias table functions manage database alias tables.
Function Description
EssListAliases Lists all the alias tables in the active database.
EssLoadAlias Loads an alias table for the active database from a structured text file
EssGetAlias Gets the active alias table name from the active database for a user.
EssSetAlias Sets the active alias table in the active database for a user.
EssDisplayAlias Dumps contents of alias table in active database.
EssRemoveAlias Removes an alias table from the active database.
EssClearAliases Clears all alias tables for the active database.
194
C Main API Application Functions
The application functions can create new applications, and modify, copy, get information about
and otherwise manage existing applications.
EssGetActive Gets the names of the caller's current active application and database.
EssSetActive Sets the callers active application and database.
EssClearActive Clears the user's current active application and database.
EssListApplications Lists all applications which are accessible to the caller.
EssConvertApplicationtoUnicode Converts a non Unicode mode application to a Unicode mode application.
EssCreateApplication Creates a new application, either on the client or the server.
EssCreateApplicationEx Creates a new application with the option of setting the application type:
Unicode- or non-Unicode mode.
EssCreateStorageTypedApplicationEx Creates a new application with options for setting the data storage mode (block
or aggregate) and application type (Unicode- or non-Unicode mode).
EssDeleteApplication Deletes an existing application, either on the client or the server.
EssRenameApplication Renames an existing application, either on the client or the server.
EssCopyApplication Copies an existing application, either on the client or the server, to a new
application, including all associated databases and objects.
EssGetApplicationInfoEx Gets information from one or more applications
EssGetApplicationState Gets an application state structure, which contains user-configurable

parameters for the application.
EssSetApplicationState Sets user-configurable parameters for the application using the application's
state structure.
EssGetApplicationInfo Gets an application's information structure, which contains non user-

configurable parameters for the application.
EssLoadApplication Starts an application on the server.
EssUnloadApplication Stops an application on the server.
C Main API Attributes Functions

These C Main functions are for attributes.
EssCheckAttributes Returns the attribute type for given attribute dimensions, base dimensions, attribute
members, and base members
195
EssFreeStructure Frees memory dynamically allocated for string type attribute information
EssGetAssociatedAttributesInfo Returns the attribute members associated with a given base member
EssGetAttributeInfo Returns attribute information for a given attribute member or dimension
EssGetAttributeSpecifications Retrieves attribute specifications for the outline
See C Outline API “C Outline API Attributes Functions” on page 724.
C Main API Database Functions

Database functions carry out database management tasks, and retrieve and modify database
information structures.
EssBeginDataload Starts sending an update specification to the active database.
EssBeginDataloadASO Starts a data load on an aggregate storage database.
EssClearDatabase Clears all loaded data in the active database.
EssCommitDatabase Forces all data blocks in the active database to be written to disk.
EssCopyDatabase Copies an existing database, either on the client or the server, to a new database, including
all associated databases and objects.
EssCreateDatabase Creates a new database within an application, on client or server.
EssDeleteDatabase Deletes an existing database from an application, on client or server.
EssEndDataload Marks the end of an update specification being sent to the active database.
EssGetCurrencyRateInfo Gets a list of structures containing rate information for all members of the tagged currency
partition dimension in the active database outline.
EssGetDatabaseInfo Gets a database's information structure, which contains non user-configurable parameters
for the database.
EssGetDatabaseInfoEx Gets information for one or more databases.
EssGetDatabaseNote Gets a database's note-of-the-day message.
EssGetDatabaseState Gets a database's state structure, which contains user-configurable parameters for the
database.
EssGetDatabaseStats Gets the active database's Stats structure, which contains statistical information about the
database.
EssListCurrencyDatabases Lists all currency databases within a specific application that are accessible to the caller.
196
EssListDatabases Lists all databases that are accessible to the caller, either within a specific application, or
on an entire server.
EssListExistingLoadBuffers Returns the list of structures that describe existing data load buffers for an aggregate storage
database.
EssLoadBufferInit Creates a temporary data load buffer.
EssLoadBufferTerm Destroys the temporary data-load memory buffer(s) allocated by oadBufferInit.
EssLoadDatabase Starts a database.
EssMergeDatabaseData Merges two or more data slices into a single data slice.
EssRenameDatabase Renames a database on client or server.
EssSetDatabaseNote Sets a database's note-of-the-day message.
EssSetDatabaseState Sets user-configurable parameters for the database using the database's state structure.
EssUnloadDatabase Stops a database within an application on the server.
EssValidateDB Checks the database for data integrity.
C Main API Database Member Functions

These functions obtain information about database members and build database dimensions.
EssQueryDatabaseMembers Performs a report-style query to list a selection of database member information.
EssCheckMemberName Checks if a string is a valid member name within the active database outline.
EssGetMemberInfo Gets a structure containing information about a specific member in the active database outline.
EssGetMemberCalc Gets the calc equation for a specific member in the active database outline.
EssGetDimensionInfo Gets dimension information.
EssBuildDimension Allows the creation of a dimension in the active database from a data file and rules file.
EssBuildDimFile This function builds a data file to be used in the addition or removal of members from the outline
in the active database.
EssBuildDimStart This function starts the process of the adding or removing members from the outline in the active
database.
EssBuildDimXml Performs light outline editing, using an XML file to make basic changes to the database outline.
197
C Main API Drill-through Functions
The following Drill-through functions manage drill-through URLs for drilling through to
information hosted on Oracle ERP and EPM applications.
l EssCreateDrillThruURL
l EssDeleteDrillThruURL
l EssGetCellDrillThruReports
l EssGetDrillThruURL
l EssListDrillThruURLs
l EssUpdateDrillThruURL
The following Drill-through functions retrieve data from connected relational databases.
See “Drill-Through Constant and Structure Definitions” on page 104.
Refer to these Drill-Through functions in the Grid API:
l EssGDTConnect
l EssGDTEndDrillThrough
l EssGDTExecuteReport
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
l EssGDTRequestDrillThrough
l EssGDTSetInfo
Note: In future releases, the C Main API Drill-Through functions below will be deprecated and
replaced by the corresponding Grid API functions. Programs should use the Grid API
functions listed above.
l EssDTInit
l EssDTOpen
l EssDTClose
l EssDTExit
l EssDTGetData
l EssDTGetHeader
l EssDTGetHeaderInfo
l EssDTListReports
l EssDTAPIClose
198
l EssDTAPIConnect
l EssDTAPIExecuteReport
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetColumns
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIGetReports
l EssDTAPIInit
l EssDTAPISetConnection
l EssDTAPISetInfo
C Main API File Functions

File functions enable an application to use predefined report scripts, data files and calculation
scripts against the active database. There are also functions for importing and exporting data to
and from both text and binary files.
EssArchiveBegin Prepares database for archive by setting READ-ONLY status.
EssArchiveEnd After archive, returns database status to READ-WRITE.
EssCalcFile Executes a calc script against the active database from a file.
EssExport Exports data from the current database to a text file.
EssImport Imports data from text files and other sources to the current database.
EssImportASO Imports data from different sources to an aggregate storage database.
EssListDbFiles Retrieves information on specified index and data files
EssReportFile Sends a report specification to the active database from a file.
EssSetDefaultCalcFile Sets the default calc script for the active database from a calc script file.
EssUpdateFile Sends an update specification to the active database from a file.
EssUpdateFileEx Sends an update specification to the active database from a file, capturing any data load errors.
EssUpdateFileASO Sends an update specification to the active aggregate storage database from a file.
EssUpdateFileASOEx Sends an update specification to the active aggregate storage database from a file, capturing any
data load errors.
EssUpdateFileUTF8ASO Sends an update specification to the active aggregate storage database from a UTF-8-encoded
file.
199
EssUpdateFileUTF8ASOEx Sends an update specification to the active aggregate storage database from a UTF-8-encoded
file, capturing any data load errors.
EssUpdateFileUtf8Ex Sends an update specification to the active database from a UTF-8-encoded file, capturing any
data load errors
EssDisplayTriggers Returns a list of all triggers associated with a database.
EssMdxTrig Manipulates triggers based on the operations contained in an MDX language file.
EssListSpoolFiles Returns a list of all the spool files associated with a database.
EssGetSpoolFile Returns a specific spool file associated with a database.
EssDeleteAllSplFiles Deletes all the spool files associated with a database.
EssDeleteSplFile Deletes a specific spool file.
C Main API Group Administration Functions

These functions create groups, set and modify group attributes, and obtain information about
existing groups.
EssListGroups Lists all groups who have access to a particular Essbase Server.
EssCreateGroup Creates a new group.
EssDeleteGroup Deletes an existing group.
EssRenameGroup Renames an existing group.
EssGetGroup Gets a group information structure, which contains security information for the group.
EssSetGroup Sets a group information structure.
EssGetGroupList Gets the list of users who are members of a group (or the list of groups to which a user belongs).
EssSetGroupList Sets list of users who are members of group.
EssAddToGroup Adds user to a list of group members.
EssDeleteFromGroup Removes a user from a list of group members
C Main API Initialization and Login Functions

These functions initialize the API, and log in and out of the Essbase Server. They also obtain
version information, and enable an application to create and delete local contexts.
200
EssAutoLogin Displays a dialog box which allows the user to log in to an Essbase Server, and optionally selects
an active application and database.
EssCreateLocalContext Creates a local API context for use in local API operations.
EssDeleteLocalContext Releases a local context previously created by EssCreateLocalContext.
EssGetAPIVersion Gets the full version number of the connected API client module.
EssGetVersion Gets the full version number of the connected Essbase Server.
EssInit Initializes the API and message database.
EssLogin Logs a user in to the Essbase Server.
EssLoginAs Logs in to the Essbase Server as another user.
EssLoginEx Logs in to the Essbase Server using an authentication token.
EssLoginExAs Logs in to the Essbase Server as another user, using an authentication token.
EssLoginSetPassword Logs in a user, and changes the password.
EssLogout Logs a user out from an Essbase Server.
EssLogoutUser Allows a Supervisor or Application Designer to disconnect another user from an Essbase Server.
EssLogSize Returns the size of the Essbase Server log file (essbase.log), or of the application log file
(appname.log).
EssShutdownServer Allows a Supervisor to remotely stop the Essbase Server.
EssTerm Terminates the API and releases all system resources used by the API.
EssValidateHCtx Validates a specific API context handle (hCtx).
EssWriteToLogFile Writes a message to the Essbase Server log file (essbase.log), or to the application log file
(appname.log).
C Main API LRO Functions

These functions create, retrieve and delete LROs and return information about them.
EssLROAddObject Links a reporting object to a data cell in an Essbase database.
EssLRODeleteCellObjects Deletes all objects linked to a given data cell in an Essbase database.
EssLRODeleteObject Deletes a specific object linked to a data cell in an Essbase database.
EssLROGetCatalog Retrieves a list of LRO catalog entries for a given data cell in an Essbase database.
201
EssLROGetCatalogBatch Retrieves a list of LRO catalog entries for multiple data cells in an Essbase database.
EssLROGetObject Retrieves an object linked to a data cell in an Essbase database.
EssLROListObjects Retrieves a list of all objects linked to cells in the active database for a given user name and/or
modification date.
EssLROPurgeObjects Deletes all objects linked to cells in the active database for a given user name and/or modification
date.
EssLROUpdateObject Stores an updated version of an LRO on the server.
C Main API Location Aliases Functions

These functions create, delete and list location aliases.
EssCreateLocationAlias Maps an alias name to the host name, application name, database name, user login name, and
user password
EssDeleteLocationAlias Deletes an existing location alias
EssGetLocationAliasList Returns all location aliases and the names to which the location aliases are mapped
C Main API Memory Allocation Functions

These functions manage memory for an application by allocating, reallocating and freeing blocks
of memory.
EssAlloc Allocates a block of memory, using the defined memory allocation scheme.
EssRealloc Reallocates a previously-allocated block of memory.
EssFree Frees a previously allocated block of memory, using the defined memory allocation scheme.
C Main API Miscellaneous Functions

These functions manage asynchronous processes, obtain state information, handle log files, and
retrieve messages.
EssGetProcessState Gets the current state of an asynchronous process, such as a calculate or data import.
202
EssCancelProcess Cancels an asynchronous process which has not yet completed.
EssGetLogFile Copies all or part of an application log file from the server to the client.
EssDeleteLogFile Deletes an application log file on the server.
EssGetGlobalState Gets the server global state structure which contains parameters for system administration.
EssSetGlobalState Sets the server global state structure which contains parameters for system administration.
EssSetPath Sets the ESSBASEPATH environment variable for the current process.
C Main API Object Functions

These functions create, delete, move and copy objects. They also retrieve and display object
information and control access to objects.
EssGetLocalPath Gets the full local file for an object file on the client.
EssListObjects Lists all objects of types specified.
EssGetObjectInfo Gets information about a specified object.
EssGetObject Copies an object from the server to a local file, and optionally locks it.
EssPutObject Copies an object from a local file to the server, and optionally unlocks it.
EssLockObject Locks an object on the server to prevent other users from updating it.
EssUnlockObject Unlocks a locked object on the server.
EssCreateObject Creates a new object.
EssDeleteObject Deletes an existing object.
EssRenameObject Renames an existing object.
EssCopyObject Copies an object.
C Main API Partition Functions

These functions manage partition operations on a database.
EssPartitionApplyOtlChangeFile Tells the server to apply metadata changes to files.
EssPartitionApplyOtlChangeFileEx Tells the server to apply metadata changes to files.
203
EssPartitionApplyOtlChangeRecs Tells the server to apply metadata changes to records.
EssPartitionCloseDefFile Closes the shared partition definition file.
EssPartitionFreeDefCtx Frees memory dynamically allocated under shared partition context structures.
EssPartitionFreeOtlChanges Frees up memory allocated by the ReadMetaChange routine.
EssPartitionGetAreaCellCount Returns the number of cells in the specified slice string.
EssPartitionGetList Returns a list of the partition partition definitions in which the currently selected
database participates.
EssPartitionGetOtlChanges Pulls meta data changes from a given source.
EssPartitionGetReplCells Replicates all data cells that are identified in the replication partition from the
source database to the selected target database.
EssPartitionNewDefFile Creates and opens a new shared partition, definition file based upon input
parameters supplied.
EssPartitionOpenDefFile Opens an existing shared partition definition file.
EssPartitionPurgeOtlChangeFile Purges meta changes made previous to the time specified with the TimeStamp
parameter.
EssPartitionPutReplCells Replicates all data cells that are identified in the replication partition from the
selected source database to the target database.
EssPartitionReadDefFile Replicates all data cells that are identified in the replication partition from the
selected source database to the target database.
EssPartitionReadOtlChangeFile Reads meta changes from a file into memory.
EssPartitionReplaceDefFile Tells the server that a new shared partition file has been sent, which replaces any
existing file for this database.
EssPartitionResetOtlChangeTime Takes two partitions, one source and one destination. It takes the "last meta
change" time from the source partition and assigns it as the "last meta change"
time of the destination partition.
EssPartitionValidateDefinition Performs full validation of the specified partition definition; that is, validates the
source and target parts of one partition definition. Useful during creation of a new
or modification of an existing partition definition.
EssPartitionValidateLocal Performs partial validation of all partition definitions on the specified server. Useful
to ascertain the validity of partition definitions after metadata changes; for
example, after database restructuring.
EssPartitionWriteDefFile Writes the current memory version of the shared partition definition file to disk.
C Main API Performance Stats Functions

These functions provide I/O performance statistics on threads, databases and applications.
204
EssDumpPerfStats Provides a pointer to the character array that contains performance statistics tables
EssGetStatBufSize Provides a pointer to the size of the buffer needed for the performance statistics tables
EssResetPerfStats Resets values in the performance statistics tables to zero
C Main API Reporting, Updating, and Calculation Functions

These functions carry out reporting (retrieving data), updating (loading data) and calculation
(aggregating data) tasks against the active database.
EssReport Sends a report specification to the active database as a single string.
EssBeginReport Starts sending a report specification to the active database.
EssEndReport Marks the end of a report specification being sent to the active database.
EssUpdate Sends an update to the active database as a single string.
EssUpdateFileASO Sends an update specification to the active aggregate storage database from a file.
EssUpdateFileUTF8ASO Sends an update specification to the active aggregate storage database from a UTF-8-encoded file.
EssBeginUpdate Starts sending an update specification to the active database.
EssEndUpdate Marks the end of an update specification being sent to the active database.
EssGetString Gets a string of data from the active database.
EssSendString Sends a string of data to the active database.
EssCalc Sends and optionally executes a calc script against the active database as a single string.
EssBeginCalc Starts sending a calc script and optionally executes it against the active database.
EssEndCalc Marks the end of a calc script being sent to the active database.
EssDefaultCalc Executes the default calculation for the active database.
EssGetDefaultCalc Gets the default calc script for the active database.
EssListCalcFunctions Lists all available calculator functions.
EssSetDefaultCalc Sets the default calc script for a database.
C Main API Runtime Substitution Variables

These functions pass runtime substitution variables referenced in calculation scripts and return
information about them.
205
EssCalcFileWithRuntimeSubVars Executes a calculation script against the active database with the specified runtime
substitution variables. Runtime substitution variables can be specified in a text file
(with a .rsv extension), which must be located on the client computer, or as a string
of key/value pairs.
EssCalcWithRuntimeSubVars Executes a calculation script with the specified runtime substitution variables, which
are specified as a string of key/value pairs.
EssGetRuntimeSubVars This function is implemented as an interface to a client in which a calculation script is

run. This function retrieves all of the information (name, value, and description) that
is specified in the runtime substitution variable declarations in the SET
RUNTIMESUBVARS calculation command for a specified calculation script.
C Main API Security Filter Functions

Security filter functions create filters, set filter contents, assign filters to user groups, display filter
lists for data bases, and obtain other data about security filters.
EssListFilters Lists all filters for a database.
EssGetFilter Starts getting the contents of a filter.
EssGetFilterRow Gets the next row of a filter.
EssCreateFilter Creates a filter. Starts setting the contents of the filter.
EssSetFilter Creates or replaces a filter. Starts setting the contents of the filter.
EssSetFilterRow Gets the next row of a filter.
EssGetFilterList Gets the list of users who are assigned a filter.
EssSetFilterList Sets the list of users who are assigned a filter.
EssDeleteFilter Deletes an existing filter.
EssRenameFilter Renames an existing filter.
EssCopyFilter Copies an existing filter.
EssVerifyFilter Verifies the syntax of a series of filter row strings against a specified database.
EssVerifyFilterRow Verifies the syntax of a single filter row string against a specified database.
C Main API Substitution Variables Functions

These functions create, retrieve and delete substitution variables and return information about
them.
206
EssCreateVariable This function creates a new substitution variable or modifies an existing substitution variable if the variable
name already exists with the identical server, application, and database values.
EssDeleteVariable This function deletes a substitution variable.
EssGetVariable This function retrieves the value of a substitution variable.
EssListVariables This function lists all substitution variables that conform to the input criteria.
C Main API User Administration Functions

User administration functions create users, assign their passwords, and their access to databases,
applications, and calc scripts. Functions are also provided to retrieve information about user
capabilities.
EssListUsers Lists all users who have access to a particular Essbase Server.
EssCreateUser Creates a new user.
EssDeleteUser Deletes an existing user.
EssRenameUser Renames an existing user.
EssGetUser Gets a user information structure, which contains security information for user.
EssSetUser Sets a user information structure that contains security information for user.
EssResetUser Resets the user's security structure to its initial state.
EssSetPassword Sets a user's password, erasing the existing password.
EssGetApplicationAccess Gets a list of user application access structures, which contain information about user access to
applications.
EssSetApplicationAccess Sets a list of user application access structures.
EssGetDatabaseAccess Gets a list of user database access structures.
EssSetDatabaseAccess Sets a list of user database access structures.
EssGetCalcList Gets the list of calc scripts objects accessible to the user.
EssSetCalcList Sets the list of calc script objects which are available to a user.
EssListConnections Lists all users who are connected to the current application and database.
EssListLogins Lists information about currently connected users.
EssListRequests Lists information about current Essbase user sessions or requests.
EssKillRequest Terminates all or specific Essbase user sessions or requests.
207
EssListLocks Lists all users who are connected to a specific application and database.
EssRemoveLocks Removes all data block locks held by a user on a database.
C Main API User and Group Identity Functions

User and group identity functions are enhanced to enable the specification of user directories
and unique identity attributes to identify users and groups that are hosted in a directory.
EssAddToGroupEx Adds a user to the specified group. Similar to EssAddToGroup, but can accept a user directory
specification or unique identity attribute.
EssCreateExtGroup Creates a group in the external user directory.
EssDeleteFromGroupEx Removes a user from a group. Similar to EssDeleteFromGroup, but can accept a user directory
EssDeleteGroupEx Deletes an existing group. Similar to EssDeleteGroup, but can accept a user directory
EssDeleteUserEx Deletes a user. Similar to EssDeleteUser, but can accept a user directory specification or
unique identity attribute.
EssGetApplicationAccessEx Gets a list of user or group application access structures, which contain information about
user or group access to applications. Similar to EssGetApplicationAccess, but can accept a
user directory specification or unique identity attribute.
EssGetDatabaseAccessEx Gets a list of user database access structures, which contain information about user access
to databases. Similar to EssGetDatabaseAccess, but can accept a user directory specification
or unique identity attribute.
EssGetGroupInfoEx Gets a group information structure, which contains security information for the group. Similar
to EssGetGroup, but can accept a user directory specification or unique identity attribute.
EssGetGroupListEx Gets the list of users who are members of a group or the list of groups to which the user
belongs. Similar to EssGetGroupList, but can accept a user directory specification or unique
identity attribute.
EssGetUserInfoEx Gets a user information structure, which contains security information for the user. Similar to
EssGetUser, but can accept a user directory specification or unique identity attribute.
EssKillRequestEx Terminates specific user sessions or requests. Similar to EssKillRequest, but the input structure
can include user directories and unique identity attributes.
EssListConnectionsEx Lists all users who are connected to the currently logged in server or application. Similar to
EssListConnections, but includes users hosted in a user directory.
EssListGroupsInfoEx Lists all groups who have access to a particular Essbase Server, application or database.
Similar to EssListGroups, but the group list structure can include user directories and unique
identity attributes.
208
EssListLocksEx Lists all users who are connected to a specific application and database, together with a
count of data blocks which they currently have locked. Similar to EssListLocks, but includes
users hosted in a user directory.
EssListLoginsEx Returns the list of log in instances in the current session. Similar to EssListLogins, but includes
users hosted in a user directory.
EssListRequestsEx Returns information about active sessions and requests. Similar to EssListRequests, but
includes users hosted in a user directory.
EssListUsersInfoEx Lists all users who have access to a particular Essbase Server, application or database. Similar
to EssListUsers, but the user list structure can include user directories and unique identity
attributes.
EssSetApplicationAccessEx Sets a list of user application access structures, which contain information about user access
to applications. Similar to EssSetApplicationAccess, but the input structure can include user
directories and unique identity attributes.
EssSetCalcListEx Sets the calculation list accessible to the specified user or group. Similar to EssSetCalcList,
but includes users and groups hosted in a user directory.
EssSetDatabaseAccessEx Sets a list of user database access structures, which contain information about user access
to databases. Similar to EssSetDatabaseAccess, but the input structure can include user
EssSetFilterListEx Sets the list of groups or users that are assigned to a filter. The count parameter controls the
number of groups or users assigned to the filter. A count of zero removes all the groups or
users from the list.
EssSetGroupListEx Sets the list of users who are members of a group. Similar to EssSetGroupList, but can accept
a user directory specification or unique identity attribute.
C Main API Shared Services Functions

Shared Services User Management enables centralized management of user access rights and
accessibility to applications created under various projects of different products.
The following functions help you migrate Essbase to Shared Services mode. After migration, you
can manage users, groups, and applications in Shared Services mode instead of in Essbase native
mode.
EssSetSSSecurityMode Migrates Essbase Server and any existing users and groups to Oracle Enterprise Performance
Management System security mode.
EssSetUserToSS Migrates a user to EPM System security mode.
EssSetGroupToSS Migrates a group to EPM System security mode.
EssSetUsersToSS Migrates all users to EPM System security mode.
EssSetGroupToSS Migrates all groups to EPM System security mode.
209
EssGetEssbaseSecurityMode Displays the type of security in use.
EssListSSMigrFailedUsers Displays users that did not successfully migrate to Shared Services.
EssListSSMigrFailedGroups Displays groups that did not successfully migrate to Shared Services.
EssReRegisterApplication Re-establishes one or all Essbase applications as Shared Services applications.
EssSetEasLocation Set or change the Essbase Administration Server location that will be registered with Shared
Services upon application creation or migration.
C Main API Unicode Mode Functions

Essbase Server allows the creation of Unicode mode applications, or migration of non-Unicode
mode applications to Unicode mode, only when it is in Unicode mode.
The following functions help you work with the Essbase Server and applications in Unicode
mode.
EssSetServerMode Sets the mode of Essbase Server to be Unicode or non-

Unicode.
EssGetServerMode Indicates whether the Essbase Server is in Unicode

mode or non-Unicode mode.
EssCreateApplicationEx Creates a Unicode mode application.
EssConvertApplicationtoUnicode Converts a non Unicode mode application to a Unicode

mode application.
EssGetApplicationInfo and EssGetApplicationInfoEx Returns application information, including locale

information.
EssUpdateFileUTF8ASO Sends an update specification to the active aggregate

storage database from a UTF-8-encoded file.
EssUpdateFileUTF8ASOEx Sends an update specification to the active aggregate

storage database from a UTF-8-encoded file, capturing
any data load errors.
EssUpdateFileUtf8Ex Sends an update specification to the active database

from a UTF-8-encoded file, capturing any data load
errors
C Main API Function Reference

Consult the Contents pane for the alphabetical list of C Main API functions.
210
EssAddToGroup
Adds a user to the list of group members.
Syntax
ESS_FUNC_M EssAddToGroup (hCtx, GroupName, UserName);
Parameter Data Type Description
hCtx ESS_HCTX_T API context handle.
GroupName ESS_STR_T Group name.
UserName ESS_STR_T Name of user to add to group list.
Notes
This function also adds the user to the list of group members and the group to the user's own
list of groups.
Return Value
None.
Access
This function requires the caller to have Create/Delete User privilege
(ESS_PRIV_USERCREATE) for the logged in server.
Example
ESS_FUNC_M
ESS_AddUser (ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts = ESS_STS_NOERR;
ESS_STR_T GroupName;
ESS_STR_T UserName;
GroupName = "PowerUsers";
UserName = "Jim Smith";
sts = EssAddToGroup (hCtx, GroupName, UserName);
return (sts);
}
See Also
l EssAddToGroupEx
l EssDeleteFromGroup
l EssGetGroupList
l EssListGroups
l EssSetGroupList
211
EssAddToGroupEx
Adds a user to the specified group. Similar to EssAddToGroup, but can accept a user directory
specification or unique identity attribute for GroupId or UserId.
Syntax
ESS_FUNC_M EssAddToGroupEx (hCtx, GroupId, UserId, bUsingIdentity);
hCtx ESS_HCTX_T API context handle (input).
GroupId ESS_STR_T Group name or identity (input). Can be specified as groupname@provider or as

a unique identity attribute.
bIsGroupId ESS_BOOL_T Input. Indicates if GroupId is a name or an identity. If TRUE, GroupId is an identity.
UserId ESS_STR_T Name of user to add to group (input). Can be specified as username@provider
or as a unique identity attribute.
bUsingIdentity ESS_BOOL_T Input. Indicates if UserID is a name or an identity. If TRUE, UserID is an identity.
Notes
The API can accept an identity or a group name. The group name can be specified as
groupname@provider.
Return Value
None.
Access
Example
void DisplayUserList(ESS_USHORT_T count, ESS_PSTR_T UserList)

{
ESS_USHORT_T i;
for (i = 0; i < count; i++)

{
if (UserList [i])
printf ("%s\n", UserList[i]);
}
}
ESS_FUNC_M ESS_AddUser (ESS_HCTX_T hCtx)

{
ESS_STR_T groupId, userId;
ESS_BOOL_T bGroupId, bUserId;
ESS_BOOL_T bisIdentity;
212
ESS_USHORT_T type;
ESS_USHORT_T count;
ESS_BOOL_T bUsingIdentity;
ESS_PSTR_T pUserList;
groupId = "IDRegularGroup@ldap";
bGroupId = ESS_FALSE;
userId = "IDUser6";
bUserId = ESS_FALSE;
sts = EssAddToGroupEx(hCtx, groupId, bGroupId, userId, bUserId);
printf("EssAddToGroupEx sts: %ld\n", sts);
if(!sts)
{
sts = EssGetGroupListEx(hCtx, groupId, bisIdentity, type, &count, &bUsingIdentity,
&pUserList);
printf("EssGetGroupListEx sts: %ld\n", sts);
if(!sts)
{
if(pUserList)
{
printf ("\n---User/Group list for %s:\n", groupId);
DisplayUserList(count, pUserList);
}
else
printf ("\tUser list is empty\n");
}
}
return (sts);
}
See Also
l EssDeleteFromGroupEx
l EssGetGroupListEx
l EssListGroupsInfoEx
EssAlloc
Allocates a block of memory, using the defined memory allocation scheme.
Syntax
ESS_FUNC_M EssAlloc (hInstance, Size, ppBlock);
hInstance ESS_HINST_T API instance handle.
Size ESS_SIZE_T Size of memory block to allocate.
ppBlock ESS_PPVOID_T Address of pointer to receive allocated memory block.
213
Notes
l This function allocates memory using the user-supplied memory management function
passed to the EssInit function. If no such functions are supplied, the default memory
allocation function (dependent on the platform) will be used.
l Memory allocated using this function should always be reallocated or freed by using the
EssRealloc and EssFree functions respectively.
l It is generally not advisable to allocate a block of zero size, as the effects of such an allocation
are platform- and compiler-dependent.
Return Value
Returns a pointer to the allocated memory block in ppBlock.
Access
This function requires no special privileges.
Example
ESS_FUNC_M ESS_GetAppActive (ESS_HCTX_T hCtx,
ESS_HINST_T hInst)
{
ESS_STR_T pDbName;
ESS_STR_T pAppName;
if ((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pAppName)) == 0)

{
if ((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pDbName)) == 0)
{
if ((sts = EssGetActive (hCtx, &pAppName, &pDbName, &Access)) == 0)
{
if (pAppName)
{
if (*pAppName)
printf ("Current active application is [%s]\r\n",pAppName);
else
printf ("No active Application is set\r\n");
printf ("\r\n");
}
}
EssFree (hInst, pDbName);
}
EssFree (hInst, pAppName);
}
return (sts);
}
See Also
l EssFree
l EssInit
l EssRealloc
214
EssArchive
No longer in use.
This function is retained for compatibility with earlier versions of Essbase only. For current
Essbase archiving, see EssArchiveBeginand EssArchiveEnd. This function now returns the
error message ESS_STS_OBSOLETE.
See Also
l EssRestore
l EssArchiveBegin
l EssArchiveEnd
EssArchiveBegin
Prepares the server for archiving by changing server mode to Read-Only.
Syntax
ESS_FUNC_M EssArchiveBegin (hCtx, AppName, DbName, FileName);
hCtx ESS_HCTX_T API context handle
AppName ESS_STR_T Name of application to archive
DbName ESS_STR_T Name of database to archive
FileName ESS_STR_T Name of file to contain archive information
Notes
l This function changes server mode to Read-Only. This mode allows the database
administrator to back up all the files on the server and prevents writing to the files during
the backup. The database files to back up are listed in the app\db directory specified by the
FileName parameter.
l Any existing information in the specified file is overwritten by the archived data.
Return Value
None.
Access
The caller must have at least read access (ESS_PRIV_READ) to the database, and must select it
as the active database using EssSetActive.
Example
ESS_FUNC_M
ESS_ArchiveBegin(ESS_HCTX_T hCtx)
{
215
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
AppName = "Sample";
DbName = "Basic";
FileName = "Test.arc";
/* Begin Archive */
sts = EssArchiveBegin(hCtx, AppName, DbName,
FileName);
return (sts);
}
See Also
l EssArchiveEnd
l EssRestore
EssArchiveDatabase
Creates an archive of a database in a specified backup file.
Syntax
ESS_FUNC_M EssArchiveDatabase (hCtx, AppName, DbName, BackupFileName, OptionsFileName,
bOverWrite);
hCtx ESS_HCTX_T Login context
AppName ESS_STR_T Application Name
Note: Works only at the database level. The AppName parameter specifies an
Application in order to access the database residing within.
DbName ESS_STR_T Database Name
BackupFileName ESS_STR_T Full path to the backup file in which to archive data. Specify the full path; for
example:
c:\hyperion\Test.arc
OptionsFileName ESS_FILENAME_T Reserved for the future.
Note: For this release, use an empty string.
bOverWrite ESS_BOOL_T Boolean. Values:

l ESS_TRUE—Overwrite existing back up file.
l ESS_FALSE—Do not overwrite. Append to existing back up file.
Return Value
Returns:
216
l 0—If successful
l Error number—If unsuccessful
Access
The caller must have Essbase Administrator access to the database.
Example
void RestoreDB()
{
ESS_STR_T AppName = "Backup";
ESS_STR_T DbName = "Basic";
ESS_STR_T BackupFileName =
"F:\\testArea\\ArchiveAndRestore\\TempBackup.arc";
ESS_STR_T optionsFileName = "";
ESS_BOOL_T bOverWrite;
ESS_BOOL_T bForceDiffName;
ESS_USHORT_T count;
ESS_PDISKVOLUME_REPLACE_T replaceVol;
printf("\nArchive DB:\n");
bOverWrite = ESS_TRUE;
sts = EssArchiveDatabase(hCtx, AppName, DbName,
BackupFileName, optionsFileName,
bOverWrite);
printf("EssArchiveDatabase sts: %ld\r\n",sts);
sts = EssUnloadApplication(hCtx, AppName);

printf("\nEssUnloadApplication sts: %ld\r\n",sts);
printf("\nCase with no volume replacement:\n");

bForceDiffName = ESS_FALSE;
count = 0;
replaceVol = ESS_NULL;
sts = EssRestoreDatabase (hCtx, AppName, DbName,
BackupFileName, bForceDiffName,
count, replaceVol);
printf("EssRestoreDatabase sts: %ld\r\n",sts);
printf("\nCase with a replacement volume (index and page files to a different

volume):\n");
count = 1;
if (count)
{
sts = EssAlloc(hInst, count * sizeof(ESS_DISKVOLUME_REPLACE_T),
(ESS_PPVOID_T)&replaceVol);
memset(replaceVol, 0, count * sizeof(ESS_DISKVOLUME_REPLACE_T));
}
strcpy(replaceVol->szPartition_Src, "C");
strcpy(replaceVol->szPartition_Dest, "F");

217
count, replaceVol);
if (replaceVol)
EssFree(hInst, replaceVol);
}
See Also
l EssRestoreDatabase
EssArchiveEnd
Restores the server to "read-write" mode after archiving is complete.
Syntax
ESS_FUNC_M EssArchiveEnd (hCtx, AppName, DbName);
AppName ESS_STR_T Name of archived application.
DbName ESS_STR_T Name of archived database.
Notes
After calling EssArchiveBegin, a call to EssArchiveEnd is required to restore Read-Write
mode.
Return Value
None.
Access
The caller must have at least read access (ESS_PRIV_READ) to the database, and must select it
as the active database using EssSetActive.
Example
ESS_FUNC_M
ESS_ArchiveEnd(ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
/* End Archive */
sts = EssArchiveEnd(hCtx, AppName, DbName);
218
return (sts);
}
See Also
l EssArchiveBegin
l EssRestore
EssAsyncBuildDim
Issues an asynchronous dimension build request.
If you use asynchronous data loads and dimension builds, you can query for the following
information during the process:
l The state of dimension build/data load process: whether it is in progress, in the final stages,
or completed
l The stage of the dimension build/data load process: whether opening the data source,
reading the outline, building dimensions, verifying an outline, or writing an outline
l The number of data records processed and rejected so far
l The name and location of the error file
l The data records processed and rejected so far
Syntax
ESS_FUNC_M EssAsyncBuildDim(hCtx, RulesObj, DataObj, MbrUser, bOverwrite, usBuildOption,
szTmpOtlFile)
RulesObj ESS_POBJDEF_T Pointer to rules file object definition structure.
DataObj ESS_POBJDEF_T Pointer to data file object definition structure.
MbrUser ESS_PMBRUSER_T SQL user structure (if data source is SQL database).
A NULL SQL user structure indicates a non SQL data source.
bOverwrite ESS_BOOL_T Boolean. Values:

l ESS_TRUE—Overwrite existing error file.
l ESS_FALSE—Do not overwrite. Append to existing error file.
219
usBuildOption ESS_USHORT_T Valid values:

l ESS_INCDIMBUILD_BUILD
Build members only.
l ESS_INCDIMBUILD_VERIFY
Build members and verify the outline.
l ESS_INCDIMBUILD_SAVEOTL
Build members and save the outline to a temp outline file.
l ESS_INCDIMBUILD_ALL
Build members, verify the outline, and restructure.
l ESS_INCDIMBUILD_ABORT
Abort the build process.
szTmpOtlFile ESS_STR_T The temporary outline file name. No extension or path is needed. Essbase creates
a temporary outline file in the app/db directory, with an extension of .otb, if
the resulting outline in this round of dimension build has outline verification
errors.
Notes
This function returns an error if the data object is located on the client. The network connection
between client and server remains active even if an error is returned.
You must call EssCloseAsyncProc to close the connection; otherwise, the server request
handler blocks further requests from the same login session.
Return Value
Returns zero if successful; error code if unsuccessful.
Example
void ESS_AsyncBuildDim()
{
ESS_STS_T sts = 0;
ESS_OBJDEF_T Rules;
ESS_OBJDEF_T Data;
ESS_PMBRUSER_T pMbrUser;
ESS_BOOL_T bOverwrite;
ESS_USHORT_T usBuildOption;
ESS_STR_T szTmpOtlFile;
ESS_STR_T bldDimErrFile;
ESS_STR_T asyncProcErrLog;
ESS_BLDDL_STATE_T procState;
ESS_BOOL_T errFileOverWrite;
szAppName = "Sample";
szDbName = "Basic";
ESS_SetActive();
AddMember("800");
220
sts = EssBeginIncrementalBuildDim(hCtx);
printf("EssBeginIncrementalBuildDim sts: %ld\n",sts);
memset(&Rules,0,sizeof(ESS_OBJDEF_T));
memset(&Data,0,sizeof(ESS_OBJDEF_T));
Rules.hCtx = hCtx;
Rules.FileName = "apgeibl";
Rules.AppName = szAppName;
Rules.DbName = szDbName;
Rules.ObjType = ESS_OBJTYPE_RULES;
Data.hCtx = hCtx;
Data.AppName = szAppName;
Data.DbName = szDbName;
Data.ObjType = ESS_OBJTYPE_TEXT;
Data.FileName = "apgeibl1";
pMbrUser = ESS_NULL;
bOverwrite = ESS_TRUE;
usBuildOption = ESS_INCDIMBUILD_BUILD;
szTmpOtlFile = "asyncBldTmp";
sts = EssAsyncBuildDim(hCtx, &Rules, &Data, pMbrUser, bOverwrite, usBuildOption,
szTmpOtlFile);
printf("EssAsyncBuildDim sts: %ld\n",sts);
sts = EssGetAsyncProcLog (hCtx, ".\\AsyncProc.log", ESS_TRUE);

printf("EssGetAsyncProcLog sts: %ld\n",sts);
sts = EssGetAsyncProcState(hCtx, &procState);

printf("EssGetAsyncProcState sts: %ld\n",sts);
if(!sts)
{
do
{
DisplyProcesStateInfo(procState);
if(procState.ilProcessStatus)
{
sts = EssCancelAsyncProc(hCtx, asyncProcErrLog, errFileOverWrite);
printf("EssCancelAsyncProc sts: %ld\n",sts);
}
else
{
}
}while(procState.usProcessState != ESS_BLDDL_STATE_DONE);
if(!procState.ilProcessStatus)
{
sts = EssCloseAsyncProc(hCtx, &procState);
printf("EssCloseAsyncProc sts: %ld\n",sts);
}
}
bldDimErrFile = "F:\\testArea\\mainapi\\BldDim.err";
sts = EssEndIncrementalBuildDim(hCtx, ESS_DOR_ALLDATA, szTmpOtlFile, bldDimErrFile,
221
ESS_FALSE);
printf("EssEndIncrementalBuildDim sts: %ld\n",sts);
}
See Also
l EssAsyncImport
l EssGetAsyncProcLog
l EssGetAsyncProcState
l EssCancelAsyncProc
l EssCloseAsyncProc
EssAsyncImport
Issues an asynchronous data load request.
or completed
Syntax
ESS_FUNC_M EssAsyncImport (hCtx, pRules, pData, pMbrUser, abortOnError);
pRules ESS_POBJDEF_T Pointer to the rules file object definition structure.
pData ESS_POBJDEF_T Pointer to the data file object definition structure.
pMbrUser ESS_PMBRUSER_T Pointer to the SQL user structure (if data source is a SQL database). A NULL SQL
user structure indicates a non SQL data source.
abortOnError ESS_USHORT_T If TRUE, import stops on the first error. Otherwise, it continues.
Notes
222
Return Value
Returns zero if successful. Otherwise, returns an error code.
Access
This function requires the caller to have database designer privilege for the specified database
(ESS_PRIV_DBDESIGN).
Example
ESS_AsyncImport()
{
ESS_SHORT_T isAbortOnError;
ESS_OBJDEF_T Rules;
ESS_OBJDEF_T Data;
ESS_PMBRUSER_T pUser;
ESS_STR_T errorName;
szAppName = "Sample";
szDbName = "Basic";
ESS_SetActive();
memset(&Rules,0,sizeof(ESS_OBJDEF_T));
memset(&Data,0,sizeof(ESS_OBJDEF_T));
Rules.hCtx = hCtx;
Rules.FileName = "Act1";
Data.hCtx = hCtx;
Data.FileName = "Act1";
errorName = ".\\asyncProcess.err";
errFileOverWrite = ESS_TRUE;
isAbortOnError = ESS_TRUE;
pUser = ESS_NULL; /* NULL equals a non-SQL data source */
sts = EssAsyncImport (hCtx, &Rules, &Data, pUser, isAbortOnError);
printf("EssAsyncImport sts: %ld\n",sts);

if(!sts)
{
do
{
{
sts = EssCancelAsyncProc(hCtx, errorName, errFileOverWrite);
223
}
else
{
}
if(!procState.ilProcessStatus)
{
}
}
}
See Also
l EssAsyncBuildDim
l EssCloseAsyncProc
EssAsyncImportASO
Issues an asynchronous data load request on an aggregate storage database.
or completed
Syntax
ESS_FUNC_M EssAsyncImportASO (hCtx, pRules, pData, pUser, usAbortOnError, ulBufferId);
pRules ESS_POBJDEF_T Pointer to the rules file object definition structure.
pData ESS_POBJDEF_T Pointer to the data file object definition structure.
224
pUser ESS_PMBRUSER_T Pointer to the SQL user structure (if data source is a SQL database). A NULL
SQL user structure indicates a non SQL data source.
usAbortOnError ESS_USHORT_T If TRUE, import stops on the first error. Otherwise, it continues.
ulBufferID ESS_ULONG_T ID of a data load buffer (a number between 1 and 999,999). To destroy a buffer
before a data load is complete, you must use the same ulBufferId number that
was used to initialize the buffer.
Notes
Return Value
Access
Example
void ESS_AsyncImportASO()
{
ESS_OBJDEF_T Rules;
ESS_OBJDEF_T Data;
ESS_PMBRERR_T pMbrErr = NULL;
ESS_PMBRUSER_T pMbrUser = NULL;
ESS_ULONG_T ulOptionsFlags;
ESS_ULONG_T ulSize;
ESS_ULONG_T ulBufferCnt;
ESS_ULONG_T ulCommitType ;
ESS_ULONG_T ulActionType;
ESS_ULONG_T ulOptions;
ESS_ULONG_T ulBufferIdAry[1];
ESS_STR_T errorName;
szAppName = "ASOSamp";
szDbName = "Sample";
ESS_SetActive();
errorName = ".\\asyncProcess.err";
errFileOverWrite = ESS_TRUE;
225
ulDuplicateAggregationMethod = ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD;
ulOptionsFlags = ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES;
ulSize = 1;
ulBufferId = 100;
sts = EssLoadBufferInit(hCtx, szAppName, szDbName, ulBufferId,
ulDuplicateAggregationMethod,
ulOptionsFlags, ulSize);
printf("EssLoadBufferInit sts: %ld\n", sts);
if(!sts)
{
/* Server object */
Rules.hCtx = hCtx;
Rules.FileName = "Dataload";
Data.hCtx = hCtx;
Data.FileName = "Dataload";
sts = EssAsyncImportASO (hCtx, &Rules, &Data, pMbrUser, isAbortOnError,
ulBufferId);
printf("EssAsyncImportASO sts: %ld\n",sts);
if(!sts)
{
if(!sts)
{
do
{
{
sts = EssCancelAsyncProc(hCtx, errorName, errFileOverWrite);
}
else
{
}

ulBufferCnt = 1;
ulBufferIdAry[0] = ulBufferId;
ulCommitType = ESS_ASO_DATA_LOAD_BUFFER_STORE_DATA;
ulActionType = ESS_ASO_DATA_LOAD_BUFFER_COMMIT;
printf("\nIncrement to main slice:\n");
ulOptions = ESS_ASO_DATA_LOAD_INCR_TO_MAIN_SLICE;
226
sts = EssLoadBufferTerm(hCtx, szAppName, szDbName, ulBufferCnt,
ulBufferIdAry, ulCommitType, ulActionType, ulOptions);
printf("EssLoadBufferTerm sts: %ld\n",sts);
}
}
}
}
See Also
l EssAsyncBuildDim
l EssAsyncImport
l EssCloseAsyncProc
EssAutoLogin
Displays a dialog box that allows the user to log in to an Essbase Server, and optionally select an
active application and database.
Syntax
ESS_FUNC_M EssAutoLogin (hInstance, Server, UserName,
Password, AppName, DbName, Options, pAccess, phCtx);
hInstance ESS_HINST_T API instance handle
Server ESS_SVRNAME_T Network server name string

The server name can be expressed as a URL representing the APS servlet endpoint
with the Essbase failover cluster name; for example:
http://myhost:13080/aps/Essbase?clustername=Essbase-
Cluster1
For secure mode (SSL), the URL syntax is

http[s]://host:port/aps/Essbase?
ClusterName=logicalName&SecureMODE=yesORno
For example,
https://myhost:13080/aps/Essbase?clustername=Essbase-
Cluster1&SecureMODE=Yes
UserName ESS_USERNAME_T User name string
Password ESS_PASSWORD_T Password string
AppName ESS_ APPNAME _T Application name
DbName ESS_ DBNAME _T Database name
227
Options ESS_USHORT_T Options flag. Values:

l AUTO_NODIALOG—Attempts to log the user in without displaying the dialog,
using the default settings (from the above arguments).
l AUTO_NOSELECT—Allows the user to log in without selecting an application
and database (lower part of the dialog is not displayed).
You can use both AUTO_NODIALOG and AUTO_NOSELECT with an OR
operator (|) to log in a user without a dialog box and not select an application
and database.
l AUTO_NODIALOG|AUTO_NOSELECT: AUTO_DEFAULT—Enables the
user to log in and select an application and database interactively in the dialog
box.
pAccess ESS_PACCESS_T Address of variable to receive database access level.
phCtx ESS_PHCTX_T Address of variable to receive Essbase context handle. Set to ESS_INVALID_HCTX
unless you are reusing an existing (valid) context handle to log in again.
Notes
l The dialog box is automatically managed by the function, and provides features in the login
dialog to change the user password, display the database note message, etc., and so provides
a standardized and powerful login screen for all applications using the API.
l Use this function instead of the EssLogin function if you are programming in a Windows
environment.
l The function should be called after executing a successful call to EssInit, and prior to making
any other API calls which require a context handle argument.
l This function is supported only in Windows environments. It is not supported in UNIX
environments.
l The string arguments Server, UserName, Password, AppName or DbName may optionally
be NULL. If any of them are not NULL, the buffers they point to are updated when the
function returns the actual values selected by the user from the dialog box. If any of the
passed in arguments point to valid strings, they will be used as the default displayed values
in the dialog. The buffers for these arguments must be large enough to contain any possible
return value, not just the values passed in.
l If the login is successful, the server and user names are automatically stored (in the file
ESSBASE.INI) and are used as the defaults the next time this function is called (unless those
arguments are specified in subsequent calls). The names of all servers which have been
successfully connected to are also stored and displayed.
l The auto login dialog box is a child window of the current active window (the window that
has the focus). Therefore avoid destroying the active window or changing focus while the
auto login dialog is displayed.
l This function returns a value of ESS_STS_CANCEL if the user presses the Cancel button or
the Esc key in the dialog box.
228
l In Windows environments, if the end user clicks the Help button, the Essbase System Login
help topic is opened. You can redirect the Help button to point to a different help file by
specifying a different help file name in the ESS_INIT_T structure.
Return Value
If successful, returns an Essbase context handle in phCtx, which can be passed as an argument
in subsequent calls to other API functions. Also returns the user's access level to the selected
application and database (if selected) in pAccess.
Access
Before calling this function, you must first initialize the API and obtain a valid instance handle
by calling the EssInit function.
See Also
l EssInit
l EssListDatabases
l EssLogin
l EssLogout
l EssSetActive
EssBeginCalc
Starts sending a calc script and optionally executes it against the active database.
Syntax
ESS_FUNC_M EssBeginCalc (hCtx, Calculate);
Calculate ESS_BOOL_T Controls calculation of the calc script. If TRUE, the calc script is executed.
Notes
l This call must be followed by successive calls to EssSendString to send the calc script, and
finally by a call to EssEndCalc.
l The calc script must be less than 64 KB long in total.
l The calculation can either be initiated, or the calc script can just be verified and any errors
returned.
l If the calc script is successfully sent and the calculation is started, it will continue on the
server as an asynchronous process after the return from this call. After calling
EssEndCalc, the caller must check at regular intervals to see if the process has completed
by calling EssGetProcessState until it returns ESS_STATE_DONE.
l If the Calculate flag is set to FALSE, the database performs only a syntax check of the calc
script.
229
l Unicode clients using the C Main API to communicate with Unicode-enabled Essbase
applications must send the UTF-8 encoded Unicode byte order mark (BOM) in the text
stream immediately after calling this function. For an example, see “Specifying the Byte
Order Encoding” on page 69.
Return Value
None.
Access
This function requires the caller to have calc privilege (ESS_PRIV_CALC) to the active database.
Example
ESS_FUNC_M
ESS_Calc (ESS_HCTX_T hCtx)
{
ESS_STR_T Script;
ESS_PROCSTATE_T pState;
Script = "CALC ALL;";
sts = EssBeginCalc (hCtx,ESS_TRUE);

if (!sts)
sts = EssSendString (hCtx, Script);
if (!sts)
sts = EssEndCalc (hCtx);
if (!sts)
{
sts = EssGetProcessState (hCtx, &pState);
while(!sts && (pState.State !=
ESS_STATE_DONE))
}
return(sts);
}
See Also
l EssCalc
l EssCalcFile
l EssDefaultCalc
l EssEndCalc
l EssGetDefaultCalc
l EssGetProcessState
l EssSendString
l EssSetDefaultCalc
EssBeginDataload
Starts sending an update specification to the active database, and can unlock any data blocks
locked for update. The update data can either be stored in the database, or just verified and any
errors returned.
230
Syntax
ESS_STS_T EssBeginDataload (hCtx, Store, Unlock, abortOnError, pRules);
hCtx; ESS_HCTX_T API context handle.
Store; ESS_BOOL_T Controls storage of data. If TRUE, data is stored in the server; if FALSE, no
data is stored.
Unlock; ESS_BOOL_T Controls unlocking of data blocks. If TRUE, all relevant blocks which are
locked will be unlocked (after data is stored, if necessary). If FALSE, no
blocks are unlocked.
abortOnError; ESS_BOOL_T If TRUE, data load stops on the first error. Otherwise, data load continues.
pRules; “ESS_OBJDEF_T” on page Pointer to the rules file object definition structure.
145
Notes
l This function must be followed by at least one call to EssSendString to send the update
specification, and then a call to EssEndDataload.
l Each string passed to EssSendString following EssBeginDataload must be terminated with
a carriage return/linefeed character sequence ("\r\n").
l If both the Store and Unlock flags are set to FALSE, the database performs only a syntax check
of the update specification.
l Unlike EssBeginUpdate, which ignores input rows (records) after an improper input row,
this function processes the remaining input rows, and commits them if appropriate.
l EssEndDataload returns a linked list of errors in “ESS_MBRERR_T” on page 142.
Return Value
None.
Access
EssBeginDataload requires the caller to have write privilege (ESS_PRIV_WRITE) to the active
database.
Example
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
ESS_STR_T Query1, Query2;
ESS_PMBRERR_T pMbrErr;
Store = ESS_TRUE;
231
Unlock = ESS_FALSE;
Query1 = "Year Market Scenario Measures Product 12345";
Query2 = " Jan East Scenario Measures Coke 125";
/* Begin Update */
sts = EssBeginDataload (hCtx, Store, Unlock, ESS_FALSE, ESS_NULL);

if(!sts)
sts = EssSendString(hCtx, Query1);
/* End Update */
if(!sts)
sts = EssEndDataload(hCtx, &pMbrErr);
See Also
l EssSendString
l EssEndDataload
l EssBeginUpdate
l EssEndUpdate
l EssUpdate
l EssImport
EssBeginDataloadASO
Starts a data load on an aggregate storage database.
Syntax
ESS_FUNC_M EssBeginDataloadASO (hCtx, Store, Unlock, abortOnError, pRules, ulBufferId);
Store ESS_BOOL_T Controls storage of data. If ESS_TRUE, data is stored in the server; if
ESS_FALSE, no data is stored.
Unlock ESS_BOOL_T Not supported for aggregate storage databases. You must always pass
ESS_FALSE for this parameter.
abortOnError ESS_BOOL_T ESS_TRUE indicates that the data load will be aborted in case of errors during
the process.
pRules “ESS_OBJDEF_T” on Pointer to the rules file object definition structure.

page 145
ulBufferId ESS_ULONG_T ID of a data load buffer. To destroy a buffer before a data load is complete,
you must use the same ulBufferId number that was used to initialize the buffer.
Notes
232
l Each string passed to EssSendString following EssBeginDataloadASO must be terminated
with a carriage return/linefeed character sequence ("\r\n").
l If the Store flag is set to FALSE, the database performs only a syntax check of the update
specification.
Return Value
Returns zero if successful; otherwise, returns an error code.
Access
This function requires the caller to have write privilege (ESS_PRIV_WRITE) to the active
database.
Example
void TestBeginDataloadASO(ESS_HCTX_T hCtx, ESS_STR_T AppName, ESS_STR_T DbName)
{
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
ESS_BOOL_T abortOnError;
ESS_STR_T loadString;
ESS_OBJDEF_T rulesFile;
ESS_ULONG_T ulSize;
/* EssLoadBufferInit */
ulSize = 100;
ulBufferId = 201;
sts = EssLoadBufferInit(hCtx, AppName, DbName, ulBufferId,
/* EssBeginDataloadASO, EssSendString, EssEndDataload */

Store = ESS_TRUE;
Unlock = ESS_FALSE;
abortOnError = ESS_FALSE;
loadString = "Mar Sale \"Curr Year\" \"Original Price\" \"017589\" \"13668\"
Cash \"No Promotion\" \"1 to 13 Years\" \"Under 20,000\" \"Digital Cameras\" 111";
233
sts = EssBeginDataloadASO (hCtx, Store, Unlock, abortOnError, ESS_NULL,
ulBufferId);
printf("EssBeginDataloadASO sts: %ld\n",sts);
sts = EssSendString(hCtx, loadString);
printf("EssSendString sts: %ld\n",sts);
printf("EssEndDataload sts: %ld\n",sts);
/* EssLoadBufferTerm */
ulBufferCnt = 1;
printf("\Commit data to main slice and destroy buffer:\n");
sts = EssLoadBufferTerm(hCtx, AppName, DbName, ulBufferCnt, ulBufferIdAry,
ulCommitType,
ulActionType, ulOptions);
See Also
l EssLoadBufferInit
l EssSendString
l EssEndDataload
l EssLoadBufferTerm
l EssImportASO
l EssUpdateFileASO
l EssUpdateFileUTF8ASO
l EssListExistingLoadBuffers
l EssMergeDatabaseData
EssBeginDataloadEx
Starts sending an update specification to the active database, and can unlock any data blocks
locked for update. The update data can either be stored in the database, or just verified and any
errors returned.
Syntax
ESS_STS_T EssBeginDataloadEx (hCtx, Store, Unlock, abortOnError, pRules, fullMbrNames);
234
Store ESS_BOOL_T Controls storage of data.

l ESS_TRUE
Data is stored in the server.
l ESS_FALSE
No data is stored.
Unlock ESS_BOOL_T Controls unlocking of data blocks. If TRUE, all relevant blocks which are
locked will be unlocked (after data is stored, if necessary). If FALSE, no
blocks are unlocked.
abortOnError; ESS_BOOL_T If TRUE, data load stops on the first error. Otherwise, data load continues.
pRules “ESS_OBJDEF_T” on Pointer to the rules file object definition structure.

page 145
fullMbrNames ESS_BOOL_T If TRUE, the error log prints full member names for the entire record.
Notes
l Each string passed to EssSendString following EssBeginDataloadEx must be terminated with
a carriage return/linefeed character sequence ("\r\n").
l Unlike EssBeginUpdate, which ignores input rows (records) after an improper input row,
this function processes the remaining input rows, and commits them if appropriate.
l EssEndDataload returns a linked list of errors in “ESS_MBRERR_T” on page 142.
Return Value
None.
Access
EssBeginDataloadEx() requires the caller to have write privilege (ESS_PRIV_WRITE) to the
active database.
Example
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
235
Store = ESS_TRUE;
Unlock = ESS_FALSE;
/* Begin Update */
sts = EssBeginDataloadEx(hCtx, Store, Unlock, ESS_FALSE, ESS_NULL, ESS_TRUE);

if(!sts)
/* End Update */
if(!sts)
See Also
l EssSendString
l EssEndDataload
l EssBeginUpdate
l EssEndUpdate
l EssUpdate
l EssImport
EssBeginIncrementalBuildDim
Starts the process of building members on the active database. Essbase Server opens the active
database's outline and keeps it open and ready for the next steps of dimension build.
Syntax
ESS_FUNC_M EssBeginIncrementalBuildDim(hCtx);
Return Value
Example
ESS_FUNC_M
ESS_IncBuildDim( ESS_HCTX_T hCtx)
{
ESS_STS_T sts = 0;
ESS_OBJDEF_T RulesObj;
ESS_OBJDEF_T DataObj;
ESS_STR_T ErrorName;
ESS_APPNAME_T appname;
ESS_DBNAME_T dbname;
memset(&RulesObj,0,sizeof(ESS_OBJDEF_T));
236
memset(&DataObj,0,sizeof(ESS_OBJDEF_T));
strcpy(appname, "sample");
strcpy(dbname,"basic");
RulesObj.hCtx = hCtx;
RulesObj.FileName = "genref";
RulesObj.AppName = appname;
RulesObj.DbName = dbname;
RulesObj.ObjType = ESS_OBJTYPE_RULES;
DataObj.hCtx = hCtx;
DataObj.FileName = "genref";
DataObj.AppName = appname;
DataObj.DbName = dbname;
DataObj.ObjType = ESS_OBJTYPE_TEXT;
ErrorName = "builddim.err";
if (!sts)
sts =
EssIncrementalBuildDim(hCtx,&RulesObj,&DataObj,NULL,ErrorName,true,ESS_INCDIMBUILD_BUILD
,NULL);
if (!sts)
sts =
EssIncrementalBuildDim(hCtx,&RulesObj,&DataOb,NULL,ErrorName,true,ESS_INCDIMBUILD_VERIFY
,NULL);
if (!sts)
sts =
EssIncrementalBuildDim(hCtx,&RulesObj,&DataOb,NULL,ErrorName,true,ESS_INCDIMBUILD_SAVEOT
L,"tmpotl");
sts = EssBeginStreamBuildDim(hCtx, &RulesObj,ESS_INCDIMBUILD_BUILD,"tmpotl");

if (!sts)
sts = EssSendString(hCtx, "600 600-20 600-20-20\n");
if (!sts)
if (!sts)
sts = EssEndStreamBuildDim(hCtx,ErrorName,false);
sts = EssEndIncrementalBuildDim(hCtx,ESS_DOR_ALLDATA,"tmpotl",ErrorName,false);
return sts;
}
See Also
l EssIncrementalBuildDim
l EssBeginIncrementalBuildDim
l EssEndIncrementalBuildDim
l EssEndStreamBuildDim
237
EssBeginReport
Starts sending a report specification to the active database. This call must be followed by
successive calls to EssSendString to send the report specification, and finally by a call to
EssEndReport. The report data can either be output, or the report specification can just be
verified and any errors returned. Also, the corresponding data blocks in the database can
optionally be locked by this call (lock for update).
Syntax
ESS_FUNC_M EssBeginReport (hCtx, Output, Lock);
Output ESS_BOOL_T Controls output of data. If TRUE, data is output from the server, according to the specified
report. If FALSE, no data is output.
Lock ESS_BOOL_T Controls block locking. If TRUE, all blocks which are accessed by the report specification
are locked for update. If FALSE, no blocks are locked.
Notes
l This function must be followed by at least one call to EssSendString, followed by a call
to EssEndReport
.
l If this function causes data to be output (Output flag is TRUE), the returned data can be
read by calling EssGetString.
l If this function causes blocks to be locked (Lock flag is TRUE), the caller is responsible for
unlocking the locked blocks (e.g. by calling EssUpdate with the Unlock flag set to TRUE).
l If both the Output and Lock flags are set to FALSE, the database performs only a syntax check
of the report specification.
Return Value
None.
Access
This function requires the caller to have read privilege (ESS_PRIV_READ) to one or more
members in the active database.
Example
ESS_FUNC_M
ESS_Report (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
238
{
ESS_STR_T rString = NULL;
sts = EssBeginReport (hCtx,ESS_TRUE,ESS_FALSE);
if (!sts)
sts = EssSendString (hCtx, "<Desc Year !");
if (!sts)
/**************
* Get report *
**************/
if (!sts)
{
printf ("%s", rString);
}
printf ("\r\n");
return(sts);
}
See Also
l EssBeginUpdate
l EssEndReport
l EssGetString
l EssReport
l EssReportFile
l EssSendString
EssBeginStreamBuildDim
Starts the dimension build process.
This function must be called before EssEndStreamBuildDim. After calling this function, call
EssSendString to send source records to Essbase server.
Syntax
ESS_FUNC_M EssBeginStreamBuildDim (hCtx, RulesObj, usBuildOption, szTmpOtlFilename)
239

Build members only.
szTmpOtlFilename ESS_STR_T The temp outline file name. Essbase creates a temporary outline file with
extension "otb" if the resulting outline in this round of dimension build has
outline verification errors.
Notes
applications must send the UTF-8 encoded Unicode byte order mark (BOM) in the text stream
immediately after calling this function. For an example, see “Specifying the Byte Order
Encoding” on page 69.
Return Value
Example
ESS_FUNC_M
{
ESS_STS_T sts = 0;
240
if (!sts)
sts =
,NULL);
if (!sts)
sts =
,NULL);
if (!sts)
sts =
L,"tmpotl");

if (!sts)
if (!sts)
if (!sts)
return sts;
}
See Also
EssBeginUpdate
Starts sending an update specification to the active database. This call must be followed by
successive calls to EssSendString to send the update specification, and finally by a call to
EssEndUpdate. The update data can either be stored in the database, or just verified and any
errors returned. Also, any data blocks locked for update can be unlocked by this call.
Syntax
ESS_FUNC_M EssBeginUpdate (hCtx, Store, Unlock);
241
Store ESS_BOOL_T Controls storage of data. If TRUE, data is stored in the server; if FALSE, no data is stored.
Unlock ESS_BOOL_T Controls unlocking of data blocks. If TRUE, all relevant blocks which are locked will be
unlocked (after data is stored, if necessary). If FALSE, no blocks are unlocked.
Notes
l This function must be followed by at least one call to EssSendString, followed by a call
to EssEndUpdate.
l Each string passed to EssSendString following this function must be terminated with a
carriage return/linefeed character sequence ("\r\n").
Return Value
None.
Access
database.
Example
ESS_VOID_T
ESS_BeginUpdate(ESS_HCTX_T hCtx)
{
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
ESS_STR_T Query;
Store = ESS_TRUE;
Unlock = ESS_FALSE;
Query = "Year Market Scenario Measures Product 12345";
/* Begin Update */
sts = EssBeginUpdate (hCtx, Store, Unlock);

if(!sts)
sts = EssSendString(hCtx, Query);
/* End Update */
if(!sts)
242
sts = EssEndUpdate(hCtx);
}
See Also
l EssBeginReport
l EssEndUpdate
l EssSendString
l EssUpdate
l EssUpdateFile
EssBuildDimension
Allows the addition or removal of members from the outline in the active database from a data
file and rules file.
Syntax
ESS_FUNC_M EssBuildDimension (hCtx, rulesObj, dataObj,
mbrUser, ErrorName);
pRulesObj “ESS_OBJDEF_T” on page 145 Pointer to rules file object definition structure.
pDataObj “ESS_OBJDEF_T” on page 145 Pointer to data file object definition structure.
pMbrUser “ESS_MBRUSER_T” on page 142 SQL user structure (if data source is SQL database). A NULL SQL user
structure indicates a non SQL data source.
ErrorName ESS_STR_T Name of error output file on client.
Notes
l If MbrUser is not NULL, an SQL data source is assumed.
l See EssImport for information on importing data sources.
l The database must be the active database. See EssSetActive.
Return Value
None.
Access
This function requires the caller to have database design privilege for the specified database
Example
ESS_FUNC_M
ESS_BuildDim(ESS_HCTX_T hCtx)
{
243
ESS_MBRUSER_T User;
RulesObj.FileName = "Prodmap";
DataObj.FileName = "Prodtabl";
sts = EssBuildDimension (hCtx, &RulesObj, &DataObj,

NULL, ErrorName);
return (sts);
/*******************************************************************/
/* */
/* When a SQL data source is defined in the rules file, define */
/* the variables in the ESS_OBJDEF_T DataObj structure as follows: */
/* DataObj.hCtx = hCtx; */
/* DataObj.AppName = NULL; */
/* DataObj.DbName = NULL; */
/* DataObj.ObjType = ESS_OBJTYPE_NONE; */
/* DataObj.FileName = NULL; */
/* */
/* Also, provide strings for the variables in the ESS_MBRUSER_T */
/* User structure; for example: */
/* User.User = "Dbusernm"; */
/* User.Password = "Dbpasswd"; */
/* */
/* Use a blank string for User and Password, if the SQL source */
/* does not require user and password information; for example: */
/* User.User = ""; */
/* User.Password = ""; */
/* */
/* Also, define sts as follows: */
/* sts = EssBuildDimension (hCtx, &RulesObj, &DataObj, */
/* &User, ErrorName); */
/* */
/*******************************************************************/
}
See Also
l EssImport
l EssBuildDimFile
l EssBuildDimStart
l EssOtlRestructure
244
EssBuildDimFile
Builds a data file used to add or remove members from the active database outline. See
EssBuildDimension for more information.
Syntax
ESS_FUNC_M EssBuildDimFile (hCtx, RulesObj, DataObj, MbrUser,
ErrorName, fOverwriteErrorFile);
RulesObj “ESS_OBJDEF_T” on page 145 Pointer to rules file object definition structure.
DataObj “ESS_OBJDEF_T” on page 145 Pointer to data file object definition structure.
MbrUser “ESS_MBRUSER_T” on page 142 SQL user structure (if data source is SQL database). NULL
structure indicates a non-SQL data source.
ErrorName ESS_STR_T Error name output on client.
fOverwriteErrorFile ESS_BOOL_T A Boolean value which detemines whether this function

overwrites an existing file name ErrorFile.
Notes
l If MbrUser is not NULL, an SQL data source is assumed.
l The description of EssImport provides information on importing data sources.
l The database must be the active database. See the description of EssSetActive.
l EssBuildDimStart must be called prior to using this function.
l This function can be called repeatedly prior to restructuring to add members via multiple
rules and/or data file to the outline.
l The database must be restructured after completion of call(s) to this function.
l The outline must be unlocked after resturcturing.
Return Value
Returns a zero if successful.
Access
This function requires database design privilege ESS_PRIV_DBDESIGN for the specified
database.
Example
ESS_FUNC_M EssBuildDimFile (ESS_HCTX_T hCtx)
{
245
RulesObj.FileName = "Prodmap";
DataObj.FileName = "Prodtabl";
sts = EssBuildDimFile (hCtx, &RulesObj,

&DataObj, NULL, ErrorName);
return (sts);
}
See Also
l EssImport
l EssBuildDimension
l EssBuildDimStart
l EssOtlRestructure
l EssUnlockObject
EssBuildDimStart
Starts the process to add or remove members from the active database outline.
Syntax
ESS_FUNC_M EssBuildDimStart (hCtx);
Notes
l See the description of EssImport for information on importing data sources.
l The database must be the active database. See the description of EssSetActive.
l The outline object must be locked prior to calling EssBuildDimStart. See the description
for EssLockObject.
Return Value
Returns zero if successful, otherwise returns an error code.
Access
This function requires the caller to have database design privilege for the specified database
Example
ESS_FUNC_M Ess_BuildDimStart (ESS_HCTX_T hCtx)
{
246
sts = EssBuildDimStart (hCtx);
return (sts);
}
See Also
l EssImport
l EssBuildDimension
l EssBuildDimFile
l EssLockObject
l EssOtlRestructure
EssBuildDimXml
Performs outline editing using an XML file to make basic changes to the database outline. This
XML outline editing method is a streamlined way to make basic outline edits without needing
to use a rules file nor invoke the Outline API.
To use the XML outline editing feature, aggregate storage outlines that were created in an earlier
release of Essbase must first be migrated to the current release. Once an aggregate storage outline
is migrated, it cannot be edited in an earlier release client. Block storage outlines created in an
earlier release of Essbase can use XML outline editing without needing to migrate the outline.
Syntax
ESS_FUNC_M EssBuildDimXml (hCtx, szXmlData, szErrorFile, ErrFileOverWrite);
szXmlData ESS_POBJDEF_T Pointer to XML object.
szErrorFile ESS_STR_T Name of error file to output on the client.
ErrFileOverWrite ESS_BOOL_T A Boolean value which determines whether this function overwrites an existing
error file.
Notes
l Before calling this function, you must create a valid restructuring XML document based on
the XSD schema file, mbredit.xsd, located in essbase\bin. Essbase processes the XML
document, based strictly on the schema, performing outline edits indicated in the XML
document.
l The XSD schema includes the following element names:
Element Name Description
mbrUpdate Sets member attribute information. Similar to EssOtlSetMemberInfo.
mbrAdd Adds a member to the outline. Similar to EssOtlAddMember.
247
Element Name Description
mbrDelete Removes a member from the outline. Similar to EssOtlDeleteMember.
mbrRename Renames a member. Similar to EssOtlRenameMember.

Caution! If you use XML outline editing to rename a member, the cell data is not retained.
mbrMove Moves a member. Similar to EssOtlMoveMember.
mbrAssoc Associates an attribute member with a standard or base member. Similar to

EssOtlAssociateAttributeMember.
dimAdd Adds a dimension to the outline. Similar to EssOtlAddDimension.
dimUpdate Sets member attribute information. Similar to EssOtlSetMemberInfo.
l In the XML document, to use some special characters in member names, you must replace
them with character entity references.
Desired Special Character Character Entity Reference Example
& (ampersand) & &IM& produces &IM&
< (less-than symbol) < <ST produces <ST
> (greater-than symbol) > OP> produces OP>
" (straight quotation mark) " "mbr1" produces "mbr1"
' (apostrophe) ' CC&R's produces CC&R's
l In the XML document, the value you specify for the otlVersion element must be the
correct revision number of the outline. You can use the revision number to keep track how
many times you update the outline using the XML document. If you specify an incorrect
revision number, the outline edit will abort, returning the correct revision number. Or, you
can specify -1 as the value for otlVersion, which causes Essbase to ignore the revision
number check and reset otlVersion to 0.
For example:
<otlEditMain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="mbredit"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
otlVersion="-1">
Return Value
Access
This function requires database design privilege ESS_PRIV_DBDESIGN for the specified
database.
248
Example
C API Function Call Example
ESS_FUNC_M EssBuildDimXml (ESS_HCTX_T hCtx)

{
ESS_OBJDEF_T xmlObj;
memset(&xmlObj, '\0', sizeof(ESS_OBJDEF_T));
xmlObj.hCtx = hCtx;
xmlObj.ObjType = ESS_OBJTYPE_XML;
xmlObj.AppName = "sample";
xmlObj.DbName = "basic";
xmlObj.FileName = "BuildDimSampleBasic";
sts = EssBuildDimXml(hCtx,&xmlObj,"xmlbuild.err",ESS_TRUE);
return sts;
}
XML Document Example

The XML object referenced in the function call must be a valid XML file, formed in congruence
to the following example:
<?xml version="1.0" encoding="UTF-8"?>
<otlEditMain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="mbredit"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
otlVersion="0">




<otlUpdate caseSensitive="true" enableMemberType="false">

<impliedShareSetting> default </impliedShareSetting>
<aliasTable>LongName</aliasTable>
<aliasTable>aliastable3</aliasTable>
<dtsMbr mbrName="Q-T-D" number="2" enable="true" />
</otlUpdate>
<mbrDelete thisMbr="Qtr1"/>
<mbrDelete thisMbr="Qtr2"/>
<mbrDelete thisMbr="Measures"/>
<mbrUpdate thisMbr="Year">
<mbrInfo>
<alias aliasTable="default" alias="Year"/>
<alias aliasTable="LongName" alias="Year extension"/>
<dataStorage>dynamic</dataStorage>
</mbrInfo>
</mbrUpdate>
249
<mbrAdd mbrName="Qtr1" parent="Year" >
</mbrAdd>
<mbrUpdate thisMbr="Qtr1">
<mbrInfo>
<alias aliasTable="default" alias="Q1"/>
<alias aliasTable="LongName" alias="Quarter1"/>
<consolidation>+</consolidation>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Jan" parent="Qtr1" />

<mbrUpdate thisMbr="Jan">
<mbrInfo>
<dataStorage>storeData</dataStorage>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Feb" parent="Qtr1" preSibling="Jan" />

<mbrUpdate thisMbr="Feb">
<mbrInfo>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Qtr2" parent="Year" preSibling="Qtr1"/>

<mbrUpdate thisMbr="Qtr2">
<mbrInfo>
<alias aliasTable="default" alias="Q2"/>
<alias aliasTable="LongName" alias="Quarter2"/>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Apr" parent="Qtr2" />

<mbrUpdate thisMbr="Apr">
<mbrInfo>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="May" parent="Qtr2" preSibling="Apr"/>

<mbrUpdate thisMbr="May">
<mbrInfo>
</mbrInfo>
</mbrUpdate>
250

<dimAdd dimName="Measures" preSibling="Year" >

<properties>
<category>account</category>
<storage>dense</storage>
<storageCategory>account</storageCategory>
</properties>
</dimAdd>
<mbrUpdate thisMbr="Measures">
<mbrInfo>
<dataStorage>labelOnly</dataStorage>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Profit" parent="Measures" />

<mbrUpdate thisMbr="Profit">
<mbrInfo>
<alias aliasTable="default" alias="Pf"/>
<alias aliasTable="LongName" alias="Profitex"/>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Margin" parent="Profit" />

<mbrUpdate thisMbr="Margin">
<mbrInfo>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Sales" parent="Margin" />

<mbrUpdate thisMbr="Sales">
<mbrInfo>
<alias aliasTable="LongName" alias="Revenue"/>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="COGS" parent="Margin" preSibling="Sales" />

<mbrUpdate thisMbr="COGS">
<mbrInfo>
<consolidation>-</consolidation>
<alias aliasTable="aliastable3" alias="Cost of Goods Sold"/>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Ratios" parent="Measures" preSibling="Margin" />

<mbrUpdate thisMbr="Ratios">
<mbrInfo>
<dataStorage>labelOnly</dataStorage>
251
<consolidation>~</consolidation>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Margin %" parent="Ratios" />

<mbrUpdate thisMbr="Margin %">
<mbrInfo twoPassCalc="true" >
<formula>Margin % Sales;</formula>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Profit %" parent="Ratios" preSibling="Margin %" />

<mbrUpdate thisMbr="Profit %">
<formula>Profit % Sales;</formula>
</mbrInfo>
</mbrUpdate>
<mbrAdd mbrName="Profit per Ounce" parent="Ratios" preSibling="Profit %" />

<mbrUpdate thisMbr="Profit per Ounce">
<formula>Profit/@ATTRIBUTEVAL(@NAME(Ounces));</formula>
</mbrInfo>
</mbrUpdate>
</otlEditMain>
EssCalc
Sends a single string. This function is equivalent to making a call to EssBeginCalc, followed
by calls to EssSendString, and finally to EssEndCalc. The calculation can either be initiated,
or the calculation script can just be verified and any errors returned.
Syntax
ESS_FUNC_M EssCalc (hCtx, Calculate, CalcScript);
Calculate ESS_BOOL_T Controls calculation of the calc script. If TRUE, the calculation script is executed and the
call is asynchronous.
CalcScript ESS_STR_T The calculation script, as a single string (must be less than 64 KB).
Notes
l The calculation script string must be less than 64 KB long.
252
l If this function succeeds and the calculation is started, it will continue on the server as an
asynchronous process after the return from this call. The caller must check at regular
intervals to see if the process has completed by calling EssGetProcessState until it returns
ESS_STATE_DONE.
l This API call is asynchronous only if the Calculate parameter is TRUE. Otherwise, it is a
simple synchronous request.
During an asynchronous request, control is passed back to the program immediately, before
the request completes. The set of valid requests for the current API context handle is limited
during the time the asynchronous request is running. If you give an invalid request during
that time, an error is returned. The list of valid API calls on the API context during an
asynchronous operation is: EssGetProcessState, EssCancelProcess.
l If the Calculate flag is set to FALSE, the database performs only a syntax check of the calc
script, and the call is synchronous.
Return Value
None.
Access
This function requires the caller to have calculation privilege (ESS_PRIV_CALC) to the active
database.
Example
ESS_FUNC_M
ESS_CalcLine (ESS_HCTX_T hCtx)
{
ESS_STR_T Script;

sts = EssCalc(hCtx, ESS_TRUE, Script);
if (!sts)
{
while (!sts && (pState.State !=
ESS_STATE_DONE))
}
return(sts);
}
See Also
l EssBeginCalc
l EssCalcFile
l EssDefaultCalc
l EssEndCalc
l EssGetDefaultCalc
l EssSendString
253
l EssSetDefaultCalc
EssCalcFile
Executes a calculation script against the active database from a file.
Syntax
ESS_FUNC_M EssCalcFile (hDestCtx, hSrcCtx, AppName, DbName,
FileName, Calculate);
hDestCtx ESS_HCTX_T API context handle of target database on Essbase Server.
hSrcCtx ESS_HCTX_T API context handle for the calculation script file location. The calculation script file can
reside on the client computer or on the same Essbase Server computer as the target database.
AppName ESS_STR_T Application name for the calculation script file location.
DbName ESS_STR_T Database name for calculation script file location.
FileName ESS_STR_T Name of calculation script file.
Calculate ESS_BOOL_T Controls calculation of the calculation script. If TRUE, the calculation script is executed
and the call is asynchronous.
Notes
l The size of the calculation script cannot exceed 64 KB.
ESS_STATE_DONE.
l This API call is asynchronous only if the Calculate parameter is TRUE. Otherwise, it is a
simple synchronous request.
during the time the asynchronous request is running. If you give an invalid request during
that time, an error is returned. The list of valid API calls on the API context during an
asynchronous operation is: EssGetProcessState, EssCancelProcess.
Return Value
None.
Access
database.
254
Example
ESS_FUNC_M
ESS_CalcFile (ESS_HCTX_T hCtx)
{
ESS_SHORT_T isResponse;
ESS_HCTX_T hSrcCtx;
ESS_BOOL_T isObject = ESS_FALSE;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
hSrcCtx = hCtx;
AppName = "Sample";
DbName = "Basic";
FileName = "Test";
sts = EssCalcFile (hCtx, hSrcCtx, AppName,

DbName, FileName, ESS_TRUE);
if (!sts)
{
ESS_STATE_DONE))
}
return(sts);
}
See Also
l EssBeginCalc
l EssCalc
l EssDefaultCalc
l EssSetDefaultCalcFile
EssCalcFileWithRuntimeSubVars
Executes a calculation script against the active database with the specified runtime substitution
variables. Runtime substitution variables can be specified in a text file (with a .rsv extension;
which must be located on the client computer) or as a string of key/value pairs.
Syntax
ESS_FUNC_M EssCalcFileWithRuntimeSubVars (hDestCtx, hSrcCtx, AppName, DbName, FileName,
RtSV, bRtSVFile, Calculate);
hDestCtx ESS_HCTX_T API context handle of the target database on Essbase Server.
hSrcCtx ESS_HCTX_T API context handle for the location of the calculation script file. The calculation script file
can be located on the client computer or on the same Essbase Server as the target database.
255
AppName ESS_STR_T Name of the application that is associated with the calculation script file.
DbName ESS_STR_T Name of the database that is associated with the calculation script file.
FileName ESS_STR_T Name of the calculation script file. The calculation script file can be located on the same
Essbase Server on which the target database is located or on the client computer.
RtSV ESS_STR_T One of the following options:

l Name and full path of a runtime substitution variable file (for example, C:
\myRTSVfile.rsv), which must be located on the client computer. Essbase does
not support runtime substitution variable files located on the Essbase Server computer.
You must create the runtime substitution variable file, which is a text file with
an .rsv extension. Each line in the file defines one runtime substitution variable as a
key/value pair and must end with a semicolon. In this example of an .rsv file, the
name and value of four runtime substitution variables are specified (for example, the
value of the runtime substitution variable named “a” is 100):
a=100;
b=200;
c=@CHILDREN("100");
d=@TODATE("DD/MM/YY","10/11/12");
l A string of runtime substitution variable key/value pairs. The string must be enclosed
with single quotation marks, and key/value pairs must be separated by a semicolon,
including a semicolon after the last runtime substitution variable in the string and
before the terminal single quotation mark. In this example of a runtime substitution
variable string, the name and value of four runtime substitution variables are specified
(for example, the value of the runtime substitution variable named “a” is 100):
'a=100;b=@CHILDREN("100");c="Actual"->"Final";d="New
York";'
This argument is used with the bRtSVFile argument.
bRtSVFile ESS_BOOL_T Flag indicating whether the RtSV argument references the name and full path of a runtime
substitution variable file (TRUE) or a string of runtime substitution variable key/value pairs
(FALSE).
Return Value
None.
Access
A call to this function requires calculation privilege (ESS_PRIV_CALC) for the active database.
Example
void Ess_CalcFileWithRuntimeSubVars(ESS_HINST_T hInst, ESS_HCTX_T hCtx)
{
ESS_STS_T sts;
ESS_STR_T AppName = "Sample";
ESS_STR_T FileName = "testrt"; \\ Server side calc script file. PLease provide this
256
when using server side calc script file
//ESS_STR_T FileName = "D:\\temp\\testrt.csc"; \\Client side calc script file.
//ESS_STR_T Param = "D:\\temp\\temp1.rsv"; \\ Client side param file.
ESS_STR_T Param = "mySales=700"; \\ Client side param string.
ESS_BOOL_T Calculate = TRUE;

//hLocalCtx = hCtx;
//sts = EssSetActive (hCtx, AppName, DbName, &Access);
//For calc file on server With Param String

sts = EssCalcFileWithRuntimeSubVars(hCtx, hCtx, AppName, DbName, FileName, Param,
FALSE, Calculate);
//For Calc file on client With Param String

sts = EssCalcFileWithRuntimeSubVars(hCtx, hLocalCtx, NULL, NULL, FileName, Param,
FALSE, Calculate);
//For calc file on server With Param File

sts = EssCalcFileWithRuntimeSubVars(hCtx, hCtx, AppName, DbName, FileName, Param,
TRUE, Calculate);
//For calc file on client With Param File

sts = EssCalcFileWithRuntimeSubVars(hCtx, hLocalCtx, NULL, NULL, FileName, Param,
TRUE, Calculate);
if (!sts)
{
ESS_STATE_DONE))
}
if(sts)
printf("API could not be executed.");
}
See Also
l EssGetRuntimeSubVars
l EssCalcWithRuntimeSubVars
l EssCancelProcess
l EssBeginCalc
l EssCalc
l EssDefaultCalc
l EssSetDefaultCalc
257
EssCalcWithRuntimeSubVars
Executes a calculation script with the specified runtime substitution variables, which are
specified as a string of key/value pairs. The calculation can be initiated, or the calculation script
can just be verified and any errors returned.
Syntax
ESS_FUNC_M EssCalcWithRuntimeSubVars (hCtx, CalcScript, RtSV, Calculate);
CalcScript ESS_STR_T The calculation script, as a single string.

The calculation script string cannot exceed 64 KB.
RtSV ESS_STR_T A string that specifies runtime substitution variable key/value pairs. The string must be
enclosed with single quotation marks, and key/value pairs must be separated by a semicolon,
including a semicolon after the last runtime substitution variable in the string and before
the terminal single quotation mark. In this example of a runtime substitution variable string,
the name and value of four runtime substitution variables are specified (for example, the
value of the runtime substitution variable named “a” is 100):
'a=100;b=@CHILDREN("100");c="Actual"->"Final";d="New York";'
Notes
l If this function succeeds and the calculation is started, it continues on the server as an
ESS_STATE_DONE.
l This API call is asynchronous only if the Calculate parameter is TRUE. Otherwise, the
call is a simple synchronous request.
during the time the asynchronous request is running. If an invalid request is made during
that time, an error is returned. Valid API calls on the API context during an asynchronous
operation: EssGetProcessState, EssCancelProcess.
l If the Calculate parameter is set to FALSE, the database performs only a syntax check of
the calculation script, and the call is synchronous.
Return Value
None.
Access
A call to this function requires calculation privilege (ESS_PRIV_CALC) for the active database.
258
Example
ESS_FUNC_M
ESS_CalcWithRuntimeSubVars(ESS_HCTX_T hCtx)
{
ESS_STR_T Script;
ESS_STR_T ParamString = "mySales=700;myCOGS=100;";
Script = "SET RUNTIMESUBVARS {salesNum =400; mySales=300; myRTVar=@CHILDREN(\"100\");

kmdsdmclms=@TODATE(\"DD/MM/YY\",\"10/11/12\"); myCOGS=50;};FIX (@INTERSECT(&myRTVar,
\"100-10\")) Sales = &mySales; COGS=&myCOGS; ENDFIX;";
sts = EssCalcWithRuntimeSubVars(hCtx, Script, ParamString, ESS_TRUE);
if (!sts)
printf ("\r\nAPI EssCalcWithParam executed successfully...\r\n\r\n");
}
See Also
l EssCalcFileWithRuntimeSubVars
l EssGetRuntimeSubVars
l EssCancelProcess
l EssBeginCalc
l EssCalc
l EssDefaultCalc
l EssSetDefaultCalc
EssCancelAsyncProc
Cancels an asynchronous data load or dimension build process.
Syntax
ESS_FUNC_M EssCancelAsyncProc (hCtx, ErrorFileName, ErFileOverWrite);
ErrorFileName ESS_STR_T An error file name.
ErFileOverWrite ESS_BOOL_T If TRUE, overwrite the error file.
Notes
Call this function after initiating an asynchronous process using EssAsyncImport or
EssAsyncBuildDim.
259
Return Value
If successful, the network connection is closed and the error log is returned. Otherwise, returns
an error code.
Example
See the example for EssAsyncBuildDim.
See Also
l EssAsyncBuildDim
l EssAsyncImport
l EssAsyncImportASO
l EssCloseAsyncProc
EssCancelProcess
Cancels an asynchronous process that has not yet completed
Syntax
ESS_FUNC_M EssCancelProcess (hCtx);
Notes
l If you use this function to cancel a process, the database may be left in an inconsistent state,
with only some of the data recalculated.
l Calling this function except after initiating a successful asynchronous database operation
(e.g. a calculation) will generate an error.
Return Value
None.
Access
This function requires no special privilege.
Example
ESS_VOID_T
ESS_CancelProcess(ESS_HCTX_T hCtx)
{
ESS_STR_T Script;
ESS_USHORT_T Count;
260
if (!sts)
if (!sts)
/*************************************
Check process state and cancel it
if it takes too long
*************************************/
if (!sts)
{
ESS_STATE_DONE))
{
Count = Count + 1;
if (Count == 1000)
sts = EssCancelProcess(hCtx);

}
}
}
See Also
l EssBeginCalc
l EssCalc
l EssImport
EssCheckAttributes
Returns attribute information for each specified member.
Syntax
ESS_FUNC_M EssCheckAttributes (hCtx, Count, pMemberNameArray, ppAttributeTypeArray);
Count; ESS_USHORT_T Number of given dimensions and members.
pMemberNameArray; ESS_PMBRNAME_T An array of names of given dimensions and members.
261
ppAttributeTypeArray; ESS_PPUSHORT_T One of the following constant identifiers (see Table 6, “C API Attributes
Terminology,” on page 96) for the attribute type array:
l ESS_ATTRIBUTE_DIMENSION
l ESS_ATTRIBUTE_MEMBER
l ESS_STANDARD_DIMENSION
l ESS_STANDARD_MEMBER
l ESS_BASE_DIMENSION
l ESS_BASE_MEMBER
l ESS_ATTRIBUTED_MEMBER
l ESS_INVALID_MEMBER
Access
Example
void ESS_CheckAttributes()
{
ESS_STS_T sts=-1,sts1=-1;
int counter,i,j;
ESS_PMBRNAME_T pMbrNames=ESS_NULL;
ESS_PUSHORT_T pMbrAttrTypes=ESS_NULL;
ESS_CHAR_T buf[80]="";
/* counter = 4; */
printf("Please enter the number of member names that follow: ");
gets(buf);
counter=atoi(buf);
if (counter)
{
sts1 = EssAlloc(hInst, (counter * sizeof(ESS_MBRNAME_T)),
(ESS_PPVOID_T)&pMbrNames);
if (!sts1)
{
memset(pMbrNames, 0, (counter * sizeof(ESS_MBRNAME_T)));
for (i = 0; i < counter; i++)

{
printf("Enter member name: ");
gets(buf);
strcpy(pMbrNames[i],buf);
}
sts = EssCheckAttributes(hCtx,counter,pMbrNames,&pMbrAttrTypes);
if (sts)
fprintf(stderr, "sts = %ld \n",sts);
else if (pMbrAttrTypes)
{
for (j = 0; j < counter; j++)
{
262
switch(pMbrAttrTypes[j])
{
case ESS_STANDARD_MEMBER:
strcpy(buf,"ESS_STANDARD_MEMBER");
break;
case ESS_STANDARD_DIMENSION:
strcpy(buf,"ESS_STANDARD_DIMENSION");
break;
case ESS_BASE_MEMBER:
strcpy(buf,"ESS_BASE_MEMBER");
break;
case ESS_BASE_DIMENSION:
strcpy(buf,"ESS_BASE_DIMENSION");
break;
case ESS_ATTRIBUTE_MEMBER:
strcpy(buf,"ESS_ATTRIBUTE_MEMBER");
break;
case ESS_ATTRIBUTE_DIMENSION:
strcpy(buf,"ESS_ATTRIBUTE_DIMENSION");
break;
case ESS_ATTRIBUTED_MEMBER:
strcpy(buf,"ESS_ATTRIBUTED_MEMBER");
break;
default:
strcpy(buf,"Unknown attribute type");
}
printf("%s is of type %s\n",pMbrNames[j],buf);
}
printf("\n");
}
}
}
}
See Also
l EssFreeStructure
l EssGetAssociatedAttributesInfo
l EssGetAttributeInfo
l EssOtlAssociateAttributeDimension
l EssOtlAssociateAttributeMember
l EssOtlDisassociateAttributeDimension
l EssOtlDisassociateAttributeMember
l EssOtlFindAttributeMembers
l EssOtlFreeStructure
l EssOtlGetAssociatedAttributes
l EssOtlGetAttributeInfo
263
l EssOtlQueryAttributes
EssCheckMemberName
Checks if a string is a valid member name within the active database outline.
Syntax
ESS_FUNC_M EssCheckMemberName (hCtx, MbrName, pValid);
MbrName ESS_STR_T Member name to be verified.
pValid ESS_PBOOL_T Address of variable to receive valid member flag. Set to TRUE if member is valid.
Notes
This function checks whether the relational span Boolean is set and can determine if the specified
member name is valid in the relational store.
Return Value
If successful, this function returns a flag, pValid, indicating if the name string MbrName is a
valid member name in the active database outline.
Access
This function requires the caller to have at least read access (ESS_PRIV_READ) to the database,
and to have selected it as their active database using EssSetActive.
Example
ESS_FUNC_M
ESS_CheckMemberName(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
ESS_STR_T MbrName;
ESS_BOOL_T pValid;
MbrName = "Profit";
sts = EssCheckMemberName(hCtx, MbrName, &pValid);
if(pValid)
printf("\"%s\" is a valid member name\n",
MbrName);
return (sts);
}
264
See Also
l EssGetMemberInfo
l EssQueryDatabaseMembers
l EssSetActive
EssClearActive
Clears the user's current active application and database.
Syntax
ESS_FUNC_M EssClearActive (hCtx);
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_UnloadDb (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
/*
* IF the current active is the same as the
* unload db, ClearActive first
*/
sts = EssClearActive(hCtx);
/*
* ELSE
*
*/
sts = EssUnloadDatabase(hCtx, AppName,
DbName);
return (sts);
}
See Also
l EssGetActive
l EssSetActive
265
EssClearAliases
Permanently removes all alias tables for the active database.
Syntax
ESS_FUNC_M EssClearAliases (hCtx);
Notes
l This function cannot remove the active alias table nor the default alias table.
l Use EssSetAlias to set an active alias to "default" prior to using this API function.
l Make sure that no one else is using the same database as the one you try to clear alias tables
from by calling EssListConnections.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_ClearAliases (ESS_HCTX_T hCtx)
{
sts = EssClearAliases(hCtx);
if(!sts)
printf("All alias tables are removed.\r\n");
return (sts);
}
See Also
l EssListAliases
l EssRemoveAlias
l EssSetActive
EssClearDatabase
Clears all loaded data in the active database.
Caution! Data deleted using this function cannot be restored. Use it with care!
266
Syntax
ESS_FUNC_M EssClearDatabase (hCtx);
Return Value
None.
Access
This function requires the caller to have Write privilege (ESS_PRIV_WRITE) for the database,
Example
ESS_FUNC_M
ESS_ClearDb (ESS_HCTX_T hCtx)
{
sts = EssClearDatabase(hCtx);
return (sts);
}
See Also
l EssDeleteDatabase
l EssUnloadDatabase
l EssSetActive
EssCloseAsyncProc
Closes the connection for a finished or canceled asynchronous dimension build or data load,
and returns the current state of the process.
Syntax
ESS_FUNC_M EssCloseAsyncProc (hCtx, ProcState);
ProcState ESS_PBLDDL_STATE_T Address of pointer to receive allocated process state structure.
Notes
EssAsyncBuildDim.
Return Value
267
Example
See Also
l EssAsyncBuildDim
l EssAsyncImport
EssClrSpanRelationalSource
Clears the Boolean bSpanRelPart field informing Essbase that pertinent data exists in an attached
relational store. Some other API functions, such as EssQueryDatabaseMembers, read
bSpanRelPart and access the relational store if bSpanRelPart is set.
Syntax
ESS_FUNC_M EssClrSpanRelationalSource (hCtx);
Notes
Several API functions have been enhanced to retrieve information from relational stores.
l EssQueryDatabaseMembers - returns member names from the relational store.
l EssGetMemberInfo - returns information on members in the relational store.
l EssCheckMemberName - checks in the relational store for valid member names.
l EssGetMemberCalc - recognizes a relational member passed as input and returns a null
string for all relational members.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_HINST_T hInst
)
{
268
if (!sts)
if (!sts)
sts = EssClrSpanRelationalSource (hCtx);
/**************
* Get report *
**************/
if (!sts)
{
}
printf ("\r\n");
return(sts);
}
See Also
l EssSetSpanRelationalPartition
EssCommitDatabase
No longer in use, because commits are handled automatically by the Essbase Server. This
function now returns the error message ESS_STS_OBSOLETE. See the Oracle Essbase Database
Administrator's Guide for details about committing data.
EssCompactOutline
Compacts an outline file that requires compacting at the server side.
Syntax
ESS_FUNC_M EssCompactOutline (hCtx);
hCtx ESS_HCTX_T API context acquired during login.
Notes
The function requires that the user is set active.
Return Value
Returns 0 if successful. After verifying that no users are performing an action, an outline-only
restructure is performed.
269
Example
#include <windows.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#pragma pack(push, api, 1)

#include <essapi.h>
#include <essotl.h>
#pragma pack(pop, api)
/* default names */
ESS_SVRNAME_T srvrName = "localhost";
ESS_USERNAME_T userName = "essexer";
ESS_PASSWORD_T pswd = "password";
ESS_APPNAME_T app = "ASOSamp";
ESS_DBNAME_T db = "Sample";
int main(int argc, char *argv[ ])

{

ESS_HINST_T hInst = NULL;
ESS_HOUTLINE_T hOutlineQuery = NULL, hOutline = NULL;
ESS_HCTX_T hCtx = NULL;
ESS_USHORT_T Items;
ESS_PAPPDB_T pAppsDbs = NULL;
ESS_INIT_T InitStruct = /* Define init */

/* structure */
{
ESS_API_VERSION, /* Version of API */
(ESS_PVOID_T)0, /* user-defined message context */
0, /* max handles */
0L, /* max buffer size */
NULL, //(ESS_STR_T)"C:\\Hyperion\\products\\Essbase\
\EssbaseServer", /* local path */
/* The following parameters use defaults */
NULL, /* message db path */
NULL, /* allocation function pointer */
NULL, /* reallocation function pointer */
NULL, /* free function pointer */
NULL, //(ESS_PFUNC_T)MessageFunc, /* error handling function
pointer */
NULL, /* path name of user-defined */
/* Application help file */
0L /* Reserved for internal use. */
/* Set to NULL */
#ifdef AD_UTF8
, ESS_API_UTF8
#endif
};
/* get appname and dbname from the argument list */

if (argc < 6) {
puts(" Usage: EssCompactOtl ServerName Userid Password AppName DbName
270
\n");
exit (0);
}
strcpy(srvrName, argv[1]);
strcpy(userName, argv[2]);
strcpy(pswd, argv[3]);
strcpy(app, argv[4]);
strcpy(db, argv[5]);
/* Initialize the Essbase API */

if ((sts = EssInit(&InitStruct, &hInst)) != ESS_STS_NOERR)
{
printf("EssInit failure: %ld\n", sts);
exit ((int) sts);
}
/* Login to Essbase */
if ((sts = EssLogin (hInst, srvrName, userName, pswd, &Items, &pAppsDbs,
&hCtx)) != ESS_STS_NOERR)
{
printf("EssLogin failure: %ld\n", sts);
exit ((int) sts);
}
if(pAppsDbs)
EssFree(hInst, pAppsDbs);
/* Select the application */

if ((sts = EssSetActive(hCtx, app, db, &Access)) != ESS_STS_NOERR)
{
printf("EssSetActive failure: %ld\n", sts);
exit ((int) sts);
}
/* compact the outline and restructure */

if ((sts = EssCompactOutline(hCtx)) != ESS_STS_NOERR)
{
printf("EssCompactOutline failure: %ld\n", sts);
exit ((int) sts);
}
/* done, logout and terminate the api */

if ((sts = EssLogout (hCtx)) != ESS_STS_NOERR)
{
printf("EssLogout failure: %ld\n", sts);
exit ((int) sts);
}
if ((sts = EssTerm(hInst)) != ESS_STS_NOERR)

{
/* error terminating API */
exit((int) sts);
}
return(0);
}
271
EssConvertApplicationtoUnicode
Create a Unicode mode application. When defined to be in Unicode mode, Essbase Server allows
the migration of non-Unicode mode applications to Unicode mode.
Syntax
ESS_FUNC_M EssConvertApplicationToUnicode(hCtx, AppName);
AppName ESS_STR_T The name of the application to be migrated. The named application must exist and not be
in Unicode mode.
Return Value
Returns 0 if successful; otherwise, returns an error.
Access
The caller must have Application Create/Delete/Edit privilege (ESS_PRIV_APPCREATE).
See Also
l EssCreateApplicationEx
EssCopyApplication
Copies an existing application, either on the client or the server, to a new application, including
all associated databases and objects.
Syntax
ESS_FUNC_M EssCopyApplication (hCtx, hSrcCtx, SrcApp, DestApp);
hSrcCtx ESS_HCTX_T Not used—should be the same as hCtx.
SrcApp ESS_STR_T Name of existing application to copy.
DestApp ESS_STR_T Name of new application. See “Application Name Limits” on page 1255.
Notes
l Copying a client application copies the local application directory and contents.
l This function can only be used to copy a client application to a new application on the client,
or a server application to a new application on the same server. Use EssCopyObject to
copy an application between different servers.
272
l The new application is not started. Call EssLoadApplication to start the newly copied
application.
Return Value
None.
Access
For a server application, the caller must have Application Create/Delete/Edit privilege
(ESS_PRIV_APPCREATE), and application designer privilege on the source application to be
copied (ESS_PRIV_APPDESIGN).
Example
ESS_FUNC_M
ESS_CopyApp(ESS_HCTX_T hCtx)
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T SrcApp;
ESS_STR_T DestApp;
hSrcCtx = hCtx;
SrcApp = "Sample";
DestApp = "NewSamp";
sts = EssCopyApplication(hCtx, hSrcCtx, SrcApp,

DestApp);
return (sts);
}
See Also
l EssCopyDatabase
l EssCopyObject
l EssLoadApplication
EssCopyDatabase
Copies an existing database, either on the client or the server, to a new database, including all
associated databases and objects. If the database is copied on the server, the new database is
started.
Syntax
ESS_FUNC_M EssCopyDatabase (hCtx, hSrcCtx, SrcApp, DestApp, SrcDb, DestDb);
SrcApp ESS_STR_T Name of source application.
273
DestApp; ESS_STR_T Name of destination application.
SrcDb; ESS_STR_T Name of existing database to copy.
DestDb ESS_STR_T Name of new database. See “Database Name Limits” on page 1256.
Notes
l Copying a client database copies the local database directory and contents.
l This function can only be used to copy a client database to another database on the client,
or a server database to another database on the same server. Use EssCopyObject to copy
a database between different servers.
Return Value
None.
Access
For a server database, the caller must have database Create/Delete/Edit privilege
(ESS_PRIV_DBCREATE), and database designer privilege on the source database to be copied
Example
ESS_FUNC_M
ESS_CopyDatabase(ESS_HCTX_T hCtx)
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T SrcApp;
ESS_STR_T DestApp;
ESS_STR_T SrcDb;
ESS_STR_T DestDb;
hSrcCtx = hCtx;
SrcApp = "Sample";
DestApp = "NewSamp";
SrcDb = "Basic";
DestDb = "NewBasic";
sts = EssCopyDatabase(hCtx, hSrcCtx, SrcApp,

DestApp, SrcDb, DestDb);
return(sts);
}
See Also
l EssCopyApplication
l EssCopyObject
274
EssCopyFilter
Copies an existing filter.
Syntax
ESS_FUNC_M EssCopyFilter (hCtx, hSrcCtx, SrcApp, DestApp, SrcDb, DestDb, SrcName,
DestName);
SrcApp ESS_STR_T Source application name.
DestApp ESS_STR_T Destination application name.
SrcDb ESS_STR_T Source database name.
DestDb ESS_STR_T Destination database name.
SrcName ESS_STR_T Source name of existing filter to be copied.
DestName ESS_STR_T Destination name of copied filter. See “Filter Name Limits” on page 1256.
Notes
l The source filter must already exist.
l To prevent overwriting an existing filter by mistake, the caller should check whether the
destination filter already exists.
Return Value
None.
Access
This function requires the caller to have database design privilege (ESS_PRIV_DBDESIGN) for
the specified database.
Example
ESS_FUNC_M
ESS_CopyFilter (ESS_HCTX_T hCtx)
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T SrcApp;
ESS_STR_T DestApp;
ESS_STR_T SrcDb;
ESS_STR_T DestDb;
ESS_STR_T SrcName;
ESS_STR_T DestName;
hSrcCtx = hCtx;
SrcApp = "Sample";
275
SrcDb = "Basic";
SrcName = "OldFilter";
DestApp = "Sample";
DestDb = "Basic";
DestName = "NewFilter";
sts = EssCopyFilter(hCtx, hSrcCtx, SrcApp,

DestApp, SrcDb, DestDb, SrcName, DestName);
if(!sts)
printf("The Filter is copied.\r\n");
return (sts);
}
See Also
l EssDeleteFilter
l EssListFilters
l EssRenameFilter
EssCopyObject
Copies an object to the server or client object system.
Syntax
ESS_FUNC_M EssCopyObject (hSrcCtx, hDestCtx, ObjType,
SrcApp, DestApp, SrcDb, DestDb, SrcObj, DestObj);
hSrcCtx ESS_HCTX_T API context handle for source object. Can be local context handle returned by
EssCreateLocalContext.
hDestCtx ESS_HCTX_T API context handle for destination object. Can be local context handle returned by
ObjType ESS_OBJTYPE_T Object type (must be single type). See “Bitmask Data Types (C)” on page 90for possible
values.
SrcApp ESS_STR_T Source application name.
DestApp ESS_STR_T Destination application name.
SrcDb ESS_STR_T Source database name. If NULL, uses the source application subdirectory.
DestDb ESS_STR_T Destination database name. If NULL, uses the destination application subdirectory.
SrcObj ESS_STR_T Name of source object to copy from.
DestObj ESS_STR_T Name of destination object to copy to. See “Object Name Limits” on page 1256.
276
Notes
l Objects may be copied from client to server, server to client, or within the same server. In
all cases the destination object must either not already exist, or it must be locked by the
caller.
l Outline objects cannot be copied. Use the EssCopyDatabase function to copy a database,
including its associated outline.
Return Value
None.
Access
This function requires the caller to have the appropriate level of access to the specified source
application and/or database containing the object (depending on the object type), and to have
Application or Database Design privilege (ESS_PRIV_APPDESIGN or ESS_PRIV_DBDESIGN)
for the specified destination application or database.
Example
ESS_FUNC_M
ESS_CopyObject(ESS_HCTX_T hCtx)
{
ESS_HCTX_T hDestCtx;
ESS_STR_T SrcApp;
ESS_STR_T DestApp;
ESS_STR_T SrcDb;
ESS_STR_T DestDb;
ESS_STR_T SrcObj;
ESS_STR_T DestObj;
hDestCtx = hCtx;
SrcApp = "Sample";
SrcDb = "Basic";
SrcObj = "Test";
DestApp = "Sample";
DestDb = "Basic";
DestObj = "NewTest";
ObjType = ESS_OBJTYPE_TEXT;
sts = EssCopyObject(hCtx,hDestCtx,ObjType,SrcApp,
DestApp,SrcDb,DestDb,SrcObj,DestObj);
if(!sts)
printf("The Object is copied.\r\n");
return (sts);
}
See Also
l EssCreateObject
l EssDeleteObject
l EssListObjects
277
l EssRenameObject
EssCreateApplication
Creates a new application, either on the client or the server. If the application is created on the
server, it is also started.
Syntax
ESS_FUNC_M EssCreateApplication (hCtx, AppName);
AppName ESS_STR_T Name of application to create. See “Application Name Limits” on page 1255.
Notes
l Creating a client application creates a directory to contain local application files.
l A newly created database or application is not automatically set to active. Call
EssSetActive after calling EssCreateDatabase or EssCreateApplication to keep
subsequent functions, such as EssRestructure, from operating on the wrong database or
application (the application or database that is already active).
l To create a Unicode mode application, use EssCreateApplicationEx.
Return Value
None.
Access
(ESS_PRIV_APPCREATE).
Example
ESS_FUNC_M
ESS_CreateApp (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
sts = EssCreateApplication (hCtx, AppName);
return(sts);
}
See Also
l EssCreateStorageTypedApplication
l EssCreateDatabase
l EssCreateObject
l EssCreateApplicationEx
278
EssCreateApplicationEx
Creates a new application, either on the client or the server. If the application is created on the
server, it is also started. This function can create Unicode mode applications.
Syntax
ESS_FUNC_M EssCreateApplicationEx(hCtx, AppName, usAppType);
usAppType The application type (Unicode or non-Unicode) of the new application.

The valid values are:
l ESS_APP_UNICODE - 0x0003—Create a Unicode application. The function fails if
the server is not in Unicode mode.
l ESS_APP_NONUNICODE - 0x0002—Create a non-Unicode application.
Notes
EssSetActive after calling EssCreateDatabaseEx or EssCreateApplicationEx to keep
Return Value
Access
See Also
l EssCreateStorageTypedApplicationEx
l EssCreateDatabaseEx
l EssCreateObject
l EssConvertApplicationtoUnicode
EssCreateDatabase
Creates a new database within an application, either on the client or the server. If the database
is created on the server, it is also started.
279
Syntax
ESS_FUNC_M EssCreateDatabase (hCtx, AppName, DbName, DbType);
AppName ESS_STR_T Name of application to contain database.
DbName ESS_STR_T Name of database to create. See “Database Name Limits” on page 1256.
DbType ESS_USHORT_T Type of database to create. Can be ESS_DBTYPE_NORMAL, or

ESS_DBTYPE_CURRENCY
Notes
l Creating a client database creates a directory to contain local database files.
EssSetActive after calling EssCreateDatabase or EssCreateApplication to keep
Return Value
None.
Access
(ESS_PRIV_DBCREATE).
Example
ESS_FUNC_M
ESS_CreateDb (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssCreateDatabase(hCtx, AppName, DbName, ESS_DBTYPE_NORMAL);

return (sts);
}
See Also
l EssCreateApplication
l EssCreateObject
280
EssCreateDatabaseEx
Creates a new database within an application, either on the client or the server. If the database
is created on the server, it is also started. This function can be used to create a database that
supports duplicate member names.
Syntax
ESS_FUNC_M EssCreateDatabaseEx (hCtx, AppName, DbName, DbType, bNonUniqueName );
AppName ESS_STR_T Name of application to contain database.
DbName ESS_STR_T Name of database to create. See “Database Name Limits” on page 1256.
DbType ESS_USHORT_T Type of database to create. Can be ESS_DBTYPE_NORMAL, or

ESS_DBTYPE_CURRENCY
bNonUniqueName ESS_BOOL_T When set to TRUE, this function creates a database that has a duplicate-
member-name support-enabled outline. If set to FALSE, the functionality is
the same as for EssCreateDatabase.
Notes
l Creating a client database creates a directory to contain local database files.
EssSetActive after calling EssCreateDatabase, EssCreateDatabaseEx, or
EssCreateApplication to keep subsequent functions, such as EssRestructure, from operating
on the wrong database or application (the application or database that is already active).
Return Value
Access
Example
ESS_FUNC_M ESS_CreateDb()
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssCreateDatabaseEx(hCtx, AppName, DbName, ESS_DBTYPE_NORMAL, TRUE);
return (sts);
281
See Also
l EssCreateDatabase
l EssCreateObject
EssCreateDrillThruURL
Creates a drill-through URL, with the given link and name, within the active database outline.
Syntax
ESS_FUNC_M EssCreateDrillThruURL (hCtx, pUrl);
pUrl ESS_PDURLINFO_T URL definition.
Return Value
l If successful, creates a drill-through URL in the active database outline.
l If unsuccessful, returns an error code.
Access
l Caller must have database Design privilege (ESS_PRIV_DBDESIGN) for the specified
database.
l Caller must have selected the specified database as the active database using EssSetActive().
Example
/* Sample Code for EssCreateDrillThruURL */

ESS_DURLINFO_T url;
ESS_USHORT_T usCountOfURLs, i;
ESS_PDURLINFO_T listOfURLs;
ESS_STR_T urlName = "";
ESS_PDURLINFO_T urlInfo;
ESS_STR_T fileName = "";
ESS_CHAR_T xmlString[XML_CHAR_MAX];
/* Valid case */
memset(&url, '\0', sizeof(ESS_DURLINFO_T));

fileName = "F:\\testarea\\mainapi\\sample1.xml";
GetFileContent(fileName, xmlString);
printf("\nValid case:\n");
url.bIsLevel0 = ESS_TRUE;
url.cpURLName = "Drill Through to EPMI";
282
url.cpURLXml = xmlString;
url.iURLXmlSize = (ESS_SHORT_T) strlen(xmlString)+1;
url.iCountOfDrillRegions = 2;
sts = EssAlloc (hInst, sizeof(ESS_STR_T) * url.iCountOfDrillRegions,
&(url.cppDrillRegions));
url.cppDrillRegions[0] = "@idesc(\"Qtr1\")";
url.cppDrillRegions[1] = "@idesc(\"Qtr2\")";
sts = EssCreateDrillThruURL(hCtx, &url);
printf("EssCreateDrillThruURL sts: %ld\n",sts);
EssCreateExtGroup
Creates a group in the external user directory.
Syntax
ESS_FUNC_M EssCreateExtGroup (hCtx, GroupName);
GroupName ESS_STR_T Name of group to create (input). See “Group Name Limits” on page 1256.
Notes
The specified group must exist in Shared Services.
Return Value
None.
Access
Example
ESS_FUNC_M ESS_CreateGroup (ESS_HCTX_T hCtx)
{
GroupName = "Group 1";
sts = EssCreateExtGroup (hCtx, GroupName);
return (sts);
}
See Also
l EssDeleteUser
l EssListUsers
l EssRenameUser
l EssSetPassword
283
l EssSetUser
l EssGetUserEx
l “ESS_USERINFOEX_T” on page 189
EssCreateExtUser
Creates a new externally authenticated user.
Syntax
ESS_FUNC_M EssCreateExtUser (hCtx, UserName, Password, SecurityProvider,
ProviderConnectionParameters);
UserName ESS_STR_T Name of user to create. See “User Name Limits” on page
1256.
Password ESS_STR_T Security password for new user. See “Password Limits” on
page 1256.
Note: The Password parameter has been made redundant

by changes for Shared Services. You can use an empty
string for this parameter.
SecurityProvider ESS_PROTOCOL_T The name of the external authentication mechanism.
ProviderConnectionParameters ESS_CONNPARAM_T Parameters used by the external authentication mechanism,

if any.
Notes
l The specified user must not already exist.
l The user's access level and other parameters may be set with the EssSetUser function.
l Your program should ensure that the password has been entered correctly (e.g. by requiring
the user to type it twice) before calling this function. Once entered, it is not possible to
retrieve a password. However, a password can be changed using the EssSetPassword
function.
Return Value
None.
Access
Example
ESS_FUNC_M ESS_CreateUser (ESS_HCTX_T hCtx)
{
284
ESS_STR_T UserName;
ESS_STR_T Password;
ESS_PROTOCOL_T Protocol;
ESS_CONN_PARAM ConnParam;

Password = "Password";
Protocol = CSS;
ConnParam = NULL;
sts = EssCreateExtUser (hCtx, UserName, Password, Protocol, ConnParam);
return (sts);
}
See Also
l EssDeleteUser
l EssListUsers
l EssRenameUser
l EssSetPassword
l EssSetUser
l EssGetUserEx
EssCreateFilter
Creates a new filter and starts setting its contents.
Syntax
ESS_FUNC_M EssCreateFilter (hCtx, AppName, DbName, FilterName, Active, Access);
AppName ESS_STR_T Application name.
DbName ESS_STR_T Database name.
FilterName ESS_STR_T Filter name. See “Filter Name Limits” on page 1256.
Active ESS_BOOL_T Filter active flag. If TRUE, the filter is set active; otherwise, it is set inactive.
Access ESS_ACCESS_T The default filter access level.
Notes
l If the filter does not already exist, it will be created by this call.
l If the filter already exists, an error message is returned.
l This call must be followed by successive calls to EssSetFilterRow to set all the rows for
the filter.
285
Return Value
None.
Access
This function requires the caller to have database designer permission (ESS_PRIV_DBDESIGN)
for the specified database.
Example
ESS_FUNC_M
ESS_CreateFilter (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FilterName;
ESS_BOOL_T Active;
ESS_ACCESS_T Access, AccessAry[3];
ESS_STR_T RowString[3];
ESS_USHORT_T ind;
AppName = "Sample";
DbName = "Basic";
FilterName = "NewFilter";
Active = ESS_TRUE;
/***** Create Filter *****/

sts = EssCreateFilter(hCtx, AppName, DbName,
FilterName, Active, Access);
if(!sts)
{
RowString[0] = "@IDESCENDANTS(Scenario)";
RowString[1] = "@IDESCENDANTS(Product)";
RowString[2] = "Qtr1, @IDESCENDANTS(\"Colas\")";
AccessAry[0] = ESS_ACCESS_READ;
AccessAry[1] = ESS_ACCESS_NONE;
AccessAry[2] = ESS_ACCESS_WRITE;
/***** Set Filter Rows *****/
for(ind = 0; ind < 3; ind++)

{
sts = EssSetFilterRow(hCtx, RowString[ind],
AccessAry[ind]);
if(sts)
printf("Cannot set Filter row %s\r\n",
RowString[ind]);
}
sts = EssSetFilterRow(hCtx,
"",ESS_ACCESS_NONE);
}
return (sts);
}
286
See Also
l EssGetFilter
l EssListFilters
l EssSetFilterRow
l EssSetFilter
EssCreateGroup
Creates a new group.
Syntax
ESS_FUNC_M EssCreateGroup (hCtx, GroupName);
GroupName ESS_STR_T Name of group to create. See “Group Name Limits” on page 1256.
Notes
l The specified group must not already exist.
l The group's access level may be set with the EssSetGroup function.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_CreateGroup (ESS_HCTX_T hCtx)
{
sts = EssCreateGroup (hCtx, GroupName);
return (sts);
}
See Also
l EssCreateExtGroup
l EssDeleteGroup
l EssListGroups
l EssRenameGroup
287
l EssSetGroup
EssCreateLocalContext
Creates a local API context for use in local API operations.
Syntax
ESS_FUNC_M EssCreateLocalContext (hInstance, UserName, Password, phLocalCtx);
hInstance; ESS_HINST_T API instance handle.
UserName; ESS_STR_T Currently not used—should be NULL.
Password; ESS_STR_T Currently not used—should be NULL.
phLocalCtx; ESS_PHCTX_T Address of variable to receive Essbase local context handle.
Notes
l This function must be called if access to local API operations (for example local file/object
functions) is desired. It should be called after calling EssInit.
l It is only necessary to call the function once per client application - the context handle can
be used for all local API operations.
l You should call EssDeleteLocalContext when the application has finished accessing
local objects.
Return Value
If successful, a valid local context handle is returned in phLocalCtx.
Access
Example
See the example of EssGetLocalPath.
See Also
l EssDeleteLocalContext
l EssInit
EssCreateLocationAlias
Creates a new location alias; that is, it maps an alias name string to an ordered set of the following
five strings: host name, application name, database name, user login name, and user password.
288
Syntax
ESS_FUNC_M EssCreateLocationAlias (hCtx, pAlias, pHost, pApp, pDb, pName, pPassword);
pAlias; ESS_STR_T Location alias.
pHost; ESS_STR_T Target host.
pApp; ESS_STR_T Target application.
pDb; ESS_STR_T Target database.
pName; ESS_STR_T User login name.
pPassword; ESS_STR_T User password.
Return Value
Returns an error if a location alias with the name pAlias already exists.
See Also
l EssDeleteLocationAlias
l EssGetLocationAliasList
EssCreateObject
Creates a new object on the server or client object system.
Syntax
ESS_FUNC_M EssCreateObject (hCtx, ObjType, AppName, DbName, ObjName);
hCtx ESS_HCTX_T API context handle. Can be local context handle returned by
ObjType ESS_OBJTYPE_T Object type (must be single type). Refer to “Bitmask Data Types (C)” on page 90 for a
list of possible values.
DbName ESS_STR_T Database name. If NULL, uses the Application subdirectory.
ObjName ESS_STR_T Name of object to create. See “Object Name Limits” on page 1256.
Notes
l To create an object, it must not already exist.
289
l A newly created object on the server contains no data and merely acts as a place holder to
prevent another user from creating the object. If you wish to update the created object, you
should lock it using EssLockObject, then save it using EssPutObject.
Return Value
None.
Access
This function requires the caller to have Application or Database Design privilege
(ESS_PRIV_APPDESIGN or ESS_PRIV_DBDESIGN) for the specified application or database
to contain the object.
Example
ESS_FUNC_M
ESS_CreateObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T ObjName;
AppName = "Sample";
DbName = "Basic";
ObjName = "Test";
ObjType = ESS_OBJTYPE_OUTLINE;
sts = EssCreateObject(hCtx, ObjType, AppName,

DbName, ObjName);
if(!sts)
printf("The Object is created.\r\n");
return (sts);
}
See Also
l EssCopyObject
l EssDeleteObject
l EssListObjects
l EssLockObject
l EssPutObject
l EssRenameObject
EssCreateStorageTypedApplication
Creates a new application with the option of data storage mode: block (multidimensional) or
aggregate.
Syntax
ESS_FUNC_M EssCreateStorageTypedApplication (hCtx, AppName, StorageType);
290
StorageType ESS_DATA_STORAGE_T The data storage type of the new application.

The valid values for StorageType are:
l ESS_DEFAULT_DATA_STORAGE—Same as
ESS_MULTIDIM_DATA_STORAGE
l ESS_MULTIDIM_DATA_STORAGE—Block storage
(multidimensional), the default storage type
l ESS_ASO_DATA_STORAGE—Aggregate storage
Notes
l The new application is created in non-Unicode mode.
EssSetActive after calling any function that creates an application or database to keep
Return Value
Access
Example
ESS_FUNC_M
ESS_CreateASOApp (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
sts = EssCreateStorageTypedApplication (hCtx, AppName, ESS_ASO_DATA_STORAGE);
return(sts);
}
See Also
l EssCreateStorageTypedApplicationEx
l EssCreateDatabase
l EssCreateObject
291
EssCreateStorageTypedApplicationEx
Creates a new application with options for data storage mode (block or aggregate) and
application mode (Unicode or non-Unicode).
Syntax
ESS_FUNC_M EssCreateStorageTypedApplicationEx (hCtx, AppName, storageType, usAppType);
StorageType ESS_DATA_STORAGE_T The data storage type of the new application.

The valid values for StorageType are:
l ESS_DEFAULT_DATA_STORAGE—Same as
ESS_MULTIDIM_DATA_STORAGE
l ESS_MULTIDIM_DATA_STORAGE—Block storage
(multidimensional), the default storage type
l ESS_ASO_DATA_STORAGE—Aggregate storage
usAppType ESS_USHORT_T The application type (Unicode or non-Unicode) of the new application.
The valid values for usAppType are:
l ESS_APP_UNICODE - 0x0003—Unicode application. The function
fails if the server is not in Unicode mode.
l ESS_APP_NONUNICODE - 0x0002—Non-Unicode application.
Notes
EssSetActive after calling any function that creates an application or database to keep
Return Value
Access
Example
ESS_FUNC_M
ESS_CreateASOApp (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
292
sts = EssCreateStorageTypedApplicationEx (hCtx, AppName,ESS_ASO_DATA_STORAGE,
ESS_APP_UNICODE);
return(sts);
}
See Also
l EssCreateStorageTypedApplication
l EssCreateDatabase
l EssCreateObject
EssCreateUser
Creates a new user.
Syntax
ESS_FUNC_M EssCreateUser (hCtx, UserName, Password);
UserName ESS_STR_T Name of user to create. See “User Name Limits” on page 1256.
Password ESS_STR_T Security password for new user. See “Password Limits” on page 1256.
Notes
l The specified user must not already exist.
l The user's access level and other parameters may be set with the EssSetUser function.
l Your program should ensure that the password has been entered correctly (for example, by
requiring the user to type it twice) before calling this function. Once entered, it is not possible
to retrieve a password. However, a password can be changed using the EssSetPassword
function.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_CreateUser (ESS_HCTX_T hCtx)
{
ESS_STR_T UserName;
ESS_STR_T Password;
293
sts = EssCreateUser (hCtx, UserName, Password);
return (sts);
}
See Also
l EssDeleteUser
l EssListUsers
l EssRenameUser
l EssSetPassword
l EssSetUser
EssCreateVariable
Creates a new substitution variable or modifies an existing substitution variable if the variable
name already exists with the identical server, application, and database values.
Syntax
ESS_FUNC_M EssCreateVariable (hCtx, pVariable);
pVariable ESS_PVARIABLE_T Pointer to the structure containing the description of the substitution variable being
created.
Notes
l The scope of the variable can apply to the server, the application, or the database. The scope
is controlled through the ESS_VARIABLE_T structure. When the server, application, and
database are all named, the substitution variable applies only to the specified database. When
only the server and application are named, the substitution variable applies to all databases
in the specified application. When only the server is named, the substitution variable applies
to all applications and databases on the specified server.
l When a variable exists and a new variable is created with the same name and scope, the new
value replaces the old value with no error message from Essbase.
l On a given server, you can create multiple substitution variables with the same name but
different scopes (application and database).
Return Value
If successful, returns zero.
294
Example
/*
** ESS_CreateVariable() creates a substitution variable using
** the API EssCreateVariable, and sets its value.
*/
ESS_FUNC_M
ESS_CreateVariable (ESS_HCTX_T hCtx)
{
ESS_VARIABLE_T Variable;
printf("\n ******************************************");
printf("\n **** An example of using EssCreateVariable");
printf("\n ******************************************");
/* Create Variable 'QuarterName' at the level of the server/App/Db */
strcpy(Variable.VarName, "QuarterName");
strcpy(Variable.Server, "Local");
strcpy(Variable.AppName, "Sample");
strcpy(Variable.DbName, "Basic");
strcpy(Variable.VarValue, "Qtr1");
sts = EssCreateVariable(hCtx, &Variable);
printf("\n Variable 'QuarterName' is created at the Server/App/Db level
with value 'Qtr1'");
/* Change Value of 'QuarterName' from Qtr1 to Qtr2 */

{
strcpy(Variable.VarValue, "Qtr2");
printf("\n Variable 'QuarterName' at the Server/App/Db level is updated
to value 'Qtr2'");
}
/* Create Variable 'MarketName' at the level of the Server/App */
{
strcpy(Variable.VarName, "MarketName");
strcpy(Variable.DbName, "");
strcpy(Variable.VarValue, "East");
printf("\n Variable 'MarketName' is created at the Server/App level");
}
/* Create Variable "MarketName' at the level of the Server */
/* This shows that you can have the same variable name at different levels*/
{
strcpy(Variable.AppName, "");
295
strcpy(Variable.VarValue, "Market");
printf("\n Variable 'MarketName' is created at the Server level");
}
printf("\n --> No Errors in EssCreateVariable\n\n\n");
else
printf("\n --> Error in EssCreateVariable number: %d\n\n\n", sts);
return (sts);
} /* end ESS_CreateVariable */
Output
******************************************
**** An example of using EssCreateVariable
******************************************
Variable 'QuarterName' is created at the Server/App/Db level with value 'Qtr1'
Variable 'QuarterName' at the Server/App/Db level is updated to value 'Qtr2'
Variable 'MarketName' is created at the Server/App level
Variable 'MarketName' is created at the Server level
--> No Errors in EssCreateVariable
See Also
l “ESS_VARIABLE_T” on page 191
l EssDeleteVariable
l EssGetVariable
l EssListVariables
EssDefaultCalc
Executes the default calculation for the active database.
Syntax
ESS_FUNC_M EssDefaultCalc (hCtx);
Notes
asynchronous process after the return from this call . The caller must check at regular
intervals to see whether the process has completed by calling EssGetProcessState until
it returns ESS_STATE_DONE.
l To get and set the default calc script, use the functions EssGetDefaultCalc,
EssSetDefaultCalc, and EssSetDefaultCalcFile.
296
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_CalcDefault (ESS_HCTX_T hCtx)
{
sts = EssDefaultCalc(hCtx);
if (!sts)
{
ESS_STATE_DONE))
sts = EssGetProcessState (hCtx,
&pState);
}
return (sts);
}
See Also
l EssBeginCalc
l EssCalc
l EssGetDefaultCalc
l EssSetDefaultCalc
EssDeleteAllSplFiles
Deletes all trigger log files for a database.
Syntax
ESS_FUNC_M EssDeleteAllSplFiles (hCtx, AppName, DbName);
297
Access
This function requires the caller to have database Design privilege (ESS_PRIV_DBDESIGN) for
See Also
l EssDisplayTriggers
l EssListSpoolFiles
l EssGetSpoolFile
l EssDeleteSplFile
l EssMdxTrig
EssDeleteApplication
Deletes an existing application, either on the client or the server. If the application is running
on the server, then it is first stopped.
Syntax
ESS_FUNC_M EssDeleteApplication (hCtx, AppName);
AppName ESS_STR_T Name of application to delete.
Notes
Deleting a client application removes the local application directory and contents. It also removes
all objects stored with the application, including all databases.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_DeleteApp (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
sts = EssDeleteApplication (hCtx, AppName);
return(sts);
}
298
See Also
l EssDeleteDatabase
l EssDeleteObject
EssDeleteDatabase
Deletes an existing database from an application, either on the client or the server. If the database
is running on the server, then it is first stopped.
Syntax
ESS_FUNC_M EssDeleteDatabase (hCtx, AppName, DbName);
AppName ESS_STR_T Name of application containing database.
DbName ESS_STR_T Name of database to delete.
Notes
l Deleting a client database removes the local database directory and contents.
l Deleting a server database removes all objects associated with that database.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_DeleteDb (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
/* IF the current active is the same as the

* unload db, ClearActive first */
/* ELSE */
sts = EssDeleteDatabase(hCtx, AppName,
DbName);
return (sts);
}
299
See Also
l EssDeleteApplication
l EssDeleteObject
EssDeleteDrillThruURL
Deletes a drill-through URL, with the given URL name, within the active database outline.
Syntax
ESS_FUNC_M EssDeleteDrillThruURL (hCtx, URLName);
URLName ESS_STR_T Drill-through URL name.
Return Value
l If successful, deletes the named drill-through URL in the active database outline.
Access
l Caller must have database Design privilege (ESS_PRIV_DBDESIGN) for the specified
database.
l Caller must have selected the specified database as the active database using
EssSetActive.
Example
sts = EssDeleteDrillThruURL(hCtx, "Drill Through to EPMI");

printf("EssDeleteDrillThruURL sts: %ld\n",sts);
EssDeleteFilter
Deletes an existing filter.
Syntax
ESS_FUNC_M EssDeleteFilter (hCtx, AppName, DbName, FilterName);
300
FilterName ESS_STR_T Filter name.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_DeleteFilter (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
FilterName = "Test";
sts = EssDeleteFilter(hCtx, AppName, DbName,

FilterName);
return (sts);
}
See Also
l EssCopyFilter
l EssListFilters
l EssRenameFilter
l EssSetFilter
EssDeleteFromGroup
Removes a user from the list of group members.
Syntax
ESS_FUNC_M EssDeleteFromGroup (hCtx, GroupName, UserName);
UserName ESS_STR_T Name of user to remove from group list.
301
Notes
In addition to deleting the specified user from the list of members for the specified group, this
function also deletes the group from the user's own list of associated groups.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_RemoveUser (ESS_HCTX_T hCtx)
{
ESS_STR_T UserName;
sts = EssDeleteFromGroup (hCtx, GroupName, UserName);
return (sts);
}
See Also
l EssAddToGroup
l EssGetGroupList
l EssListGroups
l EssSetGroupList
EssDeleteFromGroupEx
Removes a user from a group. Similar to EssDeleteFromGroup, but can accept a user directory
specification or unique identity attribute for GroupId or UserId.
Syntax
ESS_FUNC_M EssDeleteFromGroupEx (hCtx, GroupId, bIsGroupId, UserId, bUsingIdentity);
GroupId ESS_STR_T Group name or identity (input). Can be specified as groupname@provider or as

bIsGroupId ESS_BOOL_T Input. Indicates if GroupId is a name or an identity. If TRUE, GroupId is an identity.
302
UserId ESS_STR_T Name of user to remove from group (input). Can be specified as
username@provider or as a unique identity attribute.
bUsingIdentity ESS_BOOL_T Input. Indicates if UserID is a name or an identity. If TRUE, UserID is an identity.
Notes
In addition to deleting the specified user from the list of members for the specified group, this
function also deletes the group from the user's own list of associated groups.
Return Value
None.
Access
Example

{
ESS_USHORT_T i;

{
if (UserList [i])
}
}
ESS_FUNC_M ESS_RemoveUser (ESS_HCTX_T hCtx)

{
ESS_STR_T groupId, userId;
ESS_BOOL_T bGroupId, bUserId;
ESS_USHORT_T type;
ESS_USHORT_T count;
groupId = "IDRegularGroup@ldap";
userId = "IDUser8@ldap";
bGroupId = ESS_FALSE;
bUserId = ESS_TRUE;
sts = EssDeleteFromGroupEx (hCtx, groupId, bGroupId, userId, bUserId);
printf("EssDeleteFromGroupEx sts: %ld\n", sts);
if(!sts)
{
&pUserList);
if(!sts)
303
{
if(pUserList)
{
}
else
}
}
return (sts);
}
See Also
l EssAddToGroupEx
l EssGetGroupListEx
EssDeleteGroup
Deletes an existing group.
Syntax
ESS_FUNC_M EssDeleteGroup (hCtx, GroupName);
GroupName ESS_STR_T Name of group to delete.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_DeleteGroup (ESS_HCTX_T hCtx)
{
sts = EssDeleteGroup (hCtx, GroupName);
return (sts);
}
304
See Also
l EssDeleteGroupEx
l EssCreateGroup
l EssListGroups
l EssRenameGroup
EssDeleteGroupEx
Deletes an existing group. Similar to EssDeleteGroup, but can accept a user directory
specification or unique identity attribute for GroupID.
Syntax
ESS_FUNC_M EssDeleteGroupEx (hCtx, GroupId, bisIdentity );
GroupId ESS_STR_T Name of group to delete (input). Can be specified as groupname@provider or as a

bIsIdentity ESS_BOOL_T Input. Indicates if GroupId is a name or an identity. If TRUE, GroupId is an identity.
Return Value
None.
Access
Example
ESS_FUNC_M ESS_DeleteGroupEx (ESS_HCTX_T hCtx)

{
ESS_STR_T groupId;
ESS_BOOL_T bIsIdentity;
groupId = "IDTempGroup1@ldap";
bIsIdentity = ESS_FALSE;
sts = EssDeleteGroupEx(hCtx, groupId, bIsIdentity);
printf("EssDeleteGroupEx sts: %ld\n", sts);
return (sts);
}
See Also
l EssDeleteUserEx
305
EssDeleteLocalContext
Releases a local context previously created by EssCreateLocalContext.
Syntax
ESS_FUNC_M EssDeleteLocalContext (hLocalCtx);
hLocalCtx ESS_HCTX_T API local context handle.
Notes
This function should only be used for local contexts. For login contexts, use the EssLogout
function.
Return Value
None.
Access
Example
See the example of EssGetLocalPath.
See Also
l EssCreateLocalContext
l EssLogout
l EssTerm
EssDeleteLocationAlias
Deletes an existing location alias.
Syntax
ESS_FUNC_M EssDeleteLocationAlias (hCtx, pAlias);
pAlias; ESS_STR_T Location alias.
Return Value
Returns an error if a location alias with the name pAlias is not found.
See Also
l EssCreateLocationAlias
306
l EssGetLocationAliasList
EssDeleteLogFile
Deletes an application log file or the Essbase Server log file (essbase.log) on the server.
Syntax
ESS_FUNC_M EssDeleteLogFile (hCtx, AppName);
AppName ESS_STR_T Application name or NULL. If NULL, this function deletes the Essbase Server log file
(essbase.log).
Notes
l Use EssGetLogFile to view message logs.
l For the location of essbase.log, see the Oracle Essbase Database Administrator's Guide.
Return Value
None.
Access
The caller must have Application Designer privilege (ESS_PRIV_APPDESIGN) for the specified
application.
Example
ESS_FUNC_M
ESS_DeleteLogFile (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
sts = EssDeleteLogFile (hCtx, AppName);

return(sts);
}
EssDeleteLogFile ("") //Deletes Agent log file.
See Also
l EssGetLogFile
l EssLogSize
l EssWriteToLogFile
EssDeleteObject
Deletes an existing object.
307
Syntax
ESS_FUNC_M EssDeleteObject (hCtx, ObjType, AppName, DbName, ObjName);
ObjType ESS_OBJTYPE_T Object type (must be single type).
DbName ESS_STR_T Database name. If NULL, uses the application subdirectory.
ObjName ESS_STR_T Object name to delete.
Notes
l To delete an object, the object must not be locked.
l Outline objects cannot be deleted. Use the EssDeleteDatabase function to delete a
database, including its associated outline.
Return Value
None.
Access
containing the object.
Example
ESS_FUNC_M
ESS_DeleteObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T ObjName;
AppName = "Sample";
DbName = "Basic";
ObjName = "Test";
sts = EssDeleteObject(hCtx, ObjType, AppName,
DbName, ObjName);
return (sts);
}
See Also
l EssCreateObject
l EssListObjects
308
EssDeleteSplFile
Deletes a specific trigger logfile for a database.
Syntax
ESS_FUNC_M EssDeleteSplFile (hCtx, AppName, DbName, SplName);
DbName ESS_STR_T databasename.
SplName ESS_STR_T The name of the spool file to delete.
Access
See Also
l EssListSpoolFiles
l EssGetSpoolFile
l EssDeleteAllSplFiles
l EssMdxTrig
EssDeleteUser
Deletes a user.
Syntax
ESS_FUNC_M EssDeleteUser (hCtx, UserName);
UserName ESS_STR_T Name of user to delete.
Notes
The caller may not delete itself nor the last Administrator on the server.
Return Value
None.
309
Access
Example
ESS_FUNC_M
ESS_DeleteUser (ESS_HCTX_T hCtx)
{
ESS_STR_T UserName;
sts = EssDeleteUser (hCtx, UserName);
return (sts);
}
See Also
l EssDeleteUserEx
l EssCreateExtUser
l EssCreateUser
l EssListUsers
l EssRenameUser
EssDeleteUserEx
Deletes a user. Similar to EssDeleteUser, but can accept a user directory specification or
Syntax
ESS_FUNC_M EssDeleteUserEx (hCtx, UserId, bIsIdentity);
hCtx ESS_HCTX_T Context handle (input).
UserId ESS_STR_T Name of user to delete (input). Can be specified as username@provider or as a unique
identity attribute.
bIsIdentity ESS_BOOL_T Input. Indicates if UserId is a name or an identity. If TRUE, UserId is an identity.
Notes
The caller may not delete itself nor the last Administrator on the server.
Return Value
None.
310
Access
Example
ESS_FUNC_M ESS_DeleteUserEx (ESS_HCTX_T hCtx)

{
ESS_STR_T userId;
userId = "IDUser3@ldap";
sts = EssDeleteUserEx(hCtx, userId, bIsIdentity);
printf("EssDeleteUserEx sts: %ld\n", sts);
return (sts);
}
See Also
l EssDeleteGroupEx
EssDeleteVariable
Deletes a substitution variable.
Syntax
ESS_FUNC_M EssDeleteVariable (hCtx, pVariable);
hCtx ESS_HCTX_T Context handle to the API.
pVariable “ESS_VARIABLE_T” on page 191 The pointer to the structure containing the description of the
substitution variable being deleted.
Return Value
Example
/*
** ESS_DeleteVariable() deletes a substitution variable using
** the API EssDeleteVariable.
*/
ESS_FUNC_M
ESS_DeleteVariable (ESS_HCTX_T hCtx)
{
ESS_PVARIABLE_T pVariables;
311
ESS_ULONG_T ulCount, i;
printf("\n ******************************************");
printf("\n **** An example of using EssDeleteVariable");
printf("\n ******************************************");
sts = EssDeleteVariable(hCtx, &Variable);
printf("\n Variable 'QuarterName' at the Server/App/Db level is deleted");
{
printf("\n Variable 'MarketName' at the Server/App level is deleted");
}
{
printf("\n Variable 'MarketName' at the Server level is deleted");
}
/*********************************************************/
/* List the variables at the level of the Server/App/Db- */
/* We should not have any */
/*********************************************************/
{
strcpy(Variable.Server, "local");
sts = EssListVariables(hCtx, &Variable, &ulCount, &pVariables);
{
printf("\n--- Number of Substitution Variables at the Server, App and Db
level is: %ld\n", ulCount);
for (i = 0; i < ulCount; i++)
{
printf("Variable name : %s\n", pVariables[i].VarName);
printf("Server name : %s\n", pVariables[i].Server);
printf("Application name : %s\n", pVariables[i].AppName);
printf("Database name : %s\n", pVariables[i].DbName);
printf("Variable value : %s\n\n", pVariables[i].VarValue);
}
}
312
}
/*********************************************************/
/* List the variables - at the level of the App */
/*********************************************************/
{
{
printf("\n--- Number of Substitution Variables at the Server and App
{
}
}
}
/*********************************************************/
/* List variables at the server level */
/*********************************************************/
{
{
printf("\n--- Number of Substitution Variables at the Server level is:
%ld\n", ulCount);
{
}
}
}
printf("\n --> No Errors in EssDeleteVariable\n\n\n");
else
printf("\n --> Error in EssDeleteVariable number: %d\n\n\n", sts);
return (sts);
} /* end ESS_DeleteVariable */
Output
313
******************************************
**** An example of using EssDeleteVariable
******************************************
Variable 'QuarterName' at the Server/App/Db level is deleted
Variable 'MarketName' at the Server/App level is deleted
Variable 'MarketName' at the Server level is deleted
--- Number of Substitution Variables at the Server, App and Db level is: 0
--- Number of Substitution Variables at the Server and App level is: 0
--- Number of Substitution Variables at the Server level is: 0
--> No Errors in EssDeleteVariable
See Also
l EssCreateVariable
l EssGetVariable
l EssListVariables
EssDisplayAlias
Dumps the contents of an alias table in the active database.
Syntax
ESS_FUNC_M EssDisplayAlias (hCtx, AliasName, pCount, ppAliases);
AliasName ESS_STR_T Name of alias table.
pCount ESS_PUSHORT_T Address of variable to receive count of aliases.
ppAliases “ESS_MBRALT_T” on page 142 Address of pointer to receive member alias table.
Notes
The memory allocated for ppAliases should be freed using EssFree.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_DisplayAlias (ESS_HCTX_T hCtx)
{
ESS_USHORT_T Count;
ESS_USHORT_T ind;
314
ESS_PMBRALT_T Altlist;
ESS_STR_T AltName;
AltName = "TestAlias";
sts = EssDisplayAlias (hCtx, AltName, &Count, &Altlist);

if (Count)
{
printf ("\r\n-----Alias Contents-----\r\n\r\n");
for (ind = 0; ind < Count; ind++)

{
printf ("%s==>%s\r\n",
Altlist [ind].MbrName, Altlist [ind].AltName);
}
printf ("\r\n");
}
return (sts);
}
See Also
l EssListAliases
EssDisplayTriggers
Lists all triggers for a database.
Syntax
ESS_FUNC_M EssDisplayTriggers (hCtx, AppName, DbName, pszTrg, pCount, ppTriggerList);
DbName ESS_STR_T database name
pszTrg ESS_STR_T The name of the specific trigger to return information for. If pszTrg is
"" (empty string), then all triggers in the specified database are returned.
pCount ESS_PUSHORT_T Address of the variable to receive the number of triggers for which
information is returned.
ppTriggerList ESS_PPTRIGGERINFO_T Address of pointer to receive an allocated array of trigger information

structures. The trigger information structure includes each trigger name,
the trigger definition, and a boolean field indicating whether the trigger is
enabled.
Notes
The memory allocated for ppTriggerList should be freed using EssFree.
315
Return Value
If successful, returns the count of trigger in the database in pCount, and an array of trigger names
in ppTriggerList.
Access
See Also
l EssListSpoolFiles
l EssGetSpoolFile
l EssDeleteSplFile
l EssMdxTrig
EssDTAPIClose
Ends the drill-through session.
Syntax
ESS_FUNC_M EssDTAPIClose (pDTAPIInst);
pDTAPIInst; ESS_PDTAPIHINST_T Initialized drill-through instance handle for the given range of data cells
Notes
l This function closes the drill-through session, but does not free up memory.
l EssDTAPIExit closes the drill-through session and frees up memory.
See Also
l Chapter 6, “Using the C Main API”
l “C Main API Structures” on page 108
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
316
EssDTAPIConnect
Establishes a connection to Essbase Studio for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTAPIConnect (pDTAPIInst);
pDTAPIInst; ESS_DTAPIHINST_T Initialized drill-through instance handle for the given range of data cells
See Also
l EssDTAPIClose
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIExecuteReport
Executes the drill-through report identified by its index to an array of report definition
structures.
Syntax
ESS_FUNC_M EssDTAPIExecuteReport (pDTAPIInst, index);
pDTAPIInst; ESS_PDTAPIHINST_T Initialized drill-through instance handle for the given range of data cells
index; ESS_ULONG_T Index of the report to be executed
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
317
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIExit
Ends the drill-through session, and frees up memory for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTAPIExit (pDTAPIInst);
pDTAPIInst; ESS_PDTAPIHINST_T Initialized drill-through instance handle for the given range of data cells.
Notes
l This function closes the drill-through session, and frees up memory.
l EssDTAPIClose closes the drill-through session, but does not free up memory.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIGetColumns
Retrieves an array of report header information structures for the given drill-through instance
handle.
Syntax
ESS_FUNC_M EssDTAPIGetColumns (pDTAPIInst, ppCol, pulCount);
318
pDTAPIInst; ESS_DTAPIHINST_T Initialized drill-through instance handle for the given range of
data cells.
ppCol; “ESS_DTAPIHEADER_T” on page An array of report header structures for the given columns.
129
pulCount; ESS_PULONG_T Number of data blocks in the ppCol report header information
array.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIGetData
Retrieves an array of report data structures for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTAPIGetData (pDTAPIInst, ppData, pulRowCount, pulColCount);
pDTAPIInst; ESS_DTAPIHINST_T Initialized drill-through instance handle for the given range of data
cells.
ppData; “ESS_DTAPIDATA_T” on page An array of report data structures for the given data cells.
129
pulRowCount; ESS_PULONG_T Number of rows for the data blocks in the ppData report data array.
pulColCount; ESS_PULONG_T Number of columns for the data blocks in the ppData report data
array.
See Also
l EssDTAPIClose
319
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIGetError
Retrieves the error status and message.
Syntax
ESS_FUNC_M EssDTAPIGetError (pDTAPIInst, ppData, pMsg, ulCount);
pDTAPIInst; ESS_DTAPIHINST_T Initialized drill-through instance handle for the given range of data cells.
ppData; ESS_STS_T Error status.
pMsg; ESS_PSTR_T Error message.
ulCount; ESS_ULONG_T Size of the error message buffer.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIGetInfo
Retrieves drill-through connection information for a given drill-through handle.
320
Syntax
ESS_FUNC_M EssDTAPIGetInfo (pDTAPIInst, pDTInfo);
pDTAPIInst; ESS_PDTAPIHINST_T Initialized drill-through instance handle for the given range of data
cells
pDTInfo; “ESS_DTAPIINFO_T” on page 129 Pointer to a structure of connection information for a given range
of data cells
Notes
l Allocate memory for ESS_DTAPIINFO_T before you call this function.
l sPassword is not returned in pDTInfo; that is, the sPassword field in ESS_DTAPIINFO_T is
not returned.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIGetReports
Returns the list of reports for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTAPIGetReports (pDTAPIInst, ppReports, pulCount);
pDTAPIInst; ESS_DTAPIHINST_T Initialized drill-through instance handle for the given range of
data cells.
ppReports; “ESS_DTAPIREPORT_T” on page 130 Pointer to an array of report definition structures.
pulCount; ESS_PULONG_T Number of data blocks in ppReports.
321
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPIInit
Starts a drill-through session, and returns a drill-through instance handle.
Syntax
ESS_FUNC_M EssDTAPIInit (pDTAPIInit, pDTAPIInst);
pDTAPIInit; ESS_PDTAPIINIT_T Currently not used, and set to NULL.
ppDTAPIInst; ESS_PDTAPIHINST_T Pointer to a drill-through initialization structure.
Notes
l This function initializes ppDTAPIHInst.
l Currently, pDTAPIInit (intended for input) is not used, and is set to NULL.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPISetInfo
322
EssDTAPISetConnection
Given a connection information string, and an extended member comment string, initializes a
drill-through handle, and starts the Drill-Through Wizard.
Syntax
ESS_FUNC_M EssDTAPISetConnection (pDTAPIInst, pEMC, ulCount, pDTInfo);
pDTAPIInst; ESS_PDTAPIHINST_T Pointer to a drill-through initialization structure.
pEMC; ESS_PSTR_T Extended member comment.
ulCount; ESS_ULONG_T Number of extended member comment blocks.
pDTInfo; ESS_PSTR_T Connection information.
Notes
Use EssGDTRequestDrillThrough to initialize the drill-through instance handle, because:
l EssDTAPISetConnection currently does not initialize pDTAPIInst.
l Due to security issues, pConnection (the connection information string) and pEMC (the
extended member comment string) currently are not retrieved from Essbase Server.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
l EssDTAPISetInfo
EssDTAPISetInfo
Sets drill-through connection information for a given drill-through handle.
Syntax
ESS_FUNC_M EssDTAPISetInfo (pDTAPIInst, pDTInfo);
323
pDTAPIInst; ESS_PDTAPIHINST_T Initialized drill-through instance handle for a given range of data
cells.
pDTInfo; “ESS_DTAPIINFO_T” on page 129 Pointer to a structure of connection information for a given range
of data cells.
Notes
The uInputOption field in ESS_DTAPIINFO_T is ignored.
See Also
l EssDTAPIClose
l EssDTAPIConnect
l EssDTAPIExit
l EssDTAPIGetData
l EssDTAPIGetError
l EssDTAPIGetInfo
l EssDTAPIInit
EssDTClose
Eds the drill-through session for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTClose (pDTInst);
pDTInst; ESS_PDTHINST_T Initialized drill-through instance handle for the given data cell range(s).
Notes
l This function closes the drill-through session, but does not free up memory.
l EssDTExit closes the drill-through session and frees up memory.
See Also
l EssDTExit
l EssDTGetData
324
l EssDTGetHeader
l EssDTInit
l EssDTListReports
l EssDTOpen
EssDTExit
Ends the drill-through session and frees up memory for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTExit (pDTInst);
pDTInst; ESS_PDTHINST_T Initialized drill-through instance handle for the given data cell range(s).
Notes
l This function closes the drill-through session and frees up memory.
l EssDTClose closes the drill-through session, but does not free up memory.
See Also
l EssDTClose
l EssDTGetData
l EssDTGetHeader
l EssDTInit
l EssDTListReports
l EssDTOpen
EssDTGetData
Retrieves an array of report data for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTGetData (pDTInst, pData, pulCount);
pDTInst; ESS_PDTHINST_T Initialized drill-through instance handle.
pData; “ESS_DTDATA_T” on page 131 Array of report data structures for given data cells.
pulCount; ESS_PULONG_T Number of data blocks in the pData header information array.
325
Notes
Call this function until pulCount is 0 (zero).
See Also
l EssDTClose
l EssDTExit
l EssDTGetHeader
l EssDTInit
l EssDTListReports
l EssDTOpen
EssDTGetHeader
Retrieves an array of report header structures for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTGetHeader (pDTInst, pBuffer, pulCount);
pDTInst; ESS_PDTHINST_T Initialized drill-through instance handle.
pBuffer; “ESS_DTBUFFER_T” on page 130 An array of report header structures for the given columns.
pulCount; ESS_PULONG_T Number of data blocks in the pBuffer report header information array.
See Also
l EssDTClose
l EssDTExit
l EssDTGetData
l EssDTInit
l EssDTListReports
l EssDTOpen
EssDTGetHeaderInfo
Retrieves report data header information for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTGetHeaderInfo (pDTInst, ppHeader, pulCount);
326
pDTInst ESS_PDTHINST_T Initialized drill-through instance handle.
ppHeader “ESS_DTHEADER_T” on page 131 Array of header information structures for the given drill-through
instance handle.
pulCount ESS_PULONG_T Number of blocks in the ppHeader header information array.
See Also
l EssDTClose
l EssDTExit
l EssDTGetData
l EssDTGetHeader
l EssDTInit
l EssDTListReports
l EssDTOpen
l EssDTOpen
EssDTInit
Starts a drill-through session, and returns a drill-through instance handle.
Syntax
ESS_FUNC_M EssDTInit (pInit, pDTInst);
pDTInit; ESS_PDTINIT_T (Currently not used, and set to NULL.)
ppDTInst; ESS_PDTHINST_T Pointer to a drill-through initialization structure.
Notes
l This function initializes ppDTHInst.
l Currently, pDTInit (intended for input) is not used, and is set to NULL.
See Also
l EssDTClose
l EssDTExit
l EssDTGetData
l EssDTGetHeader
l EssDTListReports
l EssDTOpen
327
EssDTListReports
Returns a list of report names for the given drill-through instance handle.
Syntax
ESS_FUNC_M EssDTListReports (pDTInst, pBuffer, pulCount);
pDTInst ESS_PDTHINST_T Initialized drill-through instance handle.
pBuffer ESS_PSTR_T Array of report names for the given drill-through instance handle.
pulCount ESS_PULONG_T Count of blocks in the pBuffer header information array.
See Also
l EssDTClose
l EssDTGetData
l EssDTGetHeader
l EssDTInit
l EssDTOpen
EssDTOpen
Given a connection information string, and an Extended Member Comment string, initializes
a drill-through handle, and starts the Drill-Through Wizard.
Syntax
ESS_FUNC_M EssDTOpen (pDTInst, pEMC, ulCount, pConnection);
pDTInst; ESS_PDTHINST_T Pointer to a drill-through initialization structure.
pEMC; ESS_PSTR_T Extended member comment.
ulCount; ESS_ULONG_T Number of extended member comment blocks.
pConnection; ESS_PSTR_T Connection information.
Notes
l This function initializes pDTInst.
l Given an outline, and a data cell selection, pConnection (the connection information string)
and pEMC (the extended member comment string) are obtained from Essbase.
See Also
328
l EssDTClose
l EssDTExit
l EssDTGetData
l EssDTGetHeader
l EssDTInit
l EssDTListReports
EssDumpPerfStats
Dumps performance statistics tables to a character array.
Syntax
ESS_FUNC_M EssDumpPerfStats (hCtx, pStatBuf, [thdSN])
hCtx; ESS_HCTX_T API context handle (input).
pStatBuf; ESS_STR_T Pointer to the address where performance statistics tables will be dumped (input).
thdSN; ESS_INT_T Optional. Thread serial number from which to dump statistics (input). Default is 0 (all
threads are dumped).
Notes
Before you call this function, call EssGetStatBufSize to ascertain how much memory to
allocate for the performance statistics tables at the address pointed to by pStatBuf.
Return Value
l If successful, this function
m Returns 0.
m Dumps performance statistics tables to a character array that begins at the address
pointed to by pStatBuf.
l The caller of this function is responsible for allocating and freeing memory at the address
pointed to by pStatBuf.
l For more information on performance statistics tables, see the Oracle Essbase Technical
Reference.
Access
The caller of this function must have supervisor access.
Example
/* This function gets the array of performance stats */
ESS_STS_T ESSGetPerfStats(ESS_HCTX_T *context)

{
329
ESS_STS_T sts;
ESS_ULONG_T bufsize;
ESS_PUCHAR_T poutarray; /* Pointer to the stats staging area */
/* Get the size of the output buffer */

if(sts = EssGetStatBufSize(context, &bufsize))
return(sts);
if(bufsize)
{
/* Allocate a staging area */
(ESS_PVOID_T)(poutarray) = malloc (bufsize);
/* Fill the staging area */

sts = EssDumpPerfStats(context, poutarray);
if(sts)
return(sts);
/* Do something useful with the stats here */

/* ....................................... */
/* Free the staging area */

sts = EssFree(context, poutarray);
if(sts)
return(sts);
}
else
{
printf("Performance Statistics not enabled, call ResetPerfStats()\n");
}
return(ESS_STS_NOERR);
}
See Also
l EssGetStatBufSize
l EssResetPerfStats
EssEndCalc
Marks the end of a calculation script being sent to the active database. This function must be
called after sending the calculation script (using EssSendString).
Syntax
ESS_FUNC_M EssEndCalc (hCtx);
Notes
l This function must be preceded by a call to EssBeginCalc, and at least one call to
EssSendString.
330
l If the calls to EssBeginCalc, EssSendString, and EssEndCalc succeed, the caller must check
at regular intervals to see whether the process has completed by calling
EssGetProcessState until it returns ESS_STATE_DONE.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_Calc (ESS_HCTX_T hCtx)
{
ESS_STR_T Script;

if (!sts)
if (!sts)
if (!sts)
{
ESS_STATE_DONE))
}
return(sts);
}
See Also
l EssBeginCalc
l EssCalc
l EssSendString
EssEndDataload
Marks the end of an update specification being sent to the active database, and must be called
after sending the update specification using EssSendString.
Syntax
ESS_STS_T EssEndDataload (hCtx, ppMbrError);
331
ppMbrError; “ESS_MBRERR_T” on Pointer to the linked list of errors contained in ESS_MBRERR_T. Possible errors
page 142 (and error strings) are:
l ESS_MBRERR_UNKNOWN (Unknown member [membername] in
dataload, [number] records returned.)
l ESS_MBRERR_DBACCESS (You have insufficient access privilege to
perform a lock on this database.)
l ESS_MBRERR_BADDATA (Invalid member [membername] in data
column.)
l ESS_MBRERR_DUPLICATE (Duplicate members from the same
dimension on data record, [number] records completed.)
l AD_MSGDL_ERRORLOAD (Unable to do dataload at Item/Record
[number].)
Notes
l This function must be preceded by a call to EssBeginDataload, and at least one call to
EssSendString.
l The memory allocated for ppMbrError must be freed using EssFreeMbrErr.
Return Value
Returns zero, if successful. Otherwise, returns an error code, as follows:
l If abortOnError is TRUE:
m The error code for the first error condition is returned.
m The error list is NULL.
l If abortOnError is FALSE:
m An error list is returned, if the server can process the data and can continue.
m Otherwise, in exceptional circumstances, the error code explaining why the server
cannot continue is returned. For example:
AD_MSGDL_COLS (too many data values in a record)
AD_MSGDL_MISDIM (data value encountered before all dimensions selected)
Access
database.
Example
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
Store = ESS_TRUE;
Unlock = ESS_FALSE;
332
/* Begin Update */
sts = EssBeginDataload (hCtx, Store, Unlock, ESS_FALSE, ESS_NULL);

if(!sts)
/* End Update */
if(!sts)
See Also
l EssBeginDataload
l EssSendString
l EssBeginUpdate
l EssEndUpdate
l EssUpdate
EssEndIncrementalBuildDim
Finalizes the round of building dimensions: Performs outline verification: if there is no outline
verification error, writes and closes the outline and restructures. If the outline has errors, writes
the outline to the outline file specified by “szTmpOtlFile” and closes the outline. You can use
outline editing tools, such as EAS outline editor, to see what is wrong in the outline.
Syntax
ESS_FUNC_M EssEndIncrementalBuildDim (hCtx, restructOption, szTmpOtlFile, ErrorName,
bOverwrite)
restructOption ESS_SHORT_T Restructure option. Valid values:

l ESS_DOR_ALLDATA
Keep all data
l ESS_DOR_NODATA
Discard all data
l ESS_DOR_LOWDATA
Keep all level 0 data
l ESS_DOR_INDATA
Keep all input data
szTmpOtlFile ESS_STR_T The temp outline file name.
333

Return Value
Example
ESS_FUNC_M
{
ESS_STS_T sts = 0;
if (!sts)
sts =
,NULL);
if (!sts)
sts =
,NULL);
if (!sts)
sts =
L,"tmpotl");
334
if (!sts)
if (!sts)
if (!sts)
return sts;
}
See Also
EssEndReport
Marks the end of a report specification being sent to the active database. This function must be
called after sending the report specification (using EssSendString) and before reading any
returned data (using EssGetString).
Syntax
ESS_FUNC_M EssEndReport (hCtx);
Notes
l This function must be preceded by a call to EssBeginReport, and at least one call to
EssSendString.
l If the output flag is TRUE for the call to EssBeginReport that begins the report sequence,
the call to EssEndReport must be followed by repeated calls to EssGetString until a NULL
string is returned.
Return Value
None.
Access
335
Example
ESS_FUNC_M
ESS_HINST_T hInst
)
{
if (!sts)
if (!sts)
/**************
* Get report *
**************/
if (!sts)
{
}
printf ("\r\n");
return(sts);
}
See Also
l EssBeginReport
l EssGetString
l EssSendString
EssEndStreamBuildDim
Ends the dimension build process.
This function must be preceded by a call to EssBeginStreamBuildDim, and then one or more
calls to EssSendString to send source records to the Essbase server.
Syntax
ESS_FUNC_M EssEndStreamBuildDim (hCtx, ErrorFileName, ErFileOverWrite)
ErrorFileName ESS_STR_T Name of error output file on client.
336
ErFileOverWrite ESS_BOOL_T Boolean. Values:

Return Value
Example
ESS_FUNC_M
{
ESS_STS_T sts = 0;
if (!sts)
sts =
,NULL);
if (!sts)
sts =
,NULL);
if (!sts)
sts =
L,"tmpotl");
337
if (!sts)
if (!sts)
if (!sts)
return sts;
}
See Also
EssEndUpdate
Marks the end of an update specification being sent to the active database. This function must
be called after sending the update specification (using EssSendString).
Syntax
ESS_FUNC_M EssEndUpdate (hCtx);
Notes
This function must be preceded by a call to EssBeginUpdate, and at least one call to
EssSendString.
Return Value
None.
Access
database.
Example
See the example of EssBeginUpdate.
See Also
l EssBeginUpdate
338
l EssSendString
l EssUpdate
EssExport
Exports a database to an ASCII file.
Syntax
ESS_FUNC_M EssExport (hCtx, AppName, DbName, PathName,
Level, Columns);
AppName ESS_STR_T Name of application to export.
DbName ESS_STR_T Name of database to export.
PathName ESS_STR_T Full path name of server file to contain exported information.
Level ESS_SHORT_T Controls level of data to export. Should be one of the following values:
l ESS_DATA_ALL—Export all levels of data
l ESS_DATA_LEVEL0—Export all data only from level zero blocks
l ESS_DATA_INPUT—Export data only from input level blocks
Columns ESS_SHORT_T Controls output of data blocks in column format (for creating rules files). Use non-zero
for column format, and zero for no column format.
Notes
If the data for a thread exceeds 2 GB, Essbase may divide the export data into multiple files with
numbers appended to the file names.
The naming convention for additional export files is as follows: _1, _2, etc. are appended to the
additional file names. If the specified output file name contains a period, the numbers are
appended before the period. Otherwise, they are appended at the end of the file name.
For example, if the given file name is /home/exportfile.txt, the next additional file is /
home/exportfile_1.txt. If the file name is /home/exportfile, the next additional file is /
home/exportfile_1.
Return Value
None.
Access
339
Example
ESS_FUNC_M
ESS_Export (ESS_HCTX_T hCtx)
{
ESS_SHORT_T isLevel;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
isLevel = ESS_DATA_LEVEL0;
AppName = "Sample";
DbName = "Basic";
sts = EssExport (hCtx, appName, dbName,

"D:\\temp\\asofile.txt", ESS_DATA_LEVEL0, ESS_FALSE);
if (!sts)
{
ESS_STATE_DONE))
}
return (sts);
}
See Also
l EssImport
EssFixIBH
Repairs invalid-block-header corruption in the database. Currently, it removes all the invalid
blocks from the database.
Syntax
ESS_FUNC_M EssFixIBH (hCtx, action);
action; ESS_IBH_ACTION An enumeration type. For this release the only valid value is REMOVE.
See Also
l EssLocateIBH
l EssGetIBH
EssFree
Frees a previously allocated block of memory, using the defined memory allocation scheme.
340
Syntax
ESS_FUNC_M EssFree (hInstance, pBlock);
pBlock ESS_PVOID_T Pointer to allocated memory block.
Notes
l This function frees memory using the user-supplied memory management function passed
to the EssInit function. If no such function is supplied, the default memory freeing
function (dependent on the platform) will be used.
l This function should be used to free any memory allocated using the EssAlloc and
EssRealloc functions. It should also be used to free any allocated buffers returned from
Essbase API functions.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_GetAppActive (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STR_T pDbName;
ESS_STR_T pAppName;
if ((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pAppName)) == 0)

{
if ((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pDbName)) == 0)
{
if ((sts = EssGetActive (hCtx, &pAppName, &pDbName, &Access)) == 0)
{
if (pAppName)
{
if (*pAppName)
else
printf ("\r\n");
}
}
}
341
}
return (sts);
}
See Also
l EssAlloc
l EssInit
l EssOtlGetMemberCommentEx
l EssOtlSetMemberCommentEx
l EssRealloc
EssFreeMbrErr
Frees the memory allocated for a linked list of ESS_MBRERR_T structures.
Syntax
ESS_FUNC_M EssFreeMbrErr (hCtx, pMbrError);
pMbrError ESS_PMBRERR_T Pointer to linked list contained in ESS_MBRERR_T.
Notes
This function can only be used to free the memory allocated for ESS_MBRERR_T.
Return Value
None.
Access
Example
See the example of EssImport.
See Also
l EssImport
EssFreeStructure
Frees memory dynamically allocated by EssGetAttributeInfo and EssGetMemberInfo for
string type attribute information.
Syntax
ESS_FUNC_M EssFreeStructure (hInst, structId,count,structPtr);
342
hInst ESS_HINST_T The instance handle of the process that called EssGetAttributeInfo or EssGetMemberInfo
to allocate the structure.
structId ESS_ULONG_T One of the following constant identifiers for the structure:
l ESS_DT_STRUCT_ATTRIBUTEINFO
l ESS_DT_STRUCT_ATTRSPECS
l ESS_DT_STRUCT_MEMBERINFO
count ESS_ULONG_T Number of structures.
structPtr ESS_PVOID_T Pointer to memory.
Notes
Always call this function to free structures allocated with either EssGetAttributeInfo or
EssGetMemberInfo before you leave the local routine.
Access
Example
void ESS_GetAttributeSpecifications()
{
ESS_PATTRSPECS_T pAttrSpecs;
sts = EssGetAttributeSpecifications(hCtx, &pAttrSpecs);
printf("\n ---------Attribute Specifications--------\n\n");

if (sts) return(sts);
switch(pAttrSpecs->usGenNameBy)
{
case ESS_GENNAMEBY_PREFIX:
printf("\n Prefix/Suffix : Prefix");
break;
case ESS_GENNAMEBY_SUFFIX:
printf("\n Prefix/Suffix : Suffix");
break;
default:
printf("\n Prefix/Suffix : None");
break;
}
switch(pAttrSpecs->usUseNameOf)
{
case ESS_USENAMEOF_PARENT:
printf("\n Use Name of : Parent");
break;
case ESS_USENAMEOF_GRANDPARENTANDPARENT:
printf("\n Use Name of : Grand Parent and Parent");
break;
case ESS_USENAMEOF_ALLANCESTORS:
343
printf("\n Use Name of : All Ancestors");
break;
case ESS_USENAMEOF_DIMENSION:
printf("\n Use Name of : Dimension");
break;
case ESS_USENAMEOF_NONE:
printf("\n Use Name of : None");
break;
default:
printf("\n Use Name of : Invalid setting");
break;
}
switch(pAttrSpecs->cDelimiter)
{
case ESS_DELIMITER_PIPE:
printf("\n Delimiter : '|'");
break;
case ESS_DELIMITER_UNDERSCORE:
printf("\n Delimiter : '_'");
break;
case ESS_DELIMITER_CARET:
printf("\n Delimiter : '^'");
break;
default:
printf("\n Delimiter : Invalid setting");
break;
}
switch(pAttrSpecs->usDateFormat)
{
case ESS_DATEFORMAT_DDMMYYYY :
printf("\n Date Format : DD-MM-YYYY");
break;
case ESS_DATEFORMAT_MMDDYYYY :
printf("\n Date Format : MM-DD-YYYY");
break;
default:
printf("\n Date Format : Invalid setting");
break;
}
switch(pAttrSpecs->usBucketingType)
{
case ESS_UPPERBOUNDINCLUSIVE :
printf("\n Bucketing Type : Upper Bound inclusive");
break;
case ESS_UPPERBOUNDNONINCLUSIVE :
printf("\n Bucketing Type : Upper Bound non-inclusive");
break;
case ESS_LOWERBOUNDINCLUSIVE :
printf("\n Bucketing Type : Lower Bound inclusive");
break;
case ESS_LOWERBOUNDNONINCLUSIVE :
printf("\n Bucketing Type : Lower Bound non-inclusive");
break;
default:
printf("\n Bucketing Type : Invalid setting");
break;
344
}
printf("\n Default for TRUE : %s",pAttrSpecs->pszDefaultTrueString);

printf("\n Default for FALSE : %s",pAttrSpecs->pszDefaultFalseString);
printf("\n Default for Attr Calc : %s",pAttrSpecs->pszDefaultAttrCalcDimName);
printf("\n Default for Sum : %s",pAttrSpecs->pszDefaultSumMbrName);
printf("\n Default for Count : %s",pAttrSpecs->pszDefaultCountMbrName);
printf("\n Default for Average : %s",pAttrSpecs->pszDefaultAverageMbrName);
printf("\n Default for Min : %s",pAttrSpecs->pszDefaultMinMbrName);
printf("\n Default for Max : %s",pAttrSpecs->pszDefaultMaxMbrName);
printf("\n");
EssFreeStructure(hInst, ESS_DT_STRUCT_ATTRSPECS, 1,(ESS_PVOID_T)pAttrSpecs);

}
See Also
l EssCheckAttributes
EssGetActive
Gets the names of the caller's current active application and database.
Syntax
ESS_FUNC_M EssGetActive (hCtx, pAppName, pDbName, pAccess);
pAppName ESS_PSTR_T Address of pointer to receive allocated application name string.
pDbName ESS_PSTR_T Address of pointer to receive allocated database name string.
pAccess; ESS_PACCESS_T Address of variable to receive the user's access level to the selected database. See
“Bitmask Data Types (C)” on page 90 for a list of possible values for this field.
345
Notes
You should free the memory allocated for pAppName and pDbName using EssFree.
Return Value
If successful, returns the user's selected active application and database in pAppName and
pDbName.
Access
Example
ESS_FUNC_M
ESS_GetAppActive (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STR_T pDbName;
ESS_STR_T pAppName;
if ((sts = EssAlloc (hInst, 80,
(ESS_PPVOID_T)&pAppName)) == 0)
{
if ((sts = EssAlloc (hInst, 80,
(ESS_PPVOID_T)&pDbName)) == 0)
{
if ((sts = EssGetActive (hCtx, &pAppName,
&pDbName, &Access)) == 0)
{
if (pAppName)
{
if (*pAppName)
else
printf ("\r\n");
}
}
}
}
return (sts);
}
See Also
l EssClearActive
l EssSetActive
EssGetAlias
Gets the active alias table name from the active database for a user.
346
Syntax
ESS_FUNC_M EssGetAlias (hCtx, pAliasName);
pAliasName ESS_PSTR_T Address of pointer to receive allocated name of active alias table.
Notes
The memory allocated for pAliasName should be freed using EssFree.
Return Value
If successful, returns the name of the active alias table in pAliasName.
Access
Example
ESS_FUNC_M
ESS_GetAlias (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T AliasName;
sts = EssGetAlias(hCtx, &AliasName);
if(!sts && AliasName)

{
printf("AliasName: %s\r\n",AliasName);
EssFree(hInst,AliasName);
}
return (sts);
}
See Also
l EssListAliases
l EssSetAlias
EssGetAPIVersion
Returns the version of the Essbase API used to compile the current application.
Syntax
ESS_FUNC_M EssGetAPIVersion (Version);
347
Version ESS_PULONG_T Version number of API. Hex value, in C notation, with the following format:
0x00000000
l First 4 numbers from right (low order word): release number between versions
l Remaining numbers (high order word): version number
For example, 0x0004.0000 represents Release 4.0, and 0x0003.0002 represents Release
3.2.
Notes
You can use this function to check the API version when your program requires a particular
version.
Example
ESS_VOID_T
ESS_GetAPIVersion()
{
sts = EssGetAPIVersion(&Version);
if(!sts)
printf("API Version %x\n",Version);
}
See Also
l EssGetObjectInfo
EssGetApplicationAccess
Gets a list of user application access structures, which contain information about user access to
applications.
Syntax
ESS_FUNC_M EssGetApplicationAccess (hCtx, UserName, AppName, pCount, ppUserApp);
UserName ESS_STR_T User name. If NULL, lists all users for the specified application.
AppName ESS_STR_T Application name. If NULL, lists all applications for the specified user.
pCount ESS_PUSHORT_T Address of variable to receive count of user application structures.
348
ppUserApp “ESS_USERAPP_T, Address of pointer to receive an allocated array of user application

ESS_GROUPAPP_T” on page structures.
183
Notes
l If UserName is NULL, all users will be listed for the specified application. If AppName is
NULL, all applications will be listed for the specified user. However, UserName and
AppName cannot both be NULL
l The Access field of the user application structure is used to represent the user's granted access
to the application, whereas the MaxAccess field represents the user's highest access from all
sources (e.g. via groups or default application access etc.).
l The memory allocated for ppUserApp should be freed using EssFree.
Return Value
If successful, returns a count of users/applications in pCount, and a list of user application
structures in ppUserApp.
Access
This function requires callers to have application designer privilege (ESS_PRIV_APPDESIGN)
for the specified application, unless they are getting their own application access information.
Example
ESS_FUNC_M
ESS_GetApplicationAccess (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T UserName;
ESS_STR_T AppName;
ESS_USHORT_T Count = 0;
ESS_USHORT_T ind;
ESS_PUSERAPP_T UserApp = NULL;
UserName = "Admin";
AppName = "";
sts = EssGetApplicationAccess(hCtx, UserName,

AppName, &Count, &UserApp);
if(!sts)
{
if(Count && UserApp)
{
printf ("\n------Application Access List----\n\n");
{
printf ("User->%s Application->%-10s
Access->%-4d MaxAccess->%-6d\r\n",
UserApp[ind].UserName,
UserApp[ind].AppName,
UserApp[ind].Access,
349
UserApp[ind].MaxAccess);
}
EssFree (hInst, UserApp);
}
else
printf ("\rUser Application list is empty\n\n");
}
return (sts);
}
See Also
l EssGetApplicationAccessEx
l EssGetDatabaseAccess
l EssListUsers
l EssSetApplicationAccess
l EssSetUser
EssGetApplicationAccessEx
Gets a list of user or group application access structures, which contain information about user
or group access to applications. Similar to EssGetApplicationAccess, but can accept a user
directory specification or unique identity attribute for UserID.
Syntax
ESS_FUNC_M EssGetApplicationAccessEx (hCtx, UserId, bIsIdentity, type, AppName, pCount,
ppUserApp);
UserId ESS_STR_T User or group name (input). Can be specified as name@provider or as a

unique identity attribute. If NULL, lists all users or groups for the specified
application.
bIsIdentity ESS_BOOL_T Input. Indicates if UserID is a name or an identity. If TRUE, UserID is an identity.
type ESS_USHORT_T Type of entity (input). Indicates if UserID is a group or a user. Can be one of the
following:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
AppName ESS_STR_T Application name (input). If NULL, lists all applications for the specified user.
pCount ESS_PUSHORT_T Address of variable to receive count of user application structures (output).
ppUserApp ESS_PPUSERAPPEX_T Address of pointer to receive an allocated array of user application structures
(output). The user application structure can include user directories and unique
350
Notes
l If UserID is NULL, all users will be listed for the specified application. If AppName is NULL,
all applications will be listed for the specified user. However, UserID and AppName cannot
both be NULL.
l The Access field of the user application structure is used to represent the user's granted access
to the application, whereas the MaxAccess field represents the user's highest access from all
sources (for example,. via groups, default application access, etc.).
l The memory allocated for ppUserApp should be freed using EssFree.
Return Value
If successful, returns a count of users/applications in pCount, and a list of user application
structures in ppUserApp.
Access
This function requires callers to have application designer privilege (ESS_PRIV_APPDESIGN)
for the specified application, unless they are getting their own application access information.
Example
void DisplayUserAppInfo(ESS_PUSERAPPEX_T userApp, ESS_USHORT_T count)

{
ESS_USHORT_T ind;

for (ind = 0; ind < count; ind++)
{
printf("\tUser: %s\n", userApp[ind].UserName);
printf("\tProvider Name: %s\n", userApp[ind].ProviderName);
printf("\tConnection Param: %s\n", userApp[ind].connparam);
printf("\tAppName: %s\n", userApp[ind].AppName);
switch(userApp[ind].Access)
{
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userApp[ind].Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userApp[ind].Access);
break;
case ESS_PRIV_WRITE:
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userApp[ind].Access);
break;
case ESS_PRIV_CALC:
printf("\tAccess: %d - ESS_PRIV_CALC\n", userApp[ind].Access);
break;
case ESS_PRIV_METAREAD:
printf("\tAccess: %d - ESS_PRIV_METAREAD\n", userApp[ind].Access);
break;
case ESS_PRIV_DBLOAD:
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userApp[ind].Access);
break;
351
case ESS_PRIV_DBMANAGE:
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userApp[ind].Access);
break;
case ESS_PRIV_DBCREATE:
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userApp[ind].Access);
break;
case ESS_PRIV_APPLOAD:
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userApp[ind].Access);
break;
case ESS_PRIV_APPMANAGE:
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userApp[ind].Access);
break;
case ESS_PRIV_APPCREATE:
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userApp[ind].Access);
break;
case ESS_PRIV_USERCREATE:
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userApp[ind].Access);
break;
case ESS_ACCESS_READ:
printf("\tAccess: %d - ESS_ACCESS_READ\n", userApp[ind].Access);
break;
case ESS_ACCESS_WRITE:
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userApp[ind].Access);
break;
case ESS_ACCESS_CALC:
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userApp[ind].Access);
break;
case ESS_ACCESS_METAREAD:
printf("\tAccess: %d - ESS_ACCESS_METAREAD\n", userApp[ind].Access);
break;
case ESS_ACCESS_DBMANAGE:
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userApp[ind].Access);
break;
case ESS_ACCESS_DBCREATE:
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userApp[ind].Access);
break;
case ESS_ACCESS_APPMANAGE:
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userApp[ind].Access);
break;
case ESS_ACCESS_APPCREATE:
printf("\tAccess: %d - ESS_ACCESS_APPCREATE\n", userApp[ind].Access);
break;
case ESS_ACCESS_FILTER:
printf("\tAccess: %d - ESS_ACCESS_FILTER\n", userApp[ind].Access);
break;
case ESS_ACCESS_DBALL:
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", userApp[ind].Access);
break;
case ESS_ACCESS_APPALL:
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userApp[ind].Access);
break;
case ESS_ACCESS_ADMIN:
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userApp[ind].Access);
break;
default:
printf("\tAccess: Unknown\n");
352
}
switch(userApp[ind].MaxAccess)
{
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userApp[ind].MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userApp[ind].MaxAccess);
break;
case ESS_PRIV_CALC:
printf("\tMax Access: %d - ESS_PRIV_CALC\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_METAREAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_METAREAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userApp[ind].MaxAccess);
break;
353
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_FILTER\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userApp[ind].MaxAccess);
break;
default:
printf("\tMax Access: Unknown\n");
}
printf("\n");
}
}
ESS_FUNC_M ESS_GetApplicationAccessEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T userId;
ESS_USHORT_T type;
ESS_USHORT_T count = 0;
ESS_USERAPPEX_T userApp[2];
ESS_PUSERAPPEX_T pUserApp = ESS_NULL;
count = 1;
strcpy(userApp[0].UserName, "IDUser1");
strcpy(userApp[0].ProviderName, "");
strcpy(userApp[0].connparam, "");
userApp[0].type = ESS_TYPE_USER;
strcpy(userApp[0].AppName, AppName);
userApp[0].Access = ESS_PRIV_APPMANAGE;
userApp[0].MaxAccess = ESS_PRIV_APPMANAGE;
sts = EssSetApplicationAccessEx(hCtx, count, &userApp);
printf("EssSetApplicationAccessEx sts: %ld\n", sts);
userId = "IDUser1";
AppName = AppName;
type = ESS_TYPE_GROUP;
sts = EssGetApplicationAccessEx(hCtx, userId, bIsIdentity, type, AppName, &count,
&pUserApp);
printf("EssGetApplicationAccessEx sts: %ld\n", sts);
354
if(!sts)
{
if(count && pUserApp)
{
DisplayUserAppInfo(pUserApp, count);
sts = EssFree (hInst, pUserApp);
}
else
}
return (sts);
}
See Also
l EssGetDatabaseAccessEx
l EssListUsersInfoEx
l EssSetApplicationAccessEx
EssGetApplicationInfo
Gets an application's information structure, which contains non user-configurable parameters
for the application.
Syntax
ESS_FUNC_M EssGetApplicationInfo (hCtx, AppName, ppAppInfo);
hCtx ESS_HCTX_T API context handle (logged in).
ppAppInfo “ESS_APPINFO_T” on page 109 Address of pointer to receive allocated application info structure.
Notes
l This function can only be called for applications on the server.
l The memory allocated for ppAppInfo should be freed using EssFree.
Return Value
If successful, this function returns a pointer to an allocated application info structure in
ppAppInfo.
Access
This function requires the caller to have at least read access (ESS_PRIV_READ) to the specified
application.
Example
ESS_FUNC_M
ESS_GetAppInfo (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
355
)
{
ESS_PAPPINFO_T AppInfo;
ESS_USHORT_T ind;
ESS_STR_T AppName;
AppName = "Sample";
sts = EssGetApplicationInfo (hCtx, AppName, &AppInfo);

if (!sts)
{
if (AppInfo)
{
printf ("\r\n-------Application Info-------\r\n\r\n");
printf ("Name : %s\r\n", AppInfo->Name);
printf ("Server Name : %s\r\n", AppInfo->Server);
printf ("Status : %d\r\n", AppInfo->Status);
printf ("Users Connected : %d\r\n", AppInfo->nConnects);
printf ("Number of DBs : %d\r\n", AppInfo->nDbs);
printf ("\r\n--List of Databases--\r\n\r\n");
for (ind = 0; ind < AppInfo->nDbs; ind++)
printf ("database(%d) : %s\r\n", ind,
AppInfo->DbNames [ind]);
EssFree (hInst, AppInfo);
}
}
return (sts);
}
See Also
l EssGetApplicationInfoEx
l EssGetApplicationState
l EssGetDatabaseInfo
EssGetApplicationInfoEx
Retrieves information from one or more applications.
Syntax
ESS_FUNC_M EssGetApplicationInfoEx (hCtx, AppName, pusCount, ppAppInfoEx);
AppName ESS_STR_T Name of application for which to return information. If NULL,

returns information for all applications.
pusCount ESS_PUSHORT_T Number of information structures returned.
ppAppInfoEx “ESS_APPINFOEX_T” on page Address of pointer to an array of allocated application info

110 structures.
356
Notes
l This function can only be called for applications on the server.
l The memory allocated for ppAppInfo should be freed using EssFree.
Return Value
If successful, this function returns an array of application information structures in ppAppInfo.
Access
application.
Example
ESS_FUNC_M
ESS_GetApplicationInfoEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_USHORT_T ind;
ESS_STR_T AppName;
ESS_USHORT_T Count;
ESS_PAPPINFOEX_T AppInfoEx = NULL;
AppName = "";
sts = EssGetApplicationInfoEx (hCtx, AppName,
&Count, &AppInfoEx);
if(!sts)
{
if(AppInfoEx)
{
printf("\n-----Application Info Ex -----\n\n");
for (ind = 0; ind <Count; ind++)
{
printf("Name:%s\r\n",AppInfoEx[ind].Name);
printf("Server Name:%s\r\n", AppInfoEx[ind].Server);
printf("Status:%d\r\n",AppInfoEx[ind].Status);
printf("Users Connected:%d\r\n",
AppInfoEx[ind].nConnects);
printf("\r\n");
}
EssFree(hInst, AppInfoEx);
}
}
return (sts);
}
See Also
l EssGetApplicationInfo
357
EssGetApplicationState
Gets an application's state structure, which contains user-configurable parameters for the
application.
Syntax
ESS_FUNC_M EssGetApplicationState (hCtx, AppName, ppAppState);
ppAppState “ESS_APPSTATE_T” on page 111 Address of pointer to receive allocated application state structure.
Notes
l This function cannot be called for local applications; it can only be called for applications
on the server.
l Memory allocated for ppAppState should be freed using EssFree.
Return Value
If successful, this function returns a pointer to an allocated application state structure in
ppAppState.
Access
application.
Example
ESS_FUNC_M
ESS_GetAppState (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PAPPSTATE_T AppState;
ESS_STR_T AppName;
AppName = "Sample";
sts = EssGetApplicationState (hCtx, AppName,
&AppState);
if (!sts)
{
if (AppState)
{
EssFree (hInst, AppState);
}
}
return (sts);
}
358
See Also
l EssGetDatabaseState
l EssSetApplicationState
EssGetAssociatedAttributesInfo
Returns the attribute members associated with a given base member.
Syntax
BaseMbrName; ESS_STR_T Base member name.
AttrDimName; ESS_STR_T (Optional) attribute dimension name.
pCount; ESS_PULONG_T Number of attribute members returned.
ppAttrInfo; “ESS_ATTRIBUTEINFO_T” on page 112 Attribute information.
Notes
l Call this function to retrieve more information for attribute members than you retrieve
using EssQueryDatabaseMembers.
l Set AttrDimName to NULL to return all attribute members that are associated with the base
member.
l Optionally, provide an attribute dimension name to retrieve information only about the
member of that dimension which is associated with the base member.
Access
Example
//void ESS_GetAssociateAttributeInfo();
ESS_GetAssociatedAttributesInfo ()
{
ESS_STS_T sts;
ESS_ULONG_T pCount=0;
ESS_PATTRIBUTEINFO_T pAttributeInfo;
ESS_USHORT_T index=0;
ESS_CHAR_T time_string[32];
struct tm* pTime;
ESS_DATETIME_T et;
ESS_MBRNAME_T attributeName;
359
ESS_MBRNAME_T dimensionName;
pAttributeInfo = NULL;
strcpy(attributeName, "100-10");
strcpy(dimensionName, "\0");
sts = EssGetAssociatedAttributesInfo(hCtx, attributeName, dimensionName, &pCount,

&pAttributeInfo);
/* for handling time values */

et = pAttributeInfo->Attribute.value.dtData;
if (!sts)
{
printf ("\nAssociated Attr info for [%s]\n", attributeName);
printf ("------------------------------------\n");
for (index=0; index<pCount; index++)
{
printf ("MbrName : %s\n", pAttributeInfo[index].MbrName);
printf ("DimName : %s\n", pAttributeInfo[index].DimName);
switch(pAttributeInfo[index].Attribute.usDataType)
{
case ESS_ATTRMBRDT_BOOL:
printf ("Data Type : Boolean \n");
if ( pAttributeInfo[index].Attribute.value.bData)
printf ("Data Value : True \n");
else
printf ("Data Value : False \n");
break;
case ESS_ATTRMBRDT_DOUBLE:
printf ("Data Type : Numeric(Double) \n");
printf ("Data Value : %g
\n",pAttributeInfo[index].Attribute.value.dblData);
break;
case ESS_ATTRMBRDT_DATETIME:
printf ("Data Type : Date \n");
if (sts)
usDateFormat = ESS_DATEFORMAT_MMDDYYYY;
else
usDateFormat = pAttrSpecs->usDateFormat;
pTime = gmtime((time_t*)&et);
switch(usDateFormat)
{
case ESS_DATEFORMAT_MMDDYYYY:
sprintf(time_string, "MM-DD-YYYY %02i-%02i-%04i",
pTime->tm_mon+1, pTime->tm_mday,pTime->tm_year+1900);
break;
sprintf(time_string, "DD-MM-YYYY %02i-%02i-%04i",
pTime->tm_mday,pTime->tm_mon+1, pTime->tm_year+1900);
break;
}
printf ("Data Value : %s \n", time_string);
360
break;
case ESS_ATTRMBRDT_STRING:
printf ("Data Type : String \n");
printf ("Data Value : %s \n",
pAttributeInfo[index].Attribute.value.strData);
EssFree(hInst, pAttributeInfo[index].Attribute.value.strData);
break;
}
printf("\n");
}
}
if (pAttributeInfo)
EssFreeStructure(hInst, ESS_DT_STRUCT_ATTRIBUTEINFO, 1, pAttributeInfo);
return (sts);
}
See Also
l EssFreeStructure
EssGetAsyncProcLog
Gets the error log for an asynchronous data load or dimension build process.
Syntax
ESS_FUNC_M EssGetAsyncProcLog (hCtx, ErrorFileName, ErFileOverWrite);
ErrorFileName ESS_STR_T An error file name.
ErFileOverWrite ESS_BOOL_T If TRUE, overwrite the error file.
361
Notes
EssAsyncBuildDim.
Return Value
Example
See Also
l EssAsyncBuildDim
l EssAsyncImport
l EssAsyncImportASO
l EssCloseAsyncProc
EssGetAsyncProcState
Queries the state of an asynchronous process an asynchronous data load or dimension build
process.
Syntax
ESS_FUNC_M EssGetAsyncProcState (hCtx, pBldDlState);
pBldDlState ESS_PBLDDL_STATE_T Address of pointer to receive allocated process state structure.
Notes
EssAsyncBuildDim.
Return Value
Example
See Also
l EssAsyncBuildDim
l EssAsyncImport
l EssAsyncImportASO
362
l EssCloseAsyncProc
EssGetAttributeInfo
Returns attribute information for a given attribute member or dimension.
Syntax
szAttributeName; ESS_STR_T Name of the attribute member or dimension.
pAttributeInfo; “ESS_ATTRIBUTEINFO_T” on page 112 Attribute information.
Notes
After you call this function, call EssFreeStructure to free memory dynamically allocated by
this function for string type attribute information.
Access
Example
void ESS_GetAttributeInfo()
{
ESS_STS_T sts;
ESS_PATTRIBUTEINFO_T pAttributeInfo;
ESS_CHAR_T time_string[32];
struct tm* pTime;
ESS_DATETIME_T et;
/* sts = EssGetAttributeInfo(hCtx, "ounces_12", &pAttributeInfo); */

/* sts = EssGetAttributeInfo(hCtx, "ounces", &pAttributeInfo); */
/* sts = EssGetAttributeInfo(hCtx, "caffeinated_true", &pAttributeInfo); */
/* sts = EssGetAttributeInfo(hCtx, "caffeinated", &pAttributeInfo); */
sts = EssGetAttributeInfo(hCtx, "intro date_10-01-1996", &pAttributeInfo);
/* sts = EssGetAttributeInfo(hCtx, "intro date", &pAttributeInfo); */
/* sts = EssGetAttributeInfo(hCtx, "can", &pAttributeInfo); */
/* sts = EssGetAttributeInfo(hCtx, "pkg type", &pAttributeInfo); */
if(sts)
fprintf(stderr,"Error in EssGetAttributeInfo(): %ld", sts);
/* for handling time values */

et = pAttributeInfo->Attribute.value.dtData;
printf("Member name: %s\n", pAttributeInfo->MbrName);
printf("Dimension name: %s\n", pAttributeInfo->DimName);
363
/* printf("Attribute: %s\n", pAttributeInfo->Attribute); */
switch(pAttributeInfo->Attribute.usDataType)
{
case ESS_ATTRMBRDT_BOOL:
printf ("Data Type : Boolean \n");
if ( pAttributeInfo->Attribute.value.bData)
printf ("Data Value : True \n");
else
printf ("Data Value : False \n");
break;
case ESS_ATTRMBRDT_DOUBLE:
printf ("Data Type : Numeric(Double) \n");
printf ("Data Value : %g \n",pAttributeInfo->Attribute.value.dblData);
break;
case ESS_ATTRMBRDT_DATETIME:
printf ("Data Type : Date \n");
if (sts)
usDateFormat = ESS_DATEFORMAT_MMDDYYYY;
else
usDateFormat = pAttrSpecs->usDateFormat;
pTime = gmtime((time_t*)&et);
switch(usDateFormat)
{
case ESS_DATEFORMAT_MMDDYYYY:
sprintf(time_string, "MM-DD-YYYY %02i-%02i-%04i",
break;
sprintf(time_string, "DD-MM-YYYY %02i-%02i-%04i",
pTime->tm_mday,pTime->tm_mon+1, pTime->tm_year+1900);
break;
}
printf ("Data Value : %s \n", time_string);
break;
case ESS_ATTRMBRDT_STRING:
printf ("Data Type : String \n");
printf ("Data Value : %s \n", pAttributeInfo->Attribute.value.strData);
EssFree(hInst, pAttributeInfo->Attribute.value.strData);
break;
}
EssFreeStructure(hInst, ESS_DT_STRUCT_ATTRIBUTEINFO, 1, pAttributeInfo);
}
See Also
l EssFreeStructure
364
EssGetAttributeSpecifications
Retrieves attribute specifications for the outline.
Syntax
hCtx; ESS_HCTX_T API Context handle.
pAttrSpecs; “ESS_ATTRSPECS_T” on page 113 Attribute specifications.
Notes
l Set attribute specifications for the outline using

EssOtlSetAttributeSpecifications.
l Attribute specifications are used to do the following:
m Generate a long name
m Indicate the format of a datetime attribute
m Indicate a numeric attribute's bucketing type
m Provide the name of the attribute calculations dimension and the names for the values
used with it
See Table 6, “C API Attributes Terminology,” on page 96.
Access
Example
void ESS_GetAttributeSpecifications()
{
printf("\n ---------Attribute Specifications--------\n\n");

if (sts) return(sts);
365
switch(pAttrSpecs->usGenNameBy)
{
break;
break;
default:
break;
}
switch(pAttrSpecs->usUseNameOf)
{
break;
break;
break;
break;
break;
default:
break;
}
switch(pAttrSpecs->cDelimiter)
{
break;
break;
break;
default:
break;
}
switch(pAttrSpecs->usDateFormat)
{
break;
366
break;
default:
break;
}
switch(pAttrSpecs->usBucketingType)
{
break;
break;
break;
break;
default:
break;
}
printf("\n Default for TRUE : %s",pAttrSpecs->pszDefaultTrueString);

printf("\n Default for FALSE : %s",pAttrSpecs->pszDefaultFalseString);
printf("\n Default for Attr Calc : %s",pAttrSpecs->pszDefaultAttrCalcDimName);
printf("\n Default for Sum : %s",pAttrSpecs->pszDefaultSumMbrName);
printf("\n Default for Count : %s",pAttrSpecs->pszDefaultCountMbrName);
printf("\n Default for Average : %s",pAttrSpecs->pszDefaultAverageMbrName);
printf("\n Default for Min : %s",pAttrSpecs->pszDefaultMinMbrName);
printf("\n Default for Max : %s",pAttrSpecs->pszDefaultMaxMbrName);
printf("\n");
EssFreeStructure(hInst, ESS_DT_STRUCT_ATTRSPECS, 1,(ESS_PVOID_T)pAttrSpecs);

}
See Also
l EssFreeStructure
367
EssGetCalcList
Gets the list of calculation script objects that are accessible to a user.
Syntax
ESS_FUNC_M EssGetCalcList (hCtx, UserName, AppName, DbName, pAllCalcs, pCount,
ppCalcList);
UserName ESS_STR_T User name.
pAllCalcs ESS_PBOOL_T Address of a variable to receive the allow all calcs flag. If TRUE, the user can access
all calculation scripts, otherwise, they can only access those specified in the
CalcList argument.
pCount ESS_PUSHORT_T Address of variable to receive a count of the number of accessible calculation script
objects.
ppCalcList ESS_PPOBJNAME_T Address of a pointer to receive an allocated array of calculation script object names.
Notes
l In order to access any calc script objects, the specified user must have at least calculate access
to the appropriate database.
l If the pAllCalcs flag is set to TRUE, pCount is zero, and ppCalcList is NULL.
l The memory allocated for ppCalcList should be freed using EssFree.
Return Value
If successful, the user's allow all calcs setting is returned in pAllCalcs, a count of their accessible
calculation scripts objects is returned in pCount, and a list of calculation script object names is
returned in ppCalcList.
Access
the specified database, unless they are getting their own calculation list.
Example
ESS_FUNC_M
ESS_GetCalcList (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T UserName;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_BOOL_T AllCalcs;
ESS_USHORT_T Count, ind;
368
ESS_POBJNAME_T pCalcList = NULL;
UserName = "Admin";
AppName = "Sample";
DbName = "Basic";
sts = EssGetCalcList(hCtx, UserName, AppName,
DbName, &AllCalcs, &Count, &pCalcList);
if(!sts && pCalcList)
{
printf("-------- Get Calc List -----------\r\n");
for (ind = 0; ind < Count; ind ++)
printf(" %s\r\n",pCalcList[ind]);
EssFree(hInst, pCalcList);
}
return (sts);
}
See Also
l EssListObjects
l EssListUsers
l EssSetCalcList
EssGetCookie
Gets the cookie associated with the current session, if a cookie was created at initialization. For
more information, see the custom callback function, CookieCreateFunc, available with
ESS_INIT_T.
Syntax
ESS_FUNC_M EssGetCookie (ESS_HCTX_T, ESS_PPVOID_T);
ppCookie ESS_PPVOID_T Address of a pointer to receive cookie.
Return Value
If successful, returns the cookie created at initialization.
Access
Example
See the query cancellation example in the topic for ESS_INIT_T.
369
EssGetCellDrillThruReports
Gets the drill-through reports associated with a data cell as a list of URL XMLs, given the cell's
member combination.
Syntax
ESS_FUNC_M EssGetCellDrillThruReports (hCtx, noMbrs, pMbrs, nURLXML, ppURLXMLLen,
ppURLXML);
noMbrs ESS_USHORT_T Number of members in the member list pMbrs.
pMbrs ESS_PSTR_T Pointer to the list of member names (or Aliases); the array size is assumed to be
the dimension count.
nURLXML ESS_PUSHORT_T Number of URL XMLs returned.
ppURLXMLLen ESS_PPUSHORT_T Returns length of URL XML generated.
ppURLXML ESS_PPVOID_T Returns pointers to the URL XML byte stream.
Notes
The application database must be set to Active for this call. This function must be extended to
support any additional information needed by the clients.
Return Value
l If successful, gets the list of URL XMLs.
Access
l Caller must have database Read privilege (ESS_PRIV_READ) for the specified database.
EssSetActive.
Example
/* Sample Code for EssGetCellDrillThruReports */

ESS_SHORT_T numMbrs = 0;
ESS_STR_T *pMbrs = ESS_NULL;
ESS_USHORT_T numURLXML, i = 0;
ESS_USHORT_T *URLXMLLen = ESS_NULL;
ESS_PPVOID_T *URLXML = ESS_NULL;
ESS_CHAR_T pTmpXML[XML_CHAR_MAX];
/* Valid case */
numMbrs = 5;
sts = EssAlloc (hInst, sizeof(ESS_STR_T) * numMbrs , &pMbrs);
370
pMbrs[0] = "Jul";
pMbrs[1] = "100-10";
pMbrs[2] = "Actual";
pMbrs[3] = "New York";
pMbrs[4] = "Sales";
sts = EssGetCellDrillThruReports(hCtx, numMbrs, pMbrs, &numURLXML, &URLXMLLen, &URLXML);
printf("EssGetCellDrillThruReports sts: %ld\n",sts);
if(!sts)
{
printf("\nNumber of URL XML: %d", numURLXML);
for (i = 0; i < numURLXML; i++)
{
memset(pTmpXML, 0, XML_CHAR_MAX);
memcpy(pTmpXML, URLXML[i], URLXMLLen[i]);
if ( URLXML[i] != ESS_NULL )
printf("\tXML [%d] : %s\n", i, pTmpXML );
else
printf("\tXML [%d] : NULL STRING \n", i );
if ( URLXML[i] != ESS_NULL )
EssFree(hInst, URLXML[i]);
}
if ( URLXML != ESS_NULL )
EssFree(hInst, URLXML);
if ( URLXMLLen != ESS_NULL )
EssFree(hInst, URLXMLLen);
}
EssGetCurrencyRateInfo
Gets a list of structures containing rate information for all members of the tagged currency
partition dimension in the active database outline.
Syntax
ESS_FUNC_M EssGetCurrencyRateInfo (hCtx, pCount, ppRateInfo);
pCount ESS_PLONG_T Address of variable to receive the count of rate info structures.
ppRateInfo “ESS_RATEINFO_T” on page 172 Address of pointer to receive allocated array of currency rate info
structures.
Notes
l The memory allocated for ppRateInfo should be freed using EssFree.
l This function can be called for regular databases with associated currency databases.
Return Value
If successful, this function returns a count of structures in pCount, and an allocated array of
currency rate info structures in ppRateInfo.
371
Access
Example
ESS_FUNC_M
ESS_GetCrRate (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_LONG_T count, i, j;
ESS_PRATEINFO_T pRateInfoList = NULL;
ESS_CHAR_T rateStr[(2 + ESS_MBRNAMELEN) * ESS_CRDB_MAXDIMNUM];
sts = EssGetCurrencyRateInfo (hCtx, &count, &pRateInfoList);
if (!sts)
{
if (count)
{
{
rateStr[0] = '\0';
for (j = 0; j < ESS_CRDB_MAXDIMNUM; j++)
{
if (pRateInfoList[i].RateMbr[j][0])
{
if (rateStr[0])
strcat(rateStr, "->");
strcat(rateStr, pRateInfoList[i].RateMbr[j]);
}
}
if (!rateStr[0])
strcpy(rateStr, "(LOCAL)");
if (i == 0)
{
/* 1st is always DB rate */
printf ("database [%s] : %s\r\n", pRateInfoList[i].MbrName, rateStr);
}
else
{
printf ("Partition [%s] : %s\r\n", pRateInfoList[i].MbrName, rateStr);
}
}
}
}
if (pRateInfoList)
EssFree (hInst, pRateInfoList);
return (sts);
}
See Also
l EssListCurrencyDatabases
l EssSetActive
372
EssGetDatabaseAccess
Gets a list of user database access structures, which contain information about user access to
databases.
Syntax
ESS_FUNC_M EssGetDatabaseAccess (hCtx, UserName, AppName, DbName, pCount, ppUserDb);
UserName ESS_STR_T User name. If NULL, lists all users for the specified application and
database.
AppName ESS_STR_T Application name. If NULL, lists all applications and databases for the
specified user.
DbName ESS_STR_T Databasename. If NULL, lists all databases for the specified user or
application.
pCount ESS_PUSHORT_T Address of variable to receive count of user database structures.
ppUserDb “ESS_USERDB_T, Address of pointer to receive an allocated array of user database structures.
ESS_GROUPDB_T” on page
184
Notes
l If any of UserName, AppName, or DbName are NULL, they will be treated as wild cards and
all items of the appropriate type will be listed. If AppName is NULL, DbName is assumed to
also be NULL. Any two of these arguments may be NULL, but not all three.
l The Access field of the user database structure is used to represent the user's granted access
to the database, whereas the MaxAccess field represents the user's highest access from all
sources (e.g. via groups or default database access etc.).
l The memory allocated for ppUserDb should be freed using EssFree.
l Filter access privileges are equivalent to ESS_PRIV_DBLOAD privileges.
Return Value
If successful, returns a count of users/databases in pCount, and a list of user database structures
in ppUserDb.
Access
the specified database, unless they are getting their own database access information.
Example
ESS_FUNC_M
ESS_GetDatabaseAccess (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
373
ESS_STR_T UserName;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_USHORT_T ind;
ESS_PUSERDB_T UserDb = NULL;
UserName = "Admin";
AppName = "Sample";
DbName = "";
sts = EssGetDatabaseAccess(hCtx, UserName,

AppName, DbName, &Count, &UserDb);
if(!sts)
{
if(Count && UserDb)
{
printf ("\r\n-------Database Access List-------
\r\n\r\n");
{
printf("User -> %s\r\n",UserDb[ind].UserName);
printf("Application -> %s\r\n",
UserDb[ind].AppName);
printf("Database -> %s\r\n",UserDb[ind].DbName);
printf("Access -> %d\r\n",UserDb[ind].Access);
printf("MaxAccess -> %d\r\n",
UserDb[ind].MaxAccess);
printf("FilterName -> %s\r\n",
UserDb[ind].FilterName);
printf("===================================\r\n");
}
EssFree (hInst, UserDb);
}
else
printf ("\r\nDatabase list is empty\r\n\r\n");
}
return (sts);
}
See Also
l EssGetApplicationAccess
l EssGetUser
l EssListUsers
l EssSetDatabaseAccess
EssGetDatabaseAccessEx
Gets a list of user database access structures, which contain information about user access to
databases. Similar to EssGetDatabaseAccess, but can accept a user directory specification or
unique identity attribute for UserID.
374
Syntax
ESS_FUNC_M EssGetDatabaseAccessEx (hCtx, UserId, bIsIdentity, type, AppName, DbName,
pCount, ppUserDb);
UserId ESS_STR_T User or group name (input). Can be specified as name@provider or as a unique
identity attribute. If NULL, lists all users or groups for the specified database.
type ESS_USHORT_T Type of entity (input). Indicates if UserID is a group or a user. Can be one of the
following:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
AppName ESS_STR_T Application name (input). If NULL, lists all applications and databases for the
specified user.
DbName ESS_STR_T Database name (input). If NULL, lists all databases for the specified user or
application.
pCount ESS_PUSHORT_T Address of variable to receive count of user database structures (output).
ppUserDb ESS_PPUSERDBEX_T Address of pointer to receive an allocated array of user database structures
(output). The user database structure can include user directories and unique
Notes
l If any of UserID, AppName, or DbName are NULL, they will be treated as wild cards and all
items of the appropriate type will be listed. If AppName is NULL, DbName is assumed to
also be NULL. Any two of these arguments may be NULL, but not all three.
l The Access field of the user database structure is used to represent the user's granted access
to the database, whereas the MaxAccess field represents the user's highest access from all
sources (e.g. via groups or default database access etc.).
l The memory allocated for ppUserDb should be freed using EssFree.
l Filter access privileges are equivalent to ESS_PRIV_DBLOAD privileges.
Return Value
If successful, returns a count of users/databases in pCount, and a list of user database structures
in ppUserDb.
Access
the specified database, unless they are getting their own database access information.
375
Example
void DisplayUserDbInfo(ESS_PUSERDBEX_T userDb, ESS_USHORT_T count)

{
ESS_USHORT_T ind;
printf ("\n------Database Access List----\n\n");

{
printf("\tUser: %s\n", userDb[ind].UserName);
printf("\tProvider Name: %s\n", userDb[ind].ProviderName);
printf("\tConnection Param: %s\n", userDb[ind].connparam);
printf("\tApp Name: %s\n", userDb[ind].AppName);
printf("\tDb Name: %s\n", userDb[ind].DbName);
switch(userDb[ind].Access)
{
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userDb[ind].Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userDb[ind].Access);
break;
case ESS_PRIV_CALC:
printf("\tAccess: %d - ESS_PRIV_CALC\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_METAREAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", userDb[ind].Access);
376
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_METAREAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_FILTER\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userDb[ind].Access);
break;
default:
}
switch(userDb[ind].MaxAccess)
{
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userDb[ind].MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userDb[ind].MaxAccess);
break;
case ESS_PRIV_CALC:
printf("\tMax Access: %d - ESS_PRIV_CALC\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_METAREAD\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userDb[ind].MaxAccess);
377
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_METAREAD\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_FILTER\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userDb[ind].MaxAccess);
break;
default:
378
}
printf("\tFilter Name: %s\n", userDb[ind].FilterName);

printf("\n");
}
}
ESS_FUNC_M ESS_GetDatabaseAccessEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T userId;
ESS_USHORT_T type;
ESS_USHORT_T count = 0;
ESS_USERDBEX_T userDb[2];
ESS_PUSERDBEX_T pUserDb = ESS_NULL;
count = 2;
strcpy(userDb[0].UserName, "IDUser1");
strcpy(userDb[0].ProviderName, "");
strcpy(userDb[0].connparam, "");
userDb[0].type = ESS_TYPE_USER;
strcpy(userDb[0].AppName, AppName);
strcpy(userDb[0].DbName, DbName);
userDb[0].Access = ESS_PRIV_READ;
userDb[0].MaxAccess = ESS_PRIV_READ;
strcpy(userDb[1].UserName, "");
userDb[1].Access = ESS_ACCESS_ADMIN;
userDb[1].MaxAccess = ESS_ACCESS_ADMIN;
sts = EssSetDatabaseAccessEx(hCtx, count, &userDb);

printf("EssSetDatabaseAccessEx sts: %ld\n\n", sts);
userId = "IDUser1";
AppName = AppName;
DbName = DbName;
type = ESS_TYPE_USER;
bIsIdentity = ESS_TRUE;
sts = EssGetDatabaseAccessEx(hCtx, userId, bIsIdentity, type, AppName, DbName,
&count, &pUserDb);
printf("EssGetDatabaseAccessEx sts: %ld\n", sts);
if(!sts)
{
if(count && pUserDb)
{
DisplayUserDbInfo(pUserDb, count);
sts = EssFree (hInst, pUserDb);
}
379
else
}
return (sts);
}
See Also
l EssSetDatabaseAccessEx
EssGetDatabaseInfo
Gets a database's information structure, which contains non user-configurable parameters for
the database.
Syntax
ESS_FUNC_M EssGetDatabaseInfo (hCtx, AppName, DbName, ppDbInfo);
ppDbInfo “ESS_DBINFO_T” on page 118 Address of pointer to receive allocated database info structure.
Notes
l The memory allocated for the ppDBInfo structure should be freed using EssFree.
l This function can only get the information structure for a server database.
Return Value
If successful, this function returns a pointer to an allocated database info structure in
ppDbInfo.
Access
database.
Example
ESS_FUNC_M
ESS_GetDbInfo (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
380
ESS_PDBINFO_T DbInfo;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssGetDatabaseInfo (hCtx, AppName,

DbName, &DbInfo);
if (!sts)
{
if (DbInfo)
{
EssFree (hInst, DbInfo);
}
}
return(sts);
}
See Also
l EssGetDatabaseInfoEx
l EssGetDatabaseStats
EssGetDatabaseInfoEx
Retrieves information for one or more databases, which contains non user-configurable
parameters for the databases.
Syntax
ESS_FUNC_M EssGetDatabaseInfoEx (hCtx, AppName, DbName, pusCount; ppDbInfo);
AppName ESS_STR_T Name of application for which to return database information. If NULL,
returns information for all applications and databases.
DbName ESS_STR_T Name of database for which to return database information. If NULL,
returns information for all databases.
pusCount ESS_PUSHORT_T Number of information structures to be returned
ppDbInfo “ESS_DBINFO_T” on page Pointer to array of information structures.

118
Notes
l The memory allocated for the ppDBInfo structure should be freed using EssFree.
l This function can only get the information structure for server databases.
381
Return Value
If successful, this function returns an array of database information structures.
Access
database.
Example
ESS_FUNC_M
ESS_GetDatabaseInfoEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_PDBINFO_T DbInfo = NULL;
ESS_USHORT_T Count;
ESS_USHORT_T ind;
AppName = "Sample";
DbName = "";
sts = EssGetDatabaseInfoEx(hCtx, AppName, DbName,

&Count, &DbInfo);
if(!sts && DbInfo)

{
printf("\r\n------- Database Info Ex --------\r\n\r\n");
for(ind = 0; ind < Count; ind++)
{
printf("AppName: %s\r\n",DbInfo[ind].AppName);
printf("DbName: %s\r\n",DbInfo[ind].Name);
printf("DbType: %d\r\n",DbInfo[ind].DbType);
printf("Status: %d\r\n",DbInfo[ind].Status);
printf("nConnects: %d\r\n",DbInfo[ind].nConnects);
printf("nLocks: %d\r\n",DbInfo[ind].nLocks);
printf("----------------------------------\r\n\r\n");
}
EssFree(hInst, DbInfo);
}
return (sts);
}
See Also
EssGetDatabaseNote
Gets a database's note-of-the-day message.
382
Syntax
ESS_FUNC_M EssGetDatabaseNote (hCtx, AppName, DbName, pDbNote);
pDbNote ESS_PSTR_T Address of pointer to receive allocated database note string.
Notes
l The note-of-the-day message may be used to display useful information about the database
(whether data has been loaded, when it was last calculated, etc.) to users before they connect
to the database.
l The database note string will always be less than 64 KB in length.
l The database's note is set by EssSetDatabaseNote.
l The memory allocated for pDbNote should be freed using EssFree.
Return Value
If successful, returns a pointer to an allocated database note string in pDbNote.
Access
database.
See Also
l EssSetDatabaseNote
EssGetDatabaseState
Gets a database's state structure, which contains user-configurable parameters for the database.
Syntax
ESS_FUNC_M EssGetDatabaseState (hCtx, AppName, DbName, ppDbState);
ppDbState “ESS_DBSTATE_T” on page 121 Address of pointer to receive allocated database state structure.
383
Notes
l This function can get only a server database's state structure.
l The memory allocated for the ppDbState structure must be freed with EssFree.
Return Value
If successful, this function returns a pointer to an allocated database state structure in
ppDbState.
Access
To get a database's state structure, the connected user must have at least read access to the
database.
Example
ESS_FUNC_M
ESS_GetCrType (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PDBSTATE_T pDbState;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssGetDatabaseState (hCtx, AppName,
DbName, &pDbState);
if (!sts)
{
if (pDbState)
{
if (pDbState->CrDbName)
{
printf ("Currency Conversion Type Member: %s\r\n", pDbState->CrTypeMember);
if (pDbState->CrConvType ==
ESS_CRCTYPE_DIV)
printf ("Currency Conversion Type: %s\r\n", "ESS_CRCTYPE_DIV");
else if (pDbState->CrConvType ==
ESS_CRCTYPE_MULT)
printf ("Currency Conversion Type: %s\r\n", "ESS_CRCTYPE_MULT");
}
else
printf ("No Currency database is set\r\n");
EssFree (hInst, pDbState);
}
}
return (sts);
}
See Also
384
l EssSetDatabaseState
EssGetDatabaseStats
Gets a database's stats structure, which contains statistical information about the database.
Syntax
ESS_FUNC_M EssGetDatabaseStats (hCtx, AppName, DbName, ppDbStats);
ppDbStats “ESS_DBSTATS_T” on page 124 Address of pointer to receive allocated database stats structure pointer.
Notes
l This function can only be called for server databases.
l This function will load the database if it is not loaded.
l The memory allocated for ppDbStats should be freed using EssFree.
Return Value
If successful, this function returns a pointer to an allocated database stats structure in
ppDbStats.
Access
Example
ESS_FUNC_M
ESS_GetDbStats (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PDBSTATS_T pDbStats;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssGetDatabaseStats (hCtx, AppName,

DbName, &pDbStats);
if (!sts)
{
385
if (pDbStats)
{
EssFree (hInst, pDbStats);
}
}
return(sts);
}
See Also
EssGetDefaultCalc
Gets the default calculation script for the active database.
Syntax
ESS_FUNC_M EssGetDefaultCalc (hCtx, pCalcScript);
pCalcScript ESS_PSTR_T Address of pointer to receive allocated calculation script string.
Return Value
If successful, this function returns the default calculation script for the database in pCalcScript.
l The returned calculation script string will be less than 64 KB long.
l The memory allocated for pCalcScript should be freed using EssFree.
Access
This function requires callers to have at least read access (ESS_PRIV_READ) to the database,
Example
ESS_FUNC_M
ESS_GetDefaultCalc (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STR_T cstr = NULL;
sts = EssGetDefaultCalc(hCtx, &cstr);
if (!sts)
{
if (cstr)
{
printf ("Default Calc Script --\r\n%s\r\n", cstr);
EssFree (hInst, cstr);
386
}
}
return (sts);
}
See Also
l EssDefaultCalc
l EssSetActive
l EssSetDefaultCalc
EssGetDimensionInfo
Gets dimension information.
Syntax
ESS_FUNC_M EssGetDimensionInfo (hCtx, MbrName, pDims, ppDimInfo);
MbrName ESS_STR_T Member name of dimension for which to return information. If

NULL, returns information about every dimension. If member
name is invalid, error results.
pDims ESS_PULONG_T Pointer to the number of information structures returned.
ppDimInfo “ESS_DIMENSIONINFO_T” on page Pointer to an array of information structures.

126
Notes
l The constant values ESS_TTYPE_ATTRIBUTE and ESS_TTYPE_ATTRCALC for the
DimTag field of the “ESS_DIMENSIONINFO_T” on page 126 structure indicate that the
dimension is an attribute dimension.
l TheDimDataType field of the ESS_DIMENSIONINFO_T structure indicates the type of
attribute dimension.
Return Value
If successful, returns an array of dimension information structures.
Example
ESS_FUNC_M
ESS_GetDimensionInfo(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T MbrName;
ESS_ULONG_T nDims, ind;
ESS_PDIMENSIONINFO_T DimInfo = NULL;
MbrName = "Year";
387
sts = EssGetDimensionInfo(hCtx, MbrName, &nDims,
&DimInfo);
if(!sts && DimInfo)

{
printf("-------- Dimension Information --------\r\n\r\n");
for(ind = 0; ind < nDims; ind++)
{
printf("Dimension Name: %s\r\n",
DimInfo[ind].DimName);
printf("Dimension Number: %d\r\n",
DimInfo[ind].DimNumber);
switch (DimInfo[ind].DimType)
{
case ESS_DIMTYPE_DENSE:
printf("Dimension Type: %s\r\n","DENSE");
break;
default:
printf("Dimension Type: %s\r\n","SPARSE");
break;
}
printf("\r\n");
}
EssFree(hInst, DimInfo);
}
return (sts);
}
See Also
l EssBuildDimension
l EssGetApplicationInfoEx
l EssGetDatabaseInfoEx
EssGetDrillThruURL
Gets the drill-through URL within the active database outline.
Syntax
ESS_FUNC_M EssGetDrillThruURL (hCtx, URLName, &pUrl);
URLName ESS_STR_T Drill-through URL name.
Return Value
l If successful, gets the drill-through URL in the active database outline.
388
Access
EssSetActive.
Example
static void DisplayUrlDefn (ESS_PDURLINFO_T pUrls )
{
ESS_UINT_T i;
printf("\tUrlname : %s\n", pUrls->cpURLName );

if (pUrls->bIsLevel0)
printf("\tUrl Is Level-0 slice : Yes\n");
else
printf("\tUrl Is Level-0 slice : No\n");
printf("\tUrlXmlsize : %i\n", pUrls->iURLXmlSize );

printf("\tUrlXml : %s\n", (ESS_STR_T) pUrls->cpURLXml);
printf("\tNumber of drill region(s): %d\n", pUrls->iCountOfDrillRegions);

for ( i = 0; i < pUrls->iCountOfDrillRegions; i++ )
{
printf("\t\tDrillRegion[%d]: %s\n", i, pUrls->cppDrillRegions[i] );
}
printf("\n");
}
ESS_STR_T urlName = "";
/* Valid case*/
urlName = "Drill Through to EPMI";

sts = EssGetDrillThruURL(hCtx, urlName, &urlinfo);
printf("EssGetDrillThruURL sts: %ld\n",sts);
if(!sts)
DisplayUrlDefn(urlInfo);
EssFreeStructure (hInst, ESS_DT_STRUCT_URLINFO, 1, (ESS_PVOID_T)urlInfo);
EssGetEssbaseSecurityMode
Displays the type of security in use: native or Shared Services mode.
Syntax
ESS_FUNC_M EssGetEssbaseSecurityMode (hCtx, pMode);
389
pMode ESS_PSECURITY_MODE_T Address of variable to receive type of security in use.
Return Value
Example
/*
ESS_FUNC_M EssGetEssbaseSecurityMode (ESS_HCTX_T hCtx,
ESS_PSECURITY_MODE_T mode);
*/
ESS_FUNC_M ESS_SS_GetEssbaseSecurityMode(ESS_HCTX_T hCtx)
{
ESS_SECURITY_MODE_T mode;
sts = EssGetEssbaseSecurityMode(hCtx, &mode);
if(sts)
{
printf("Failed to get Essbase Security mode.\n");
}
else
{
printf("Essbase Security Mode : %d\n", mode);
}
return(sts);
}
See also an extended Appendix B
EssGetExtUser
Returns information about externally authenticated users.
Syntax
ESS_FUNC_M EssGetExtUser (hCtx, UserName, ppExtUserInfo);
UserName ESS_STR_T Name of user.
ppExtUserInfo “ESS_USERINFOEX_T” on page 189 Address of pointer to receive allocated user info structure.
Notes
The memory allocated for ppExtUserInfo should be freed using EssFree.
390
Return Value
If successful, returns the user information structure in ppExtUserInfo.
Access
(ESS_PRIV_USERCREATE) for the logged in server, unless they are getting their own user
information.
See Also
l EssListExtUsers
l EssSetExtUser
EssGetFilter
Starts getting the contents of a filter.
Syntax
ESS_FUNC_M EssGetFilter (hCtx, AppName, DbName, FilterName, pActive, pAccess);
pActive ESS_PBOOL_T Address of variable to receive filter active flag. If TRUE, the filter is currently in effect
pAccess ESS_PACCESS_T Address of variable to receive the default filter access level. For possible values, see
“Bitmask Data Types (C)” on page 90.
Notes
This call must be followed by successive calls to EssGetFilterRow to fetch the rows for the
filter.
Return Value
If successful, returns the filter active flag in pActive, and the default filter access level in pAccess.
Access
This function requires the caller to have database designer privilege (ESS_PRIV_DBDESIGN)
391
Example
ESS_FUNC_M
ESS_GetFilter (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_BOOL_T Active;
ESS_STR_T RowString = NULL;
ESS_STR_T Acc_Str;
AppName = "Sample";
DbName = "Basic";
/**************
* Get Filter *
**************/
sts = EssGetFilter(hCtx, AppName, DbName,
FilterName, &Active, &Access);
/*******************
* Get Filter Rows *
*******************/
if(!sts)
{
sts = EssGetFilterRow(hCtx, &RowString,
&Access);
if(!sts && RowString)
{
printf("%s Filter Rows\r\n",FilterName);
while(RowString)
{
switch (Access)
{
case ESS_ACCESS_NONE:
Acc_Str = "NONE";
break;
Acc_Str = "READ";
break;
default:
Acc_Str = "WRITE";
break;
}
printf("%s - %s\r\n",Acc_Str,RowString);
sts = EssGetFilterRow(hCtx, &RowString,
&Access);
}
EssFree(hInst, RowString);
}
}
return (sts);
}
392
See Also
l EssGetFilterRow
l EssListFilters
l EssSetFilter
EssGetFilterList
Gets the list of users who are assigned a filter.
Syntax
ESS_FUNC_M EssGetFilterList (hCtx, AppName, DbName, FilterName, pCount, ppUserList);
pCount ESS_PUSHORT_T Address of variable to receive count of users assigned this filter.
ppUserList ESS_PPUSERNAME_T Address of pointer to receive allocated array of user names.
Notes
The memory allocated for ppUserList should be freed using EssFree.
Return Value
If successful, returns a count of the users assigned this filter in pCount, and an array of user
names in ppUserList.
Access
Example
ESS_STS_T
ESS_GetFilterList (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_USHORT_T ind;
ESS_PUSERNAME_T UserList = NULL;
AppName = "Sample";
DbName = "Basic";
393
sts = EssGetFilterList(hCtx, AppName, DbName,

FilterName, &Count, &UserList);
if(!sts)
{
printf("--------%s User List---------\r\n\r\n",
FilterName);
if(Count && UserList)
{
printf("%s\r\n",UserList[ind]);
EssFree(hInst, UserList);
}
printf("\r\n");
}
return (sts);
}
See Also
l EssGetFilter
l EssListFilters
l EssSetFilterList
EssGetFilterRow
Gets the next row of a filter.
Syntax
ESS_FUNC_M EssGetFilterRow (hCtx, pRowString, pAccess);
pRowString ESS_PSTR_T Address of pointer to receive the next row of the filter.
pAccess ESS_PACCESS_T Address of variable to receive the access level for the filter row. Possible values are listed
in “Bitmask Data Types (C)” on page 90.
Notes
l This function should be called repeatedly after calling EssGetFilter, until a NULL row
string pointer is returned.
l The memory allocated for pRowString should be freed using EssFree.
Return Value
If successful, returns the next filter row (if any) in pRowString, and the row access level in
pAccess.
394
Access
Example
See the example of EssGetFilter.
See Also
l EssGetFilter
l EssListFilters
EssGetGlobalState
Gets the server global state structure which contains parameters for system administration.
Syntax
ESS_FUNC_M EssGetGlobalState (hCtx, ppGlobal);
ppGlobal “ESS_GLOBAL_T” on page 134 Address of pointer to receive allocated global state structure.
Notes
The memory allocated for ppGlobal should be freed using EssFree.
Return Value
If successful, returns the current state of the server global state structure in ppGlobal.
Access
This function requires the caller to be a supervisor.
Example
ESS_FUNC_M
ESS_GetGlobalState (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_PGLOBAL_T pGlobal = NULL;
sts = EssGetGlobalState(hCtx, &pGlobal);
if(!sts && pGlobal)

{
printf("--------- Global State ----------\n\n");
printf("Security->%d Logins->%d\r\n",
pGlobal->Security, pGlobal->Logins);
printf("Access->%ld Validity->%d\r\n",
pGlobal->Access, pGlobal->Validity);
395
printf("Currency->%d PwMin->%d\r\n",
pGlobal->Currency,pGlobal->PwMin);
printf("InactivityTime->%ld InactivityCheck->%ld\r\n", pGlobal->InactivityTime,
pGlobal->InactivityCheck);
EssFree(hInst, pGlobal);
}
return (sts);
}
See Also
l EssSetGlobalState
EssGetGroup
Gets a group information structure, which contains security information for the group.
Syntax
ESS_FUNC_M EssGetGroup (hCtx, GroupName, ppGroupInfo);
ppGroupInfo “ESS_USERINFO_T, ESS_GROUPINFO_T” Address of pointer to receive allocated group info

on page 186 structure (output).
Notes
The memory allocated for ppGroupInfo should be freed using EssFree.
Return Value
If successful, returns the group information structure in ppGroupInfo.
Access
See Also
l EssGetGroupInfoEx
l EssListGroups
l EssSetGroup
EssGetGroupInfoEx
Gets a group information structure, which contains security information for the group. Similar
to EssGetGroup, but can accept a user directory specification or unique identity attribute for
GroupID.
396
Syntax
ESS_FUNC_M EssGetGroupInfoEx (hCtx, GroupId, bisIdentity, ppGroupInfo);
GroupId ESS_STR_T Group name (input). Can be specified as groupname@provider or as

bIsIdentity ESS_BOOL_T Input. Indicates if GroupId is a name or an identity. If TRUE, GroupId is an

identity.
ppGroupInfo ESS_PGROUPINFOID_T Address of pointer to receive allocated group info structure (output). The
group list structure can include user directories and unique identity
attributes.
Notes
The memory allocated for ppGroupInfo should be freed using EssFree.
Return Value
If successful, returns the group information structure in ppGroupInfo.
Access
Example
void DisplayGroupsInfoEx(ESS_GROUPINFOID_T groupInfo)

{
ESS_BOOL_T isDefined = ESS_TRUE;
printf("\tUser Name: %s\n", groupInfo.Name);

printf("\tProvider Name: %s\n", groupInfo.ProviderName);
printf("\tIdentity: %s\n", groupInfo.connparam);
printf("\tDescription: %s\n", groupInfo.Description);
printf("\tEMail Identification: %s\n", groupInfo.EMailID);
if (groupInfo.LockedOut)
printf("\tLocked out: Yes\n");
else
printf("\tLocked out: No\n");
if (groupInfo.PwdChgNow)
printf("\tChange the password now: Yes\n");
else
printf("\tChange the password now: No\n");
printf("\tPassword: %s\n", groupInfo.Password);

printf("\tApplication: %s\n", groupInfo.AppName);
printf("\tDatabase: %s\n", groupInfo.DbName);
397
if (groupInfo.Login)
printf("\tLogged in: Yes\n");
else
printf("\tLogged in: No\n");
switch(groupInfo.Access)
{
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", groupInfo.Access);
break;
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", groupInfo.Access);
398
break;
case ESS_PRIV_CALC:
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", groupInfo.Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", groupInfo.Access);
break;
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", groupInfo.Access);
break;
default:
}
switch(groupInfo.MaxAccess)
{
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", groupInfo.MaxAccess);
break;
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", groupInfo.MaxAccess);
399
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", groupInfo.MaxAccess);
break;
case ESS_PRIV_CALC:
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", groupInfo.MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", groupInfo.MaxAccess);
break;
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", groupInfo.MaxAccess);
break;
default:
}
printf("\tPassword Expiration in Dates: %d\n",groupInfo.Expiration);

printf("\tFailed Login Attempts Since Then: %d\n", groupInfo.FailCount);
printf("\tLogin ID: %d\n", groupInfo.LoginId);
printf("\tProtocol: %s\n", groupInfo.protocol);
printf("\tConnection Parameter: %s\n", groupInfo.connparam);
printf( "\n");
ESS_FUNC_M ESS_GetGroupInfoEx (ESS_HCTX_T hCtx)

{
ESS_STR_T groupId;
ESS_PGROUPINFOID_T groupInfo;
groupId = "IDAdminGroup@ldap";
bisIdentity = ESS_TRUE;
sts = EssGetGroupInfoEx(hCtx, groupId, bisIdentity, &groupInfo);
printf("EssGetGroupInfoEx sts: %ld\n", sts);
if(!sts && groupInfo)
{
DisplayGroupsInfoEx(*groupInfo);
}
return (sts);
}
400
See Also
EssGetGroupList
Gets the list of users who are members of a group (or the list of groups to which a user belongs).
Syntax
ESS_FUNC_M EssGetGroupList (hCtx, GroupName, pCount, ppUserList);
GroupName ESS_USERNAME_T User name or group name.
pCount ESS_PUSHORT_T Address of variable to receive count of user names.
ppUserList ESS_PPUSERNAME_T Address of pointer to receive allocated array of user name strings.
Notes
l This function can also be used to get the list of groups to which a user belongs, by using a
user name as the GroupName argument.
l The memory allocated for ppUserList should be freed using EssFree.
Return Value
If successful, returns a count of user names in pCount, and a array of user name strings in
ppUserList.
Access
(ESS_PRIV_USERCREATE) for the logged in server, unless they are a user getting their own list
of groups.
Example
ESS_FUNC_M
ESS_ListGroupUsers (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_USHORT_T ind;
ESS_USHORT_T Items;
ESS_USERNAME_T GroupName;
strcpy(Groupname, "PowerUsers");
sts = EssGetGroupList (hCtx, GroupName, &Items, &UserList);
if (!sts)
{
if (Items && UserList)
401
{
printf ("\r\n-------%s User List-------\r\n\r\n", GroupName);
for (ind = 0; ind < Items; ind++)
{
if (UserList [ind])
printf ("%s\r\n", UserList [ind]);
}
EssFree (hInst, UserList);
}
else
printf ("\r\nUsers list is empty\r\n\r\n");
}
return (sts);
}
See Also
l EssGetGroupListEx
l EssAddToGroup
l EssListGroups
l EssSetGroupList
EssGetGroupListEx
Gets the list of users who are members of a group or the list of groups to which the user belongs.
Similar to EssGetGroupList, but can accept a user directory specification or unique identity
attribute for GroupName.
Syntax
ESS_FUNC_M EssGetGroupListEx (hCtx, GroupName, bIsIdentity, entityType, pCount,
bOutputInIds, ppUserList);
GroupName ESS_STR_T Group name or identity (input). Can be specified as groupname@provider or

as a unique identity attribute.
bIsIdentity ESS_BOOL_T Input. Indicates if GroupName is a name or an identity. If TRUE, GroupName is an

identity.
entityType ESS_USHORT_T Type of entity (input). Can be one of the following:

l ESS_TYPE_USER – Returns the list of groups to which this user belongs
l ESS_TYPE_GROUP – Returns the list of users to which this group belongs
pCount ESS_PUSHORT_T Address of variable to receive count of user names (output).
bOutputInIds ESS_BOOL_T Input. Indicates whether the output must be in identities. If TRUE, ppUserList
returns an array of identities.
402
ppUserList ESS_PSTR_T Address of pointer to receive allocated array of user name strings or identities
(output).
Notes
l This function can also be used to get the list of groups to which a user belongs, by using a
user name as the GroupName argument.
Return Value
If successful, returns a count of user names in pCount, and a array of user name strings or
identities in ppUserList.
Access
(ESS_PRIV_USERCREATE) for the logged in server, unless they are a user getting their own list
of groups.
Example

{
ESS_USHORT_T i;

{
if (UserList [i])
}
}
ESS_FUNC_M ESS_ListGroupUsers (ESS_HCTX_T hCtx, ESS_HINST_T hInst)

{
ESS_STR_T groupId;
ESS_USHORT_T type;
ESS_USHORT_T count;
groupId = "IDAdminGroup";
bisIdentity = ESS_TRUE;
type = ESS_TYPE_GROUP;
&pUserList);
if(!sts)
{
if(pUserList)
{
403
}
else
}
return (sts);
}
See Also
l EssAddToGroupEx
EssGetIBH
Creates a local log file with all index combinations for which blocks contain invalid block headers.
The database administrator can use this information to reload the datapoints that were identified
as corrupted.
Syntax
ESS_FUNC_M EssGetIBH (hCtx, destFileName);
destFileName; ESS_STR_T Name of the file in which the IBH information is to be stored at client side.
See Also
l EssLocateIBH
l EssFixIBH
EssGetLocalPath
Gets the full local file path for a specific object file on the client.
Syntax
ESS_FUNC_M EssGetLocalPath (hCtx, ObjType, AppName, DbName, ObjName, Create, pPath);
hCtx ESS_HCTX_T API context handle returned by EssCreateLocalContext.
ObjType ESS_OBJTYPE_T Object type (must be single type). See “Bitmask Data Types (C)” on page 90 for a list of
object types.
AppName ESS_STR_T Application name or NULL (ESS_NULL). If NULL, this function assumes a file name,
and returns the ObjName in pPath as is.
404
ObjName ESS_STR_T Object name or file name if AppName is NULL ObjName is not parsed for correctness;
no suffix is appended to the path.
Create ESS_BOOL_T Create directories flag. If TRUE, the appropriate application and database sub-
directories will be created if necessary. If FALSE, and the directories do not exist, an error
will be generated.
pPath ESS_PSTR_T Address of pointer to receive allocated local path name string.
Notes
The memory allocated for pPath should be freed using EssFree.
Return Value
If successful, returns the full path name of the appropriate object file in pPath.
Access
Example
ESS_VOID_T
ESS_GetLocalPath (ESS_HINST_T hInst)
{
ESS_HCTX_T hLocalCtx;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T ObjName;
ESS_BOOL_T Create;
ESS_STR_T Path;
AppName = "Sample";
DbName = "Basic";
ObjName = "Basic";
Create = ESS_TRUE;
sts = EssCreateLocalContext(hInst, NULL, NULL,
&hLocalCtx);
if(!sts && hLocalCtx)
{
sts = EssGetLocalPath(hLocalCtx, ObjType,
AppName, DbName, ObjName, Create, &Path);
if(!sts)
{
if(*Path)
{
printf("Path: %s\r\n",Path);
EssFree(hInst,Path);
}
}
405
}
if(hLocalCtx)
sts = EssDeleteLocalContext(hLocalCtx);
}
See Also
l EssCreateLocalContext
l EssListObjects
EssGetLocationAliasList
Returns a list of all currently-defined location aliases, together with lists of the host names,
application names, database names and user names to which the location aliases are mapped.
Syntax
ESS_FUNC_M EssGetLocationAliasList (hCtx, pusListCnt, ppAliasNames, ppHostNames,
ppAppNames, ppDbNames, ppUserNames);
pusListCnt; ESS_PUSHORT_T Number of location aliases returned.
ppAliasNames; ESS_PSTR_T * Location alias name buffer.
ppHostNames; ESS_PSTR_T * Host name buffer.
ppAppNames; ESS_PSTR_T * Application name buffer.
ppDbNames; ESS_PSTR_T * Database name buffer.
ppUserNames; ESS_PSTR_T * User login name buffer.
Notes
l hCtx is the only input parameter.
l pusListCnt, ppAliasNames, ppHostNames, ppAppNames, ppDbNames and ppUserNames are
output parameters; that is, values returned.
l After you call this function, you must call EssFree to free the memory used by the returned
lists.
See Also
l EssCreateLocationAlias
l EssDeleteLocationAlias
406
EssGetLogFile
Copies all or part of an application log file (appname.log) or the Essbase Server log file
(essbase.log) from the server to the client.
Syntax
ESS_FUNC_M EssGetLogFile (hCtx, AppName, TimeStamp, LocalName};
AppName ESS_STR_T Application name or NULL. If NULL, this function accesses the Essbase Server log file
(essbase.log).
TimeStamp ESS_TIME_T Time stamp, indicating date and time of earliest log file entry required. If TimeStamp is
set to 0 (zero), this function copies the entire log file.
LocalName ESS_STR_T Full path name of local destination file on client.
Notes
l TimeStamp represents the number of seconds elapsed since midnight (00:00:00) Greenwich
Mean Time on January 1, 1970. This function copies to the client only log file entries
occurring after the date & time specified by TimeStamp.
l For the locations of essbase.log and appname.log, see the Oracle Essbase Database
Administrator's Guide.
Return Value
If successful, the file is copied to the local file specified by LocalName.
Access
This function requires the caller to have application Design privilege (ESS_PRIV_APPDESIGN),
or database Design privilege (ESS_PRIV_DBDESIGN) for the specified application or any of its
databases.
Example
ESS_FUNC_M
ESS_GetLogFile (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T LocalName;
AppName = "Sample";
LocalName = "C:\\Hyperion\\products\\Essbase\\EssbaseServer\\test.log";
/* Get entire log file */

TimeStamp = 0;
sts = EssGetLogFile(hCtx, AppName, TimeStamp,

LocalName);
407
return (sts);
}
See Also
l EssDeleteLogFile
l EssLogSize
l EssWriteToLogFile
EssGetMemberCalc
Gets the calculation equation for a specific member in the active database outline.
Syntax
ESS_FUNC_M EssGetMemberCalc (hCtx, MbrName, pCalcStr, pLastCalcStr);
MbrName ESS_STR_T Member name.
pCalcStr ESS_PSTR_T Address of pointer to receive allocated member calculation string.
pLastCalcStr ESS_PSTR_T Address of pointer to receive allocated member last calculation string.
Notes
l The last calculation string is the formula used to calculate the member the last time the
database was calculated. It might be left from pCalStr if a calculation script was used to
calculate the database.
l This function checks whether the relational span Boolean is set and can determine if
members stored in attached relational data sets have calculation strings, but returns a NULL
string instead of the calculation string.
l The memory allocated for pCalcStr and pLastCalcStr should be freed using EssFree.
Return Value
If successful, this function returns the calculation string and last calculation string in pCalcStr
and pLastCalcStr.
Access
Example
ESS_FUNC_M
ESS_GetMbrCalc (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
408
ESS_STR_T calcStr, lastCalcStr;
calcStr = lastCalcStr = NULL;

sts = EssGetMemberCalc(hCtx, "Year", &calcStr, &lastCalcStr);
if (!sts)
{
if (calcStr)
{
printf ("Outline Defined Calc Equation -- [%s]\r\n", calcStr);
}
else
{
printf ("Outline Defined Calc Equation -- [Default Rollup]\r\n");
}
if (lastCalcStr)
{
printf ("Last Calculated Calc Equation -- [%s]\r\n", lastCalcStr);
}
else
{
if (calcStr)
printf ("Last Calculated Calc Equation -- [%s]\r\n", calcStr);
else
printf ("Last Calculated Calc Equation -- [Default Rollup]\r\n");
}
}
if (calcStr)
EssFree (hInst, calcStr);
if (lastCalcStr)
EssFree (hInst, lastCalcStr);
return (sts);
}
See Also
l EssGetMemberInfo
l EssSetActive
EssGetMemberInfo
Gets a structure containing information about a specific member in the active database outline.
Syntax
ESS_FUNC_M EssGetMemberInfo (hCtx, MbrName, ppMbrInfo);
MbrName ESS_STR_T Member name.
409
ppMbrInfo “ESS_MEMBERINFO_T” on page 143 Address of pointer to receive allocated member information
structure.
Notes
l Call EssFree or EssFreeStructure to free memory dynamically allocated for
ppMbrInfo.
For an attribute member of type ESS_ATTRMBRDT_STRING, you must call
EssFreeStructure to free memory dynamically allocated for ppMbrInfo. Specify
ESS_DT_STRUCT_MBRINFO as the structure ID. EssFree will not free memory
dynamically allocated for an attribute string value.
l The ESS_MBRSTS_ATTRIBUTE constant for the Status field of the
“ESS_MEMBERINFO_T” on page 143 structure indicates that the dimension or member
is an attribute dimension or attribute member.
l Two fields of the ESS_MEMBERINFO_T structure are for attributes only:
m fAttributed
m Attribute
l This function checks whether the relational span Boolean is set (set by
EssSetSpanRelationalPartition) and can return information on members in the
relational store.
l Two fields of the “ESS_MEMBERINFO_T” on page 143 structure are used only for members
in relational stores:
m fHasRelDesc
m fHasRelPartEnabled
l Two fields of the “ESS_MBRINFO_T” on page 709 structure are used only for members in
relational stores:
m fHasRelDesc
m fHasRelPartEnabled
Return Value
If successful, this function returns an allocated member information structure, ppMbrInfo. If a
member has no parent, this function returns an empty string in the ParentMbrName field of the
ESS_MEMBERINFO_T structure.
Access
Example
ESS_FUNC_M
ESS_GetMbrInfo (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
410
)
{
ESS_MEMBERINFO_T *pMbrInfo = NULL;
sts = EssGetMemberInfo(hCtx, "Profit",
&pMbrInfo);
if (!sts)
{
if (pMbrInfo)
{
EssFreeStructure(hCtx, structId, count, structPtr);
}
}
return (sts);
}
See Also
l EssCheckMemberName
l EssFreeStructure
l EssGetMemberCalc
l EssSetActive
EssGetObject
Copies an object from the server or client object system to a local file, and optionally locks it.
Syntax
ESS_FUNC_M EssGetObject (hCtx, ObjType, AppName, DbName, ObjName, LocalName, Lock);
ObjName ESS_STR_T Name of object to get.
LocalName ESS_STR_T Full path name of local destination file on client.
Lock ESS_BOOL_T Flag to control object locking. If TRUE, the server object is locked to prevent updates
by other users.
Notes
To lock an object, it must already exist on the server and not be locked by another user. Locking
is not supported on the client.
411
Return Value
If successful, the object is copied to the local file specified by LocalName.
Access
This function requires the caller to have the appropriate level of access to the specified application
and/or database containing the object (depending on the object type). To lock the object (lock
flag is TRUE), the caller must have application or Database Designer privilege
Example
ESS_FUNC_M
ESS_GetObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T ObjName;
ESS_BOOL_T Lock;
AppName = "Sample";
DbName = "Basic";
ObjName = "Basic";
LocalName = "C:\\Hyperion\\products\\Essbase\\EssbaseClient\\client\\Basic.otl";
Lock = ESS_TRUE;
sts = EssGetObject (hCtx, ObjType, AppName,

DbName, ObjName, LocalName, Lock);
return (sts);
}
See Also
l EssGetObjectInfo
l EssListObjects
l EssLockObject
l EssPutObject
l EssUnlockObject
EssGetObjectInfo
Gets information about a specific object on the server or locally on the client.
Syntax
ESS_FUNC_M EssGetObjectInfo (hCtx, ObjType, AppName, DbName, ObjName, ppObject);
412
ObjType ESS_OBJTYPE_T Object type (must be single type). Refer to “Bitmask Data Types (C)” on page 90 for
a list of possible values.
ObjName ESS_STR_T Object name.
ppObject ESS_PPOBJINFO_T Address of pointer to receive allocated object info structure.
Notes
l Outline time stamp information differs depending on whether the call to EssGetObjectInfo
is to a block storage or aggregate storage application:
m Block storage application: Returns the time stamp of the outline file that was last updated
m Aggregate storage application: Returns the system time of the outline file that was
updated by the operating system.
l The memory allocated for ppObject should be freed using EssFree.
Return Value
If successful, returns an object structure containing information about the appropriate object
in ppObject.
Access
and/or database containing the object (depending on the object type).
See Also
l EssGetObject
l EssListObjects
EssGetProcessState
Gets the current state of an asynchronous process, such as a calculate or a data import.
Syntax
ESS_FUNC_M EssGetProcessState (hCtx, pProcState);
413
pProcState “ESS_PROCSTATE_T” on page 172 Pointer to process state structure.
Notes
l Your program should call this function at regular intervals (between 5-10 seconds) until it
returns ESS_STATE_DONE in pProcState.
l Calling this function except after initiating a successful asynchronous database operation,
for example, a calculation, generates an error.
l The memory allocated for pProcState should be freed using EssFree.
Return Value
If this function is unable to get the process state, an error is returned. If the process terminates
because of an error, then its error code is returned. Otherwise, this function returns
ESS_STS_NOERR, and the current process state is given in the state structure pProcState. Values
for pProcState:
l ESS_STATE_DONE—0 = Done
l ESS_STATE_INPROGRESS—1 = In progress
l ESS_STATE_FINALSTAGE—5 = In final stage; cannot be canceled
Access
This function requires no special privilege.
Example
ESS_FUNC_M
ESS_RunCalc (ESS_HCTX_T hCtx)
{
ESS_SHORT_T isResponse;
ESS_HCTX_T hSrcCtx;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
hSrcCtx = hCtx;
AppName = "Sample";
DbName = "Basic";
FileName = "Test";
sts = EssCalcFile (hCtx, hSrcCtx, AppName,

DbName, FileName, ESS_TRUE);
if (!sts)
{
ESS_STATE_DONE))
}
414
return(sts);
}
See Also
l EssBeginCalc
l EssCalc
l EssCancelProcess
l EssImport
EssGetRuntimeSubVars
This function is implemented as an interface to a client in which a calculation script is run. This
function retrieves all of the information (name, value, and description) that is specified in the
runtime substitution variable declarations in the SET RUNTIMESUBVARS calculation
command for a specified calculation script. If a runtime substitution variable declaration
includes the <RTSV_HINT>rtsv_description</RTSV_HINT> tag, in which
rtsv_description is a string that describes the data type and data input limit for the runtime
substitution variable, this string can then be used to prompt a user to input a value at runtime
or validate input data before passing the value to the calculation script.
Syntax
ESS_FUNC_M EssGetRuntimeSubVars (hCtx, hSrcCtx AppName, DbName, FileName, pulRtSVCount,
pRtSVList);
hSrcCtx ESS_HCTX_T API context handle for the location of the calculation script file.
The calculation script file can be located on the client computer
or on the same Essbase Server as the target database.
AppName ESS_STR_T Name of the application.
DbName ESS_STR_T Name of the database in the application.
CalcScript ESS_STR_T Name of the calculation script file or a calculation string.

This argument is used with the bClientCalcFile
argument.
bClientCalcFile ESS_BOOL_T Flag indicating whether the CalcScript argument

references a client-side calculation script file (TRUE) or
calculation string (FALSE).
This argument is ignored if the calculation script file is located
on Essbase Server.
pulRtSVCount ESS_ULONG_T Address of the variable to receive the count of runtime

substitution variable structures (key/value pairs) in the
calculation script.
415
pRtSVList ESS_RUNTIMESUBVARS_DESC_T A list (array) of runtime substitution variable structures in the

calculation script. Each structure contains a runtime
substitution variable key/value pair. Optionally, each structure
can specify a string in the
<RTSV_HINT>rtsv_description</RTSV_HINT>
tag that describes the runtime substitution variable data type
and data input limit (for example, an integer not greater than
100).
The API internally allocates the array, and the API caller has the
responsibility to free the memory.
Return Value
None.
Access
A call to this function requires read privileges (ESS_PRIV_READ) for the active database.
Example
void Ess_GetRuntimeSubVars(ESS_HINST_T hInst, ESS_HCTX_T hCtx)
{
ESS_STS_T sts;
ESS_STR_T FileName = "D:\\temp\\testrt.csc"; //Client side calc file
//ESS_STR_T FileName = "SET RUNTIMESUBVARS { myCOGS; myProduct = 333; myMarket =
<RTSV_HINT> myMarket is an initialized Runtime Substitution Variables </RTSV_HINT>;
myCity= \"Sunnyvale\", \"Santa Clara\", \"San Jose\" <RTSV_HINT> list of non-numeric
values </RTSV_HINT>; myCOGS; myProduct = 333; product = 100 <RTSV_HINT> initialize to
string 100 </RTSV_HINT>; baseProduct = @LEVMBRS(\"Product\",0) <RTSV_HINT> list of
members</RTSV_HINT>; myCOGS; myProduct = 333; mySales = 777 <RTSV_HINT> uninitialized;
mySales should be specified during runtime if there is no substitution variable mySales
set at Essbase level</RTSV_HINT>; myCOGS;myProduct = 333;mySal;};FIX (\"100-10\", \"New
York\") COGS=&mySV; Sales = &mySales; ENDFIX;" ; // Client side calc string
//ESS_STR_T FileName = "testrt"; \\ server side calc file
ESS_BOOL_T Calculate = TRUE;
ESS_ULONG_T i;
ESS_ULONG_T* pulRTParamsCount = NULL;
ESS_RUNTIMESUBVARS_DESC_T* pRTParamList = NULL;
ESS_RUNTIMESUBVARS_DESC_T** ppRTParamList = NULL;
ESS_RUNTIMESUBVARS_DESC_T* pRTParams = NULL;
ESS_STS_T status;

status = EssAlloc(hInst, sizeof(ESS_ULONG_T), (ESS_PPVOID_T)&pulRTParamsCount);
memset(pulRTParamsCount, 0, sizeof(ESS_ULONG_T));
ppRTParamList= &pRTParamList;
416
//For server side calc file
sts = EssGetRuntimeSubVars(hCtx, hCtx, AppName, DbName, FileName, FALSE,
pulRTParamsCount, ppRTParamList);
//For client side calc file

sts = EssGetRuntimeSubVars(hCtx, hLocalCtx, NULL, NULL, FileName, TRUE,
//For client side calc strings

sts = EssGetRuntimeSubVars(hCtx, hLocalCtx, NULL, NULL, FileName, FALSE,
pRTParams = &pRTParamList[0];
for (i=0; i < *pulRTParamsCount; i++)

{
printf("***** information for Runtime Parameter - %d *****\n", i+1);
printf(" Param Name - %s \n", (pRTParams+i)->rtsvName);

printf(" Param Value - %s \n", (pRTParams+i)->rtsvVal);
printf(" RTP_HINT - %s \n", (pRTParams+i)->rtsvDesc);
printf("\n");
}
if(sts)
printf("API could not be executed.");
if (pulRTParamsCount)
EssFree(hInst, pulRTParamsCount);
return(status);
}
See Also
l ESS_RUNTIMESUBVARS_DESC_T
l EssCalcWithRuntimeSubVars
l EssCalcFileWithRuntimeSubVars
EssGetServerLocaleString
Gets the server locale description; for example, English_UnitedStates.US-ASCII@Default.
Syntax
ESS_FUNC_M EssGetServerLocaleString (hCtx, localeString);
localeString; ESS_PSTR_T Address of pointer to receive allocated string of server locale description.
417
Notes
The memory allocated for localeString should be freed using EssFree.
Return Value
If successful, returns the name of the server locale description in localeString.
Access
Example
ESS_FUNC_M
ESS_GetServerLocaleString (ESS_HCTX_T hCtx)
{
ESS_STR_T localeStr= NULL;
sts = EssGetServerLocaleString(hCtx, &localeStr);
if (localeStr)
{
printf("server locale: %s\r\n",localeStr);
EssFree(hInst,localeStr);
}
return sts;
}
EssGetServerMode
Returns a value indicating whether the Essbase Server is in Unicode mode or non-Unicode mode.
Syntax
ESS_FUNC_M EssGetServerMode(hCtx, *bUnicode);
bUnicode ESS_BOOL_T The returned value, bUnicode, where bUnicode can be:
l ESS_TRUE—Essbase Server is in Unicode mode. Essbase Server allows creation of
Unicode mode applications or migration of non-Unicode mode applications to
Unicode mode.
l ESS_FALSE—Essbase Server is in non-Unicode mode. Essbase Server does not allow
creation of Unicode mode applications or migration of non-Unicode mode
applications to Unicode mode.
Return Value
None.
Access
This function does not require the caller to have a special privilege.
418
See Also
l EssSetServerMode
EssGetSpoolFile
Returns a specific trigger log file for a database.
Syntax
ESS_FUNC_M EssGetSpoolFile (hCtx, AppName, DbName, SplName, LocalName);
SplName ESS_STR_T The name of a specific spool file to return.
LocalName ESS_STR_T The new name of the spool file on the server.
Return Value
If successful, returns a specific trigger spool file for a database.
Access
See Also
l EssListSpoolFiles
l EssDeleteSplFile
l EssMdxTrig
EssGetSrvOutlineInfo
Gets outline information stored on the Essbase Server. There is no requirement to open the
outline in query mode before using this function.
Syntax
ESS_FUNC_M EssGetSrvOutlineInfo (hCtx, AppName, DbName, pSvrOutlineInfo);
419
pSvrOutlineInfo “ESS_SVROTLINFO_T” on page 720 Pointer to structure containing outline information stored
on the Essbase Server.
Return Value
Example
ESS_FUNC_M ESS_GetSrvOutlineInfo()
{
ESS_STS_T sts = 0;
ESS_INT_T i;
ESS_OBJDEF_T Object;
ESS_APPNAME_T szAppName;
ESS_DBNAME_T szDbName;
ESS_OBJNAME_T szFileName;
ESS_SVROTLINFO_T SvrOutlineInfo;
memset(&Object, '\0', sizeof(Object));

Object.hCtx = hCtx;
Object.ObjType = ESS_OBJTYPE_OUTLINE;
strcpy(szAppName, "Sample");
strcpy(szDbName, "Basic");
strcpy(szFileName, "Basic");
Object.AppName = szAppName;
Object.DbName = szDbName;
Object.FileName = szFileName;
sts = EssGetSrvOutlineInfo (hCtx, szAppName, szDbName, &SvrOutlineInfo);
if (!sts)
{
printf("\nCase sensitivity is set to: %d", (SvrOutlineInfo).fCaseSensitive);
printf("\nOutline type is set to: %d", (SvrOutlineInfo).usOutlineType);
printf("\nOutline allows duplicate names is set to: %d",
(SvrOutlineInfo).fNonUniqueName);
printf("\nNumber of alias tables is: %d", (SvrOutlineInfo).usNumAliasTables);
printf("\nNames of the alias tables are:");
for (i= 0; i < (SvrOutlineInfo).usNumAliasTables; ++i)

printf("\n %s", (SvrOutlineInfo).pAliasTables[i]);
}
return sts;
}
The output of the above example is:
420
Case sensitivity is set to: 0
Outline type is set to: 0
Outline allows duplicate names is set to: 1
Number of alias tables is: 2
Names of the alias tables are:
Default
Long Names
EssGetStatBufSize
Returns a pointer to the size of the buffer needed for the performance statistics tables retrieved
by EssDumpPerfStats.
Syntax
pBufSize; ESS_PULONG_T Pointer to the size of the buffer needed for the character array that will hold the
performance statistics tables.
Notes
l Before you call EssDumpPerfStats, call this function to ascertain how much memory to
allocate for the performance statistics tables at the address pointed to by pStatBuf.
l The buffer size pointed to by pBufSize is 0 if performance statistics have never been enabled;
that is, if persistence in EssResetPerfStats has never been set to 4.
Return Value
l If successful,
m This function returns 0.
m pBufSize contains a pointer to the size of the buffer needed for the character array that
will hold the performance statistics tables retrieved by EssDumpPerfStats.
l For more information on performance statistics tables, see the topic “Performance Statistics
in MaxL”, in the Oracle Essbase Technical Reference.
Access
Example
For a code example that calls EssGetStatBufSize, see the example in EssDumpPerfStats.
See Also
l EssDumpPerfStats
421
l EssResetPerfStats
EssGetString
Gets a string of data from the active database. This function should be called after EssReport
or EssEndReport if data is returned.
Syntax
ESS_FUNC_M EssGetString (hCtx, pString);
pString ESS_PSTR_T Address of pointer to receive allocated returned data string.
Notes
l Calling this function other than after successfully executing a report will generate an error.
l The returned string will be less than 64 KB long.
l Always include the carriage return/line feed with this command or errors will result.
l You must call this function until it returns a NULL string.
l The memory allocated for pString should be freed using EssFree.
Return Value
An allocated pointer to the data string is returned in pString. This pointer will be NULL if there
is no more data to be returned.
Access
Example
ESS_FUNC_M
ESS_HINST_T hInst
)
{
if (!sts)
if (!sts)
/**************
* Get report *
**************/
if (!sts)
422
{
}
printf ("\r\n");
return(sts);
}
See Also
l EssEndReport
l EssReport
EssGetUser
Gets a user information structure, which contains security information for the user.
Syntax
ESS_FUNC_M EssGetUser (hCtx, UserName, ppUserInfo);
ppUserInfo “ESS_USERINFO_T, ESS_GROUPINFO_T” Address of pointer to receive allocated user info structure.
on page 186
Notes
The memory allocated for ppUserInfo should be freed using EssFree.
Return Value
If successful, returns the user information structure in ppUserInfo.
Access
information.
Example
ESS_FUNC_M
ESS_GetUserInfo (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PUSERINFO_T User = NULL;
423
sts = EssGetUser (hCtx, "Jim Smith", &User);
if (!sts)
{
if (User)
EssFree (hInst, User);
}
return (sts);
}
See Also
l EssGetUserInfoEx
l EssListUsers
l EssSetUser
EssGetUserEx
Gets a user information structure, which contains security information for the user.
Syntax
ESS_FUNC_M EssGetUserEx (hCtx, UserName, ppUserInfo);
ppUserInfoEx “ESS_USERINFOEX_T” on page 189 Address of pointer to receive info structure of externally
authenticated user.
Notes
The memory allocated for ppUserInfo should be freed using EssFree.
Return Value
If successful, returns the user information structure in ppUserInfo.
Access
information.
Example
ESS_FUNC_M
ESS_GetUserInfo (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
424
sts = EssGetUserEx (hCtx, "Jim Smith", &User);

if (!sts)
{
if (User)
}
return (sts);
}
See Also
l EssCreateExtUser
l EssListUsers
l EssSetUser
l EssSetUserEx
EssGetUserInfoEx
Gets a user information structure, which contains security information for the user. Similar to
EssGetUser, but can accept a user directory specification or unique identity attribute for
UserID.
Syntax
ESS_FUNC_M EssGetUserInfoEx (hCtx, UserId, bIsIdentity, ppUserInfo);
UserName ESS_STR_T User name (input). Can be specified as username@provider or as a unique

identity attribute.
ppUserInfo ESS_PUSERINFOID_T Address of pointer to receive allocated user info structure (output). The user list
structure can include user directories and unique identity attributes.
Notes
The memory allocated for ppUserpInfo should be freed using EssFree.
Return Value
If successful, returns the user information structure in ppUserInfo
Access
425
Example
void DisplayUserInfoID(ESS_PUSERINFOID_T userInfo)

{
printf("\tUser Name: %s\n", userInfo->Name);

printf("\tProvider Name: %s\n", userInfo->ProviderName);
printf("\tConnparam: %s\n", userInfo->connparam);
printf("\tDescription: %s\n", userInfo->Description);
printf("\tEMail Identification: %s\n", userInfo->EMailID);
if (userInfo->LockedOut)
else
if (userInfo->PwdChgNow)
else
printf( "\tConnected Application: %s\n", userInfo->AppName);

printf( "\tConnected Database: %s\n", userInfo->DbName);
if (userInfo->Login)
else
switch(userInfo->Access)
{
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", userInfo->Access);
break;
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userInfo->Access);
break;
426
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userInfo->Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userInfo->Access);
break;
case ESS_PRIV_CALC:
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userInfo->Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userInfo->Access);
break;
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userInfo->Access);
break;
default:
}
switch(userInfo->MaxAccess)
{
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", userInfo->MaxAccess);
break;
break;
427
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userInfo->MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userInfo->MaxAccess);
break;
case ESS_PRIV_CALC:
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userInfo->MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userInfo->MaxAccess);
break;
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userInfo->MaxAccess);
break;
default:
}
printf("\tPassword Expiration in Dates: %d\n",userInfo->Expiration);

//EssSdCTime(NULL, userInfo->LastLogin, sizeof(time_string), time_string);
428
//printf("\tLast Successful Login: %s\n", time_string);
printf("\tFailed Login Attempts Since Then: %d\n", userInfo->FailCount);
printf("\tLogin ID: %d\n", userInfo->LoginId);
printf( "\n");
}
ESS_FUNC_M ESS_GetUserInfoEx (ESS_HCTX_T hCtx)
{
ESS_STR_T userId;
ESS_PUSERINFOID_T userInfo = NULL;
bUsingIdentity = ESS_TRUE;
sts = EssGetUserInfoEx (hCtx, userId, bUsingIdentity, &userInfo);
printf("EssGetUserInfoEx sts: %ld\n", sts);
if (userInfo)
{
DisplayUserInfoID(userInfo);
}
return (sts);
}
See Also
EssGetUserType
Enables you to find the application access type for a user.
Syntax
ESS_FUNC_M EssGetUserType (hCtx, UserName, UserType)
UserType ESS_PUSER_TYPE_T Application access type defined for the UserName specified.
Return Value
Returns the status of the API.
Example
ESS_FUNC_M
ESS_GetUserType (ESS_HCTX_T hCtx)
{
429
ESS_STR_T UserName="jsmith";
ESS_PUSER_TYPE_T UserType;
sts = EssGetUserType (hCtx, UserName, UserType);

printf("user type for the user %s is %d\n", UserName, *UserType);
return (sts);
}
See Also
l EssSetUserType
EssGetVariable
Retrieves the value of a substitution variable.
Syntax
ESS_FUNC_M EssGetVariable (hCtx, pVariable);
pVariable “ESS_VARIABLE_T” on page 191 The pointer to the structure containing the description of the specified
substitution variable.
Return Value
If successful, this function returns the value of the substitution variable in the VarValue field of
structure ESS_VARIABLE_T.
Example
/*
** ESS_GetVariable() gets the substitution variable value using
** the API function EssGetVariable.
*/
ESS_FUNC_M
ESS_GetVariable (ESS_HCTX_T hCtx)
{
printf("\n ***************************************");
printf("\n **** An example of using EssGetVariable");
printf("\n ***************************************");
/********************************/
/* Get the Value of QuarterName */
/********************************/
sts = EssGetVariable(hCtx, &Variable);
430
{
printf("\n------- Substitution Variable 'QuarterName' Information \n");
printf("Variable name : %s\n", Variable.VarName);
printf("Server name : %s\n", Variable.Server);
printf("Application name : %s\n", Variable.AppName);
printf("Database name : %s\n", Variable.DbName);
printf("Variable value : %s\n\n", Variable.VarValue);
}
/***************************************************************/
/* Get the Value of MarketName at the level of the Server/App */
/***************************************************************/
{
{
printf("\n------- Substitution Variable 'MarketName' Information \n");
}
}
/***********************************************************/
/* Get the Value of MarketName at the level of the Server */
/***********************************************************/
{
{
printf("\n------- Substitution Variable 'MarketName' Information \n");
}
}
printf("\n --> No Errors in EssGetVariable\n\n\n");
else
printf("\n --> Error in EssGetVariable number: %d\n\n\n", sts);
return (sts);
} /* End ESS_GetVariable */
431
Output
***************************************
**** An example of using EssGetVariable
***************************************
------- Substitution Variable 'QuarterName' Information
Variable name : QuarterName
Server name : Local
Application name : Sample
Database name : Basic
Variable value : Qtr2
------- Substitution Variable 'MarketName' Information

Variable name : MarketName
Server name : Local
Database name :
Variable value : East
------- Substitution Variable 'MarketName' Information

Server name : Local
Application name :
Database name :
Variable value : Market
--> No Errors in EssGetVariable
See Also
l EssCreateVariable
l EssDeleteVariable
l EssListVariables
EssGetVersion
Gets the full version number of the connected Essbase Server, in the form
Release.Version.Revision, e.g. 11.1.2.
Syntax
ESS_FUNC_M EssGetVersion (hCtx, pRelease, pVersion, pRevision);
pRelease ESS_PUSHORT_T Address of variable to receive release number.
pVersion ESS_PUSHORT_T Address of variable to receive version number.
pRevision ESS_PUSHORT_T Address of variable to receive revision number.
432
Notes
You can call this function after connecting to a server, to ensure that the Essbase Server version
supports all the features used by your program.
Return Value
If successful, returns the full incremental Essbase version number in pRelease, pVersion and
pRevision.
Access
Example
ESS_FUNC_M
ESS_GetVersion (ESS_HCTX_T hCtx)
{
ESS_USHORT_T Release;
ESS_USHORT_T Version;
ESS_USHORT_T Revision;
sts = EssGetVersion (hCtx, &Release, &Version,

&Revision);
if (!sts)
{
printf ("\r\nEssbase Application Server - Version %d.%d.%d\r\n", Release, Version,
Revision);
}
return (sts);
}
See Also
l EssInit
l EssGetAPIVersion
EssImport
Allows importing data from different sources to the Essbase Server.
Syntax
ESS_FUNC_M EssImport (hCtx, pRules, pData, ppMbrError, pMbrUser, abortOnError);
pRules “ESS_OBJDEF_T” on page Pointer to the rules file object definition structure.
145
pData “ESS_OBJDEF_T” on page Pointer to the data file object definition structure.
145
433
ppMbrError ESS_PPMBRERR_T Pointer to linked list of errors contained in ESS_MBRERR_T. Possible

errors are:
l ESS_MBRERR_BADDIM
l ESS_MBRERR_BADGEN
l ESS_MBRERR_UNKNOWN
l ESS_MBRERR_BADACCESS
l ESS_MBRERR_BADSYNTAX
pMbrUser “ESS_MBRUSER_T” on Pointer to the SQL user structure (if data source is a SQL database). A
page 142 NULL SQL user structure indicates a non SQL data source.
abortOnError ESS_USHORT_T If TRUE, import stops on the first error. Otherwise, it continues.
Notes
l For a non SQL source, if the AppName and DbName fields in ESS_OBJDEF_T structures
for pRules and pData are NULL, hCtx must be a local context handle, and the
ESS_OBJDEF_T FileName field must contain the fully qualified path to the file.
l If a local object is used, EssCreateLocalContext must be called first.
Return Value
Access
Example
ESS_FUNC_M
ESS_Import(ESS_HCTX_T hCtx)
{
ESS_OBJDEF_T Rules;
ESS_OBJDEF_T Data;
ESS_MBRUSER_T User;
ESS_PMBRERR_T pMbrError = NULL;
Data.hCtx = hCtx;
Data.AppName = "Olap";
Data.DbName = "Demo";
Data.FileName = "Actuals";
Rules.hCtx = hCtx;
Rules.AppName = "Olap";
Rules.DbName = "Demo";
434
Rules.FileName = "Actmap";
/**********************/
/* Running conditions */
/**********************/
sts = EssImport (hCtx, &Rules, &Data, &pMbrError,

NULL, isAbortOnError);
if(pMbrError)
EssFreeMbrErr(hCtx, pMbrError);
/*******************************************************************/
/* */
/* When a SQL data source is defined in the rules file, define */
/* the variables in the ESS_OBJDEF_T Data structure as follows: */
/* Data.hCtx = hCtx; */
/* Data.AppName = NULL; */
/* Data.DbName = NULL; */
/* Data.ObjType = ESS_OBJTYPE_NONE; */
/* Data.FileName = NULL; */
/* */
/* Also, provide strings for the variables in the ESS_MBRUSER_T */
/* User structure; for example: */
/* User.User = "Dbusernm"; */
/* User.Password = "Dbpasswd"; */
/* */
/* Use a blank string for User and Password, if the SQL source */
/* does not require user and password information; for example: */
/* User.User = ""; */
/* User.Password = ""; */
/* */
/* Also, define sts as follows: */
/* sts = EssImport (hCtx, &Rules, &Data, &pMbrError, */
/* &User, isAbortOnError); */
/* */
/*******************************************************************/
}
See Also
l EssExport
l EssBuildDimension
l EssFreeMbrErr
EssImportASO
Allows importing data from different sources to an Essbase aggregate storage database.
Syntax
ESS_FUNC_M EssImportASO (hCtx, pRules, pData, ppMbrError, pUser, usabortOnError,
ulBufferId);
435
pRules “ESS_OBJDEF_T” on page Pointer to the rules file object definition structure.
145
pData “ESS_OBJDEF_T” on page Pointer to the data file object definition structure.
145
ppMbrError ESS_PPMBRERR_T Pointer to linked list of errors contained in ESS_MBRERR_T. Possible

errors are:
l ESS_MBRERR_BADDIM
l ESS_MBRERR_BADGEN
l ESS_MBRERR_UNKNOWN
l ESS_MBRERR_BADACCESS
l ESS_MBRERR_BADSYNTAX
pUser “ESS_MBRUSER_T” on Pointer to the SQL user structure (if data source is a SQL database). A
page 142 NULL SQL user structure indicates a non SQL data source.
usabortOnError ESS_USHORT_T If TRUE, import stops on the first error. Otherwise, it continues.
ulBufferId ESS_ULONG_T ID of a data load buffer (a number between 1 and 999,999). To destroy
a buffer before a data load is complete, you must use the same
ulBufferId number that was used to initialize the buffer.
Notes
l For a non SQL source, if the AppName and DbName fields in ESS_OBJDEF_T structures
for pRules and pData are NULL, hCtx must be a local context handle, and the
ESS_OBJDEF_T FileName field must contain the fully qualified path to the file.
l If a local object is used, EssCreateLocalContext must be called first.
Return Value
Access
Example
void TestImportASO(ESS_HCTX_T hCtx, ESS_STR_T AppName, ESS_STR_T DbName)
{
ESS_OBJDEF_T Rules;
ESS_OBJDEF_T Data;
436
ESS_ULONG_T ulSize;
ulSize = 100;
ulBufferId = 10;
ulDuplicateAggregationMethod, ulOptionsFlags, ulSize);
/* Server object */
Rules.hCtx = hCtx;
Rules.AppName = AppName;
Rules.DbName = DbName;
Rules.FileName = "Dataload";
Data.hCtx = hCtx;
Data.AppName = AppName;
Data.DbName = DbName;
Data.FileName = "Dataload";
sts = EssImportASO (hCtx, &Rules, &Data, &pMbrErr, pMbrUser,

isAbortOnError, ulBufferId);
printf("EssImportASO sts: %ld\n",sts);
if(pMbrErr)
EssFreeMbrErr(hCtx, pMbrErr);
/* Commit and delete the buffer */

ulBufferCnt = 1;
printf("\nCommit data to the main slice:\n");
sts = EssLoadBufferTerm(hCtx, AppName, DbName, ulBufferCnt,
ulBufferIdAry, ulCommitType, ulActionType, ulOptions);
}
See Also
l EssLoadBufferInit
l EssSendString
l EssEndDataload
l EssLoadBufferTerm
l EssUpdateFileASO
437
EssIncrementalBuildDim
Builds dimensions with the specified rules file and data source. Can be called multiple times
within the incremental dimension build protocol.
EssBeginIncrementalBuildDim must be called before this function gets called.
Syntax
ESS_FUNC_M EssIncrementalBuildDim(hCtx, RulesObj, DataObj, MbrUser, ErrorName,
bOverwrite, usBuildOption, szTmpOtlFile)
DataObj ESS_POBJDEF_T Pointer to data file object definition structure.
MbrUser ESS_PMBRUSER_T SQL user structure (if data source is SQL database).
A NULL SQL user structure indicates a non SQL data source.


Build members only.
szTmpOtlFile ESS_STR_T The temp outline file name. Essbase creates a temporary outline file with
extension .otb if the resulting outline in this round of dimension build has
outline verification errors.
Return Value
Example
See EssBeginIncrementalBuildDim.
438
See Also
EssInit
Initializes the API and message database.
Syntax
ESS_FUNC_M EssInit (pInitStruct, phInstance);
pInitStruct “ESS_INIT_T” on page 135 Pointer to API initialization structure.
phInstance ESS_PHINST_T Pointer to Essbase API instance handle.
Notes
l You must call this function before any other Essbase API functions.
l If any field in the initialization structure is NULL or zero (as appropriate), the API uses a
default value for those parameters.
Return Value
The ESS_INIT_T structure passed to this function includes a number of initialization
parameters, including the name of the message database, the maximum size of client buffer that
can be allocated, pointers to the user-defined memory free allocation, error callback functions,
the name and location of your help file, and version number.
This function returns the phInstance instance handle that allows multiple applications to access
the API independently (for DLLs only). The instance handle should be preserved and passed to
EssLogin, EssTerm, and the memory allocation functions.
Access
Example
ESS_VOID_T ESS_Init()
{
ESS_HINST_T hInst;
/* structure */
{
USER, /* user-defined message context */
439
"C:\\Essbase", /* local path */
NULL, /* error handling function pointer */
NULL, /* Reserved for internal use. */
/* Set to NULL */
};
/* Initialize the API */
if ((sts = EssInit (&InitStruct, &hInst)) != ESS_STS_NOERR)
{
/* error initializing API */
exit ((ESS_USHORT_T) sts);
}
See Also
l EssLogin
l EssAutoLogin
l EssTerm
EssKillRequest
Terminates specific Essbase user sessions or requests.
Syntax
ESS_FUNC_M EssKillRequest (hCtx, pRequestInfoStruct);
pRequestInfoStruct ESS_PREQUESTINFO_T Pointer to the Request Information structure.
Notes
This function uses the information in “ESS_REQUESTINFO_T” on page 173 regarding current
sessions and requests to terminate a specific user session. This function can also be used to
terminate (without logging out the user) any active requests being made to an application, a
database, or the system during a user session.
A session is the time in seconds between an Essbase user's login and logout.
This function terminates the sessions/requests specified by the UserName, AppName, and
DbName specified in the ESS_REQUESTINFO_T structure. If those fields are null, this function
440
terminates all sessions/requests initiated by this process (user). The application program is
responsible for allocating and freeing the memory used by ESS_REQUESTINFO_T.
To disconnect your own active request (query cancellation), set up a custom callback function
as described in the topic for the Essbase initialization structure. See ESS_INIT_T.
Return Value
Example
#include
#include
ESS_FUNC_M ESS_ListRequest ()
{
ESS_HCTX_T hCtx;
ESS_USHORT_T Items;
ESS_HINST_T hInst ;
ESS_USHORT_T numRequest;
ESS_PREQUESTINFO_T requestInfo;

/* structure */
{
NULL, /* user-defined message context */
NULL, /* local path */
/* Set to NULL */
};
EssInit (&InitStruct, &hInst);
sts = EssLogin (hInst, "local", "admin", "password", &Items, &pAppsDbs, &hCtx);
sts = EssSetActive ( hCtx, "sample", "basic", &Access );
sts = EssListRequests( hCtx, NULL, NULL, NULL, &numRequest, &requestInfo);
printf ( "Total requests on the server %d\n", numRequest );
if ( !sts && requestInfo )
441
{
ESS_USHORT_T index = 0;
while ( index < numRequest )

{
printf ( "login ID = %ul\n", requestInfo[index].LoginId );
printf ( "user name = %s\n", requestInfo[index].UserName );
printf ( "login machine = %s\n", requestInfo[index].LoginSourceMachine );
printf ( "AppName = %s\n", requestInfo[index].AppName );
printf ( "DbName = %s\n", requestInfo[index].DbName );
printf ( "DbRequestCode = %u\n", requestInfo[index].DbRequestCode );
printf ( "RequestString = %s\n", requestInfo[index].RequestString );
printf ( "TimeStarted = %ul\n", requestInfo[index].TimeStarted );
printf ( "State = %d\n", requestInfo[index].State );
printf ( "\n\n--------------------------------------\n\n",
requestInfo[index].State );
sts = EssKillRequest (hCtx, &requestInfo[index] );
index++;
}
EssFree ( hInst, requestInfo );

}
EssLogout (hCtx);
EssTerm (hInst);
return(sts);
}
void main()
{
ESS_ListRequest ();
}
See Also
l EssKillRequestEx
l EssListRequests
l “ESS_REQUESTINFO_T” on page 173
l “ESS_REQ_STATE_T” on page 179
EssKillRequestEx
Terminates specific Essbase user sessions or requests. Similar to EssKillRequest, except the
input structure can include user directories and unique identity attributes.
Syntax
ESS_FUNC_M EssKillRequestEx (hCtx, pRequestInfoStruct);
442
pRequestInfoStruct ESS_PREQUESTINFOEX_T Pointer to the Request Information structure (input).
Notes
This function uses the information in ESS_REQUESTINFOEX_T regarding current sessions
and requests to terminate a specific user session. This function can also be used to terminate
(without logging out the user) any active requests being made to an application, a database, or
the system during a user session.
A session is the time in seconds between an Essbase user's login and logout.
This function terminates the sessions/requests specified by the UserName, AppName, and
DbName specified in the ESS_REQUESTINFOEX_T structure. If those fields are null, this
function terminates all sessions/requests initiated by this process (user). The application
program is responsible for allocating and freeing the memory used by
ESS_REQUESTINFOEX_T.
To disconnect your own active request (query cancellation), set up a custom callback function
as described in the topic for the Essbase initialization structure. See ESS_INIT_T.
Return Value
Example
void ListRequestsEx ()
{
ESS_STR_T userId;
ESS_PREQUESTINFOEX_T requestInfo;
userId = "admin";
sts = EssListRequestsEx(hCtx, userId, bIsIdentity, "Sample", "Sample1", &numRequest,
&requestInfo);
printf("\nEssListRequestsEx sts: %ld\n", sts);
printf ( "Total requests on the server: %d\n", numRequest );
{
{
443
printf ( "\n\n--------------------------------------\n\n",
sts = EssKillRequestEx (hCtx, &requestInfo[index] );
index++;
}

}
userId = " native://nvid=f0ed2a6d7fb07688:5a342200:1265973105c:-7f46?USER ";

&requestInfo);
{
{
printf ( "\n\n--------------------------------------\n\n",
index++;
}

}
}
See Also
l EssListRequestsEx
EssListAliases
Lists all the alias tables in the active database.
Syntax
ESS_FUNC_M EssListAliases (hCtx, pCount ppAliasList);
444
pCount ESS_PUSHORT_T Address of variable to receive count of alias tables.
ppAliasList ESS_PPALIASNAME_T Address of pointer to receive an allocated array of alias table names.
Notes
The memory allocated for ppAliasList should be freed using EssFree.
Return Value
If successful, this function returns a count of alias tables in pCount, and an allocated array of
alias table names in ppAliasList.
Access
and to have selected it as the active database using EssSetActive.
Example
ESS_FUNC_M
ESS_ListAliases (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_USHORT_T Count;
ESS_USHORT_T ind;
ESS_PALIASNAME_T Altlist = NULL;
sts = EssListAliases (hCtx, &Count, &Altlist);

if (!sts)
{
if (Count && Altlist)
{
printf ("\r\n-----List of Aliases-----\r\n\r\n");

{
if (Altlist [ind] != NULL)
printf ("%s\r\n", Altlist[ind]);
}
EssFree (hInst, Altlist);
}
else
printf ("\r\nAlias List is Empty\r\n\r\n");
}
return (sts);
}
See Also
l EssDisplayAlias
445
l EssSetActive
EssListApplications
Lists all applications which are accessible to the caller.
Syntax
ESS_FUNC_M EssListApplications (hCtx, pCount, ppAppList);
pCount ESS_PUSHORT_T Address of variable to receive count of returned applications.
ppAppList ESS_PPAPPNAME_T Address of pointer to receive allocated array of application name strings.
Notes
The memory allocated for ppAppList must be freed using EssFree.
Return Value
If successful, this function returns a count of the number of accessible applications in pCount,
and an array of application name strings in ppAppList. There are 'count' number of items in the
array.
Access
This function requires no special privileges; note however that server applications will only be
listed if the caller has access to them.
Example
ESS_FUNC_M
ESS_ListApps (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PAPPNAME_T strp = NULL;
ESS_USHORT_T Items;
ESS_USHORT_T ind;
sts = EssListApplications (hCtx, &Items, &strp);

if (!sts)
{
if (Items && strp)
{
printf ("Applications availables\r\n");
{
if (strp [ind] != NULL)
printf ("%s\r\n", strp [ind]);
}
446
EssFree (hInst, strp);
}
else
printf ("\r\nApplication List is Empty\r\n\r\n");
}
printf ("\r\n");
return (sts);
}
See Also
l EssListDatabases
l EssListObjects
EssListCalcFunctions
Lists all calculator functions available in the active application. The list of available functions
includes all native functions and all custom-defined functions (CDFs) and custom-defined
macros (CDMs).
Syntax
ESS_FUNC_M EssListCalcFunctions (hCtx, pCalcFunc);
pCalcFunc ESS_PSTR_T Pointer to the string containing the available calculator functions. The string is in the form
of XML.
Notes
This function requires supervisor privilege (usually granted to the administrator). The user must
also have database access to receive this list. To avoid an error, the user must have both supervisor
privilege and access to the database to run a program that calls this function.
The contents of the string returned by EssGetCalcList is formatted as XML and must be
either rendered in an XML utility or parsed to display only the actual text. All XML tags are
enclosed in angle brackets (for example, <xml_tag>).
Here is a pared-down example of a typical XML output file:
ESSBASE API v.62000
1051034: Logging in user admin
1051035: Last login on Tuesday, May 22, 2001 10:31:19 AM
<list>
<group name="Boolean">
<function>
<name><![CDATA[@ISACCTYPE]]></name>
<syntax>
<![CDATA[@ISACCTYPE(tag)]]>
</syntax>
<comment>
<![CDATA[returns TRUE if the current member has the associated accounts tag]]>
447
</comment>
</function>
</group>
<group name="Relationship Functions">
<function>
<name><![CDATA[@ANCESTVAL]]></name>
<syntax>
<![CDATA[@ANCESTVAL (dimName, genLevNum [, mbrName])]]>
</syntax>
<comment>
<![CDATA[returns the ancestor values of a specified member combination]]>
</comment>
</group>
<group name="Custom">
</group>
</list>
Return Value
Example
#include <iostream.h>
#include <fstream.h>
#include "windows.h"
#include "essbase.h"
#include "essapi.h"
#include "essotl.h"
#include "stdio.h"
/* globals - handles to different ESS objects */
ESS_HINST_T hInst = 0;
ESS_HCTX_T hCtx = 0;
ESS_HOUTLINE_T hOutline = 0;
/* end globals */
/* forward declarations of functions */

void apiInit();
void apiTerm();
ESS_STS_T apiAutoLogin();
ESS_STS_T apiLogout();
/* end forward declarations */
ESS_FUNC_M MessageHandler (ESS_PVOID_T UserContext, /* user context pointer

*/
ESS_LONG_T MessageNumber, /* Essbase message
number */
ESS_USHORT_T Level, /* message level */
ESS_STR_T LogString, /* message log string
448
*/
ESS_STR_T MessageString /* message string */)
{
printf( "%d: %s\n", MessageNumber, MessageString );
return 0;
}
void apiInit()
{
ESS_STS_T sts;
ESS_INIT_T InitStruct = {
ESS_API_VERSION,
NULL,
0L,
255,
NULL,
NULL,
NULL,
NULL,
NULL,
(ESS_PFUNC_T)MessageHandler,
NULL,
0L
};
printf( "ESSBASE API v.%x\n", ESS_API_VERSION );

{
printf( "API init failure: %d\n", sts);
exit(1);
}
ESS_STS_T apiAutoLogin ()
{
ESS_CHAR_T SvrName[ESS_SVRNAMELEN];
ESS_CHAR_T UserName[ESS_USERNAMELEN];
ESS_CHAR_T Password[ESS_PASSWORDLEN];
ESS_USHORT_T Option;
ESS_ACCESS_T Access ;
/* Initialize parameters */
strcpy(SvrName,"localhost");
strcpy(UserName, "");
strcpy(Password, "");
strcpy(szAppName, "");
strcpy(szDbName, "");
Option = AUTO_DEFAULT;
/* Login to Essbase Server */

return EssAutoLogin (hInst, SvrName, UserName, Password,
szAppName, szDbName, Option, &Access, &hCtx);
449
}
void apiTerm()
{
if ( hCtx )
sts = apiLogout();
if ( !sts && hInst )

sts = EssTerm(hInst);
if ( sts )
{
printf( "API shutdown failure: %d\n", sts );
exit(1);
}
}
ESS_STS_T apiLogout()
{
return EssLogout(hCtx);
}
int main(int argc, char **argv)

{
ESS_STS_T status;
ESS_STR_T pszCalcFunctionList;
apiInit();
status = apiAutoLogin();
if ( status )
return 1;
status = EssListCalcFunctions( hCtx, &pszCalcFunctionList );

if ( status )
return 1;
printf( "%s\n", pszCalcFunctionList );
apiTerm();
return 0;
}
See Also
l EssGetFilterList
EssListConnections
Lists all users who are connected to the currently logged in server or application.
Syntax
ESS_FUNC_M EssListConnections (hCtx, pCount, ppUserList);
450
pCount ESS_PUSHORT_T Variable to receive count of users.
ppUserList “ESS_USERINFO_T, Pointer to an array of user information structures. This array is

ESS_GROUPINFO_T” on page 186 allocated by the API.
Notes
l pCount contains the number of elements in the ppUserList array.
l If hCtx is a Supervisor, ppUserList is a list of users logged in to the server. If hCtx is an
Application Designer, ppUserList is a list of users connected to any application for which
hCtx is an Application Designer.
l Use EssFree to free the buffer allocated for ppUserList.
Return Value
Returns 0 if successful.
Access
This function requires the caller to have Supervisor or Application Designer privilege.
Example
ESS_FUNC_M ESS_ListUserConnections (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_USHORT_T usrcnt;
ESS_PUSERINFO_T users;
sts = EssListConnections(hCtx, &usrcnt, &users);
if(!sts)
EssFree(hInst, users);
return(sts);
}
See Also
l EssListConnectionsEx
EssListConnectionsEx
Lists all users who are connected to the currently logged in server or application. Similar to
EssListConnections, but includes users hosted in a user directory.
Syntax
ESS_FUNC_M EssListConnectionsEx (hCtx, pCount, ppUserList);
451
pCount ESS_PUSHORT_T Address of variable to receive count of users (output).
ppUserList ESS_PPUSERINFOID_T Pointer to an array of user information structures (output). The information
structures can include user directories and unique identity attributes.
Notes
l pCount contains the number of elements in the ppUserList array.
l If hCtx is a Supervisor, ppUserList is a list of users logged in to the server. If hCtx is an
Application Designer, ppUserList is a list of users connected to any application for which
hCtx is an Application Designer.
l Use EssFree to free the buffer allocated for ppUserList.
Return Value
Access
This function requires the caller to have Supervisor or Application Designer privilege.
Example
void DisplayUserInfoID2(ESS_USERINFOID_T userInfo)

{
printf("\tUser Name: %s\n", userInfo.Name);

printf("\tProvider Name: %s\n", userInfo.ProviderName);
printf("\tConnparam: %s\n", userInfo.connparam);
printf("\tDescription: %s\n", userInfo.Description);
printf("\tEMail Identification: %s\n", userInfo.EMailID);
if (userInfo.LockedOut)
else
if (userInfo.PwdChgNow)
else
printf( "\tConnected Application: %s\n", userInfo.AppName);

printf( "\tConnected Database: %s\n", userInfo.DbName);
if (userInfo.Login)
else
switch(userInfo.Access)
452
{
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", userInfo.Access);
break;
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userInfo.Access);
break;
case ESS_PRIV_CALC:
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userInfo.Access);
453
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userInfo.Access);
break;
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userInfo.Access);
break;
default:
}
switch(userInfo.MaxAccess)
{
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", userInfo.MaxAccess);
break;
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userInfo.MaxAccess);
454
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userInfo.MaxAccess);
break;
case ESS_PRIV_CALC:
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userInfo.MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userInfo.MaxAccess);
break;
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userInfo.MaxAccess);
break;
default:
}
printf("\tPassword Expiration in Dates: %d\n",userInfo.Expiration);

//EssSdCTime(NULL, userInfo.LastLogin, sizeof(time_string), time_string);
printf("\tFailed Login Attempts Since Then: %d\n", userInfo.FailCount);
printf("\tLogin ID: %ld\n", userInfo.LoginId);
printf( "\n");
}
ESS_FUNC_M ESS_ListUserConnectionsEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_HCTX_T hLocalCtx1;
ESS_USHORT_T usercount, i = 0;
ESS_PUSERINFOID_T userInfo = ESS_NULL;
ESS_USHORT_T Items;
ESS_PAPPDB_T pAppsDbs = ESS_NULL;
usercount = 0;
memset(&userInfo, '\0', sizeof(userInfo));
sts = EssListConnectionsEx(hCtx, &usercount, &userInfo);
printf("EssListConnectionsEx sts: %ld\n", sts);
if(!sts)
{
printf("\nConnection count(s): %d\n", usercount);
for(i = 0; i < usercount; i++)
{
DisplayUserInfoID2(userInfo[i]);
}
}
455
return(sts);
}
EssListCurrencyDatabases
Lists all currency databases within a specific application which are accessible to the caller.
Syntax
ESS_FUNC_M EssListCurrencyDatabases (hCtx, AppName, pCount, ppDbList);
pCount ESS_PUSHORT_T Address of variable to receive count of currency databases.
ppDbList “ESS_APPDB_T” on page 108 Address of pointer to receive allocated array of application/database
structures.
Notes
l This function can only be used to list currency databases within an application on the server,
not the client.
l The ppDbList argument returns an array of structures containing matching pairs of
application and database name strings.
l The memory allocated for ppDbList should be freed using EssFree.
Return Value
If successful, this function returns a count of the number of accessible currency databases in
pCount, and a list of applications/currency database names in ppDbList.
Access
This function requires no special privileges; note, however, that server currency databases will
only be listed if the caller has access to them.
Example
ESS_FUNC_M
ESS_ListCurrencyDatabases (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_USHORT_T Items;
ESS_USHORT_T ind;
ESS_STR_T AppName;
ESS_PAPPDB_T pDbsList = NULL;
AppName = "Sample";
sts = EssListCurrencyDatabases(hCtx, AppName,
&Items, &pDbsList);
456
if(!sts)
{
if(Items && pDbsList)
{
printf("\r\n---- Currency Databases ----\r\n\r\n");
for (ind = 0; ind<Items; ind++)
{
if((pDbsList+ind) !=NULL)
{
if(pDbsList[ind].DbName != NULL)
{
printf("%s",AppName);
printf(" ==> ");
printf("%s",pDbsList[ind].DbName);
printf("\n\r");
}
}
}
EssFree(hInst, pDbsList);
}
else
printf("\r\nCurrency Database List is Empty\r\n\r\n");
}
return (sts);
}
See Also
l EssListApplications
l EssListDatabases
l EssListObjects
EssListDatabases
Lists all databases which are accessible to the caller, either within a specific application, or on an
entire server.
Syntax
ESS_FUNC_M EssListDatabases (hCtx, AppName, pCount, ppDbList);
pCount ESS_PUSHORT_T Address of variable to receive count of applications and databases.
ppDbList “ESS_APPDB_T” on page 108 Address of pointer to receive allocated array of application/database name
structures.
457
Notes
l If the AppName argument is NULL, this function lists all the accessible applications and
databases on the server.
l The ppDbList argument returns an array of structures containing matching pairs of
application and database name strings.
l The memory allocated for ppDbList must be freed using EssFree.
Return Value
If successful, this function returns a count of the number of accessible databases in pCount, and
a list of the application and database names in ppDbList.
Access
This function requires no special privileges; note however that server databases will only be listed
if the caller has access to them.
Example
ESS_FUNC_M
ESS_ListDbs (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_USHORT_T Items;
ESS_USHORT_T ind;
sts = EssListDatabases (hCtx, NULL, &Items,
&pAppsDbs);
if (!sts)
{
if (Items && pAppsDbs)
{
printf ("\r\n-----Applications/databases available-----\r\n");
{
if ((pAppsDbs+ind) != NULL)
{
if ((pAppsDbs[ind].AppName != NULL) &&
(pAppsDbs[ind].DbName != NULL))
{
printf ("%s", pAppsDbs[ind].AppName);
printf (" ==> ");
printf ("%s", pAppsDbs[ind].DbName);
printf ("\n\r");
}
}
}
EssFree (hInst, pAppsDbs);
}
else
printf ("\r\ndatabaseList is Empty\r\n\r\n");
}
458
return(sts);
}
See Also
l EssListCurrencyDatabases
l EssListObjects
EssListExistingLoadBuffers
Returns the list of structures that describe existing data load buffers for an aggregate storage
database.
This function returns the count of existing buffers and an array of descriptor structures. The
memory for the array must be freed using EssFree.
Syntax
ESS_FUNC_M EssListExistingLoadBuffers (hCtx, AppName, DbName, pCount, paLoadBuffers);
AppName ESS_STR_T Use NULL. Function always applies to the currently selected
database.
DbName ESS_STR_T Use NULL. Function always applies to the currently selected
database.
pCount ESS_PULONG_T Address of variable to receive count of load buffers.
paLoadBuffers “ESS_LOAD_BUFFER_T” on page Pointer to load buffer information structure.

139**
Return Value
Example
void TestListExistingLoadBuffers(ESS_HCTX_T hCtx, ESS_STR_T AppName, ESS_STR_T DbName)
{
ESS_LOAD_BUFFER_T *LoadBuffers;
ESS_ULONG_T i;
ESS_ULONG_T Count;
/* EssListExistingLoadBuffers */
sts = EssListExistingLoadBuffers(hCtx, AppName, DbName, &Count, &LoadBuffers);
printf("EssListExistingLoadBuffers sts: %ld\n",sts);
printf("\tNumber of buffers: %d", Count);
if(Count > 0)
459
{
for(i = 0; i < Count; i++)
{
printf("\n\tBuffer Id: %d", LoadBuffers[i].ulBufferId);
printf("\n\tDuplicate Agg Method: %d",
LoadBuffers[i].ulDuplicateAggregationMethod);
printf("\n\tOption Flags: %d",
LoadBuffers[i].ulOptionFlags);
printf("\n\tSize (1-100): %d", LoadBuffers[i].ulSize);
printf("\n\tInternal: %d", LoadBuffers[i].bInternal);
printf("\n\tActive: %d", LoadBuffers[i].bActive);
printf("\n");
}
}
}
See Also
l EssLoadBufferInit
l EssSendString
l EssEndDataload
l EssLoadBufferTerm
l EssImportASO
l EssUpdateFileASO
EssListDbFiles
Retrieves information on specified index and data files.
Syntax
szAppName; ESS_STR_T Application name.
szDbName; ESS_STR_T Database name.
usFileType; ESS_USHORT_T One of the following file types to be returned:

l ESS_FILETYPE_INDEX
l ESS_FILETYPE_DATA
l ESS_FILETYPE_INDEX | ESS_FILETYPE_DATA
pNmbrOfFiles; ESS_PUSHORT_T Pointer to the number of index and data files returned.
ppDbInfoArray; “ESS_DBFILEINFO_T” on page Pointer to an array of database file information structures returned.
117
460
Return Value
l If successful,
l This function returns 0
l pNmbrOfFiles contains a pointer to the number of index and data files returned
l ppDbInfoArray contains a pointer to an array of database file information structures
returned
Example
ESS_STS_T ListDbFiles( ESS_HCTX_T hCtx )
{
ESS_APPNAME_T pszAppName;
ESS_DBNAME_T pszDbName;
ESS_PDBFILEINFO_T aDbFileInfo = NULL;
ESS_PDBFILEINFO_T pDbFileInfo = NULL;
ESS_USHORT_T usFileType = ( ESS_FILETYPE_INDEX | ESS_FILETYPE_DATA );
ESS_USHORT_T usFileCount = 0;
ESS_USHORT_T usFileIx;
/**************************************************************
* Prompt for the type of files to list: index, data or both, *
* and assign the user's file type choice to usFileType *
**************************************************************
* This function uses ESS_FILETYPE_INDEX | ESS_FILETYPE_DATA *
* as the default value *
**************************************************************/
.
.
.
/*************************************************************
* Prompt for application and database names, and assign the *
* user's choices to pszAppName and pszDbName, respectively *
*************************************************************/
.
.
.
/*********************************************************************
* Get an array of persistent database file information from Essbase *
* for the selected file type, application and database *
*********************************************************************/
sts = EssListDbFiles( hCtx, pszAppName, pszDbName, usFileType,
&usFileCount, &aDbFileInfo );
if ( sts )
{
goto exit;
}
/**********************************************
* Format and display the information in the *
* persistent database file information array *
461
**********************************************/
if ( ( usFileCount ) && ( aDbFileInfo ) )
{
printf( "Application Name: %s\n",
aDbFileInfo[ 0 ].AppName );
printf( "Database Name: %s\n",

aDbFileInfo[ 0 ].DbName );
for ( ( usFileIx = 0, usFileType = 0 );

usFileIx < usFileCount;
usFileIx++ )
{
/******************************************************
* Format and display the information in the current *
* persistent database file information array element *
******************************************************/
pDbFileInfo = &( aDbFileInfo[ usFileIx ] );
printf( "\nFile %lu:\n",

pDbFileInfo->FileSequenceNum );
printf( " File Name: %s\n",

pDbFileInfo->FilePath );
printf( " File Type: " );
if ( pDbFileInfo->FileType == ESS_FILETYPE_INDEX )
{
printf( "INDEX\n" );
}
else
{
printf( "DATA\n" );
}
printf( " File Number: %lu of %lu\n",

pDbFileInfo->FileSequenceNum, pDbFileInfo->FileCount );
printf( " File Size: %lu\n",

pDbFileInfo->FileSize );
printf( " File Opened: %c\n",

( pDbFileInfo->FileOpen ) ? 'Y' : 'N' );
} /* FOR usFileIx */
/************************************************
* Free the memory allocated for the persistent *
* database file information array *
************************************************/
free( aDbFileInfo );
}
else
{
printf( "Application Name: %s\n",
AppName );
462
printf( "Database Name: %s\n",
DbName );
switch ( usFileType )
{
case ESS_FILETYPE_INDEX:
printf( "\nNo existing INDEX files.\n" );
break;
case ESS_FILETYPE_DATA:
printf( "\nNo existing DATA files.\n" );
break;
case ( ESS_FILETYPE_INDEX | ESS_FILETYPE_DATA ):
printf( "\nNo existing INDEX or DATA files.\n" );
break;
default:
printf( "\nNo existing database files of the selected type.\n" );
break;
} /* SWITCH usFileType */
}
printf( "\n" );
exit:
return ( sts );
}
See Also
l “ESS_DBFILEINFO_T” on page 117
EssListDrillThruURLs
Lists the drill-through URL names within the active database outline.
Syntax
ESS_FUNC_M EssListDrillThruURLs (hCtx, &pCountOfUrls, &pUrls);
pCountOfUrls ESS_PUSHORT_T Count of drill-through URLs.
pUrls ESS_PPDURLINFO_T List of URLs.
Notes
The ESS_DURLINFO_T structure array must be deallocated by the caller using
EssFreeStructure with the ESS_DT_STRUCT_URLINFO option.
463
Return Value
l If successful, lists drill-through URLs in the active database outline.
Access
EssSetActive.
Example
static void DisplayUrlDefn (ESS_PDURLINFO_T pUrls )
{
ESS_UINT_T i;
printf("\tUrlname : %s\n", pUrls->cpURLName );

if (pUrls->bIsLevel0)
printf("\tUrl Is Level-0 slice : Yes\n");
else
printf("\tUrl Is Level-0 slice : No\n");
printf("\tUrlXmlsize : %i\n", pUrls->iURLXmlSize );

printf("\tUrlXml : %s\n", (ESS_STR_T) pUrls->cpURLXml);
printf("\tNumber of drill region(s): %d\n", pUrls->iCountOfDrillRegions);

for ( i = 0; i < pUrls->iCountOfDrillRegions; i++ )
{
printf("\t\tDrillRegion[%d]: %s\n", i, pUrls->cppDrillRegions[i] );
}
printf("\n");
}

ESS_PDURLINFO_T listOfURLs;
ESS_DURLINFO_T url;
/* Valid case*/
sts = EssListDrillThruURLs(hCtx, &usCountOfURLs, &listOfURLs);

printf("EssListDrillThruURLs sts: %ld\n",sts);
if(!sts)
{
printf("\tCount of URL: %d\n", usCountOfURLs);
printf("\tList of URL(s):\n");
for(i = 0; i < usCountOfURLs; i++)
{
DisplayUrlDefn (&listOfURLs[i]);
}
}
EssFreeStructure (hInst, ESS_DT_STRUCT_URLINFO, usCountOfURLs, listOfURLs);
464
EssListExtUsers
Lists users who are externally authenticated through Shared Services.
Syntax
ESS_FUNC_M EssListExtUsers (hCtx, AppName, DbName, Protocol, Count, ppUserList);
AppName ESS_STR_T Application name. If NULL, lists all users.
DbName ESS_STR_T Database name. If NULL, lists users for all databases within application.
Protocol ESS_STR_T External authentication protocol: CSS, for Shared Services mode. Even
if the protocol is not specified, this function returns a list of users who are
externally authenticated through Shared Services.
Count ESS_PUSHORT_T Address of variable to receive count of users.
ppUserList “ESS_USERINFOEX_T” on Address of pointer to receive an allocated array of user info structures.
page 189 The AppName and DbName fields of the returned user info structures
contain NULL values.
Notes
l If both AppName and DbName are not NULL, only users with access to the specified
application and database are listed. If DbName is NULL, only users with access to the specified
application are listed. If AppName is NULL, all users that exist on the server are listed.
l The AppName and DbName fields of the returned ESS_USERINFO_T structures contain
NULL values.
Return Value
If successful, returns a count of the number of users in pCount, and list of users with access to
the specified application and database in ppUserList.
Access
See Also
l EssSetExtUser
l EssCreateExtUser
l EssGetExtUser
EssListFilters
Lists all filters for a database.
465
Syntax
ESS_FUNC_M EssListFilters (hCtx, AppName, DbName, Count, ppFilterList);
pCount ESS_PUSHORT_T Address of variable to receive count of filter names.
ppFilterList ESS_PPFTRNAME_T Address of pointer to receive an allocated array of filter name strings.
Notes
The memory allocated for ppFilterList should be freed using EssFree.
Return Value
If successful, returns the count of filters in the database in pCount, and an array of filter names
in ppFilterList.
Access
Example
ESS_FUNC_M
ESS_ListFilters (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_USHORT_T ind;
ESS_PFTRNAME_T pFilterList = NULL;
AppName = "Sample";
DbName = "Basic";
sts = EssListFilters(hCtx, AppName, DbName,

&Count, &pFilterList);
if(!sts)
{
if(Count && pFilterList)
{
printf ("\r\n-------Filter List-------\r\n\r\n");
printf("%s\r\n",pFilterList[ind]);
EssFree (hInst, pFilterList);
}
else
466
printf ("\r\nFilter List is empty\r\n\r\n");
}
return (sts);
}
See Also
l EssGetFilter
l EssSetFilter
EssListFilterUsers
Lists all users using a filter.
Syntax
ESS_FUNC_M EssListFilterUsers (hCtx, dbName, AppName, UserCount, ppUserInfo);
dbName ESS_STR_T Database name.
UserCount ESS_PUSHORT_T Count of users using the filter.
ppUserInfo ESS_PPUSERINFO_T (see “ESS_USERINFO_T, Pointer to array of user information structures.

ESS_GROUPINFO_T” on page 186)
Return Value
See Also
l EssListFilters
EssListGroups
Lists all groups who have access to a particular Essbase Server, application or database.
Syntax
ESS_FUNC_M EssListGroups (hCtx, AppName, DbName, pCount, ppGroupList);
AppName ESS_STR_T Application name. If NULL, lists all groups.
467
DbName ESS_STR_T Database name. If NULL, lists groups for all databases within
application.
pCount ESS_PUSHORT_T Address of variable to receive count of groups.
ppGroupList “ESS_USERINFO_T, Address of pointer to receive an allocated array of group info

ESS_GROUPINFO_T” on page 186 structures.
Notes
l If both AppName and DbName are not NULL, only groups with access to the specified
application and database will be listed. If DbName is NULL, only groups with access to the
specified application will be listed. If AppName is NULL, all groups on the logged in server
will be listed.
l The memory allocated for ppGroupList should be freed using EssFree.
Return Value
If successful, returns a count of the number of groups in pCount, and list of groups with access
to the specified application and database in ppGroupList.
Access
Example
ESS_FUNC_M
ESS_ListGroups (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_USHORT_T Count;
ESS_PGROUPINFO_T Groups = NULL;
ESS_USHORT_T ind;
sts = EssListGroups (hCtx, NULL, NULL, &Count, &Groups);
if (!sts)
{
if (Count && Groups)
{
printf ("\r\n-----Group List-----\r\n\r\n");
printf ("Name->%s\r\n", Groups [ind].Name);
EssFree (hInst, Groups);
}
else
printf ("\r\nGroup List is Empty\r\n\r\n");
}
return (sts);
}
468
See Also
l EssGetGroup
l EssListUsers
EssListGroupsInfoEx
Lists all groups who have access to a particular Essbase Server, application or database. Similar
to EssListGroups, but the group list structure can include user directories and unique identity
attributes.
Syntax
ESS_FUNC_M EssListGroupsInfoEx (hCtx, AppName, DbName, pCount, ppGroupList);
AppName ESS_STR_T Application name (input). If NULL, lists all groups.
DbName ESS_STR_T Database name (input). If NULL, lists groups for all databases within the
application.
pCount ESS_PUSHORT_T Address of variable to receive count of groups (output).
ppGroupList ESS_PPGROUPINFOID_T Address of pointer to receive an allocated array of group info structures
(output). The group list structure can include user directories and unique
Notes
l If both AppName and DbName are not NULL, only groups with access to the specified
application and database will be listed. If DbName is NULL, only groups with access to the
specified application will be listed. If AppName is NULL, all groups on the logged in server
will be listed.
l The memory allocated for ppGroupList should be freed using EssFree.
Return Value
If successful, returns a count of the number of groups in pCount, and list of groups with access
to the specified application and database in ppGroupList.
Access
Example
void DisplayGroupsInfoEx(ESS_GROUPINFOID_T groupInfo)

{
469
printf("\tUser Name: %s\n", groupInfo.Name);
printf("\tProvider Name: %s\n", groupInfo.ProviderName);
printf("\tIdentity: %s\n", groupInfo.connparam);
printf("\tDescription: %s\n", groupInfo.Description);
printf("\tEMail Identification: %s\n", groupInfo.EMailID);
if (groupInfo.LockedOut)
else
if (groupInfo.PwdChgNow)
else
printf("\tPassword: %s\n", groupInfo.Password);

printf("\tApplication: %s\n", groupInfo.AppName);
printf("\tDatabase: %s\n", groupInfo.DbName);
if (groupInfo.Login)
else
switch(groupInfo.Access)
{
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", groupInfo.Access);
break;
break;
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", groupInfo.Access);
470
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", groupInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", groupInfo.Access);
break;
case ESS_PRIV_CALC:
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", groupInfo.Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", groupInfo.Access);
break;
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", groupInfo.Access);
break;
default:
}
switch(groupInfo.MaxAccess)
{
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", groupInfo.MaxAccess);
break;
break;
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", groupInfo.MaxAccess);
471
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", groupInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", groupInfo.MaxAccess);
break;
case ESS_PRIV_CALC:
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", groupInfo.MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", groupInfo.MaxAccess);
break;
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", groupInfo.MaxAccess);
break;
default:
}
printf("\tPassword Expiration in Dates: %d\n",groupInfo.Expiration);

printf("\tFailed Login Attempts Since Then: %d\n", groupInfo.FailCount);
printf("\tLogin ID: %d\n", groupInfo.LoginId);
printf("\tProtocol: %s\n", groupInfo.protocol);
printf("\tConnection Parameter: %s\n", groupInfo.connparam);
printf( "\n");
472
}
ESS_FUNC_M ESS_ListGroupsInfoEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)

{

ESS_USHORT_T count, i;
ESS_PGROUPINFOID_T pGroupList = ESS_NULL;
sts = EssListGroupsInfoEx(hCtx, AppName, DbName, &count, &pGroupList);

printf("EssListGroupsInfoEx sts: %ld\n", sts);
if(!sts)
{
printf("\nNumber of group(s): %d\n", count);
for(i = 0; i < count; i++)
{
DisplayGroupsInfoEx(pGroupList[i]);
}
}
return (sts);
}
See Also
l EssGetGroupInfoEx
EssListLocks
Lists all users who are connected to a specific application and database, together with a count of
data blocks which they currently have locked.
Syntax
ESS_FUNC_M EssListLocks (hCtx, AppName, DbName, pCount, ppLockList);
pCount ESS_PUSHORT_T Address of variable to receive count of users.
ppLockList “ESS_LOCKINFO_T” on page 140 Address of pointer to receive an allocated array of user lock info
structures.
Notes
l This function is a "snapshot," in that only those users who are connected to the server when
this function is called will be listed.
l The memory allocated for ppLockList should be freed using EssFree.
473
Return Value
If successful, returns a count of the number of connected users in pCount, and list of user lock
structures in ppLockList.
Access
Example
ESS_FUNC_M
ESS_ListLocks (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_FUNC_M sts;
ESS_USHORT_T Count;
ESS_PLOCKINFO_T plockinfo = NULL;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssListLocks (hCtx, AppName, DbName,
&Count, &plockinfo);
if (!sts)
{
if (Count && plockinfo)
EssFree (hInst, plockinfo);
else
printf ("\r\nExclusive Lock List on %s:%s is empty\r\n\r\n", AppName, DbName);
}
return (sts);
}
See Also
l EssListLocksEx
l EssListConnections
l EssListUsers
l EssRemoveLocks
EssListLocksEx
Lists all users who are connected to a specific application and database, together with a count of
data blocks which they currently have locked. Similar to EssListLocks, but includes users
hosted in a user directory.
Syntax
ESS_FUNC_M EssListLocksEx (hCtx, AppName, DbName, pCount, ppLockList);
474
AppName ESS_STR_T Application name (input).
DbName ESS_STR_T Database name (input).
pCount ESS_PUSHORT_T Address of variable to receive the user count (output).
ppLockList ESS_PPLOCKINFOEX_T Address of pointer to receive an allocated array of user lock information
structures (output). The information structures can include user directories
and unique identity attributes.
Notes
l This function is a "snapshot," in that only those users who are connected to the server when
this function is called will be listed.
l The memory allocated for ppLockList should be freed using EssFree.
Return Value
If successful, returns a count of the number of connected users in pCount, and list of user lock
structures in ppLockList.
Access
Example
void DisplayLock(ESS_LOCKINFOEX_T lockinfo)

{
printf("\tUser Name: %s\n", lockinfo.UserName);

printf("\tProvider Name: %s\n", lockinfo.ProviderName);
printf("\tConnection Parameter: %s\n", lockinfo.connparam);
printf("\tNumber of Locks: %d\n", lockinfo.nLocks);
printf("\tTime: %ld\n", lockinfo.Time);
printf("\tLoginId: %ld\n", lockinfo.LoginId);
printf("\n");
}
ESS_FUNC_M ESS_ListLocksEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STS_T sts;
ESS_PLOCKINFOEX_T plockinfo = NULL;
sts = EssSetActive(hCtx, AppName, DbName, &Access);
475
printf("EssSetActive sts: %ld\n",sts);
sts = EssListLocksEx (hCtx, AppName, DbName, &count, &plockinfo);

printf("EssListLocksEx sts: %ld\n", sts);
if(!sts)
{
printf("\nNumber of lock info returned: %d\n", count);
{
DisplayLock(plockinfo[i]);
}
}
return (sts);
}
See Also
l EssListConnectionsEx
EssListLogins
Returns the list of login instances in the current session.
Syntax
ESS_FUNC_M EssListLogins (hCtx, count, logins);
count ESS_PUSHORT_T Pointer to the number of logins returned from the server.
logins ESS_PPCONNECTINFO_T Pointer to an array of a ESS_CONNECTINFO_T structure containing

connection information.
Notes
You can call this function more than once for the same user name and server. The API returns
a unique context handle for each login to the server.
Return Value
If successful, returns login information and a count of current logins.
Access
by calling EssInit.
See Also
l EssListLoginsEx
l EssAutoLogin
l EssInit
476
l EssListDatabases
l EssLogout
l EssSetActive
EssListLoginsEx
Returns the list of log in instances in the current session. Similar to EssListLogins, but
Syntax
ESS_FUNC_M EssListLoginsEx (hCtx, count, logins);
count ESS_PUSHORT_T Pointer to the number of log ins returned from the server (output).
logins ESS_PPCONNECTINFOEX_T Pointer to an array of an ESS_CONNECTINFOEX_T structure containing

connection information (output). The information structure can include
user directories and unique identity attributes.
Notes
You can call this function more than once for the same user name and server. The API returns
a unique context handle for each login to the server.
Return Value
If successful, returns login information and a count of current logins.
Access
by calling EssInit.
Example
void DisplayLoginInfo(ESS_CONNECTINFOEX_T login)

{
printf("\tName: %s\n", login.Name);

printf("\tApp Name: %s\n", login.AppName);
printf("\tDb Name: %s\n", login.DbName);
printf("\tLogin MachineName: %s\n", login.LoginMachine);
printf("\tLogin Ip: %ld\n", login.LoginIP);
printf("\tLast login time: %ld\n", login.LastLogin);
printf("\n");
}
ESS_FUNC_M ESS_ListLoginsEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
477
{
ESS_PCONNECTINFOEX_T logins;
ESS_USHORT_T Items;
sts = EssListLoginsEx(hCtx, &count, &logins);

printf("EssListLogins sts: %ld\n", sts);
if(!sts)
{
printf("\nConnection count(s): %d\n", count);
{
DisplayLoginInfo(logins[i]);
}
sts = EssFree (hInst, logins);

printf("EssFree sts: %ld\n", sts);
}
return(sts);
}
See Also
l EssAutoLogin
l EssInit
l EssListDatabases
l EssLogout
l EssSetActive
EssListObjects
Lists all objects of the specified types on the server or locally on the client.
Syntax
ESS_FUNC_M EssListObjects (hCtx, ObjType, AppName, DbName, pCount, ppObjList);
ObjType ESS_OBJTYPE_T Object type (may be multiple types joined by bitwise OR ( | )). Refer to “Bitmask
Data Types (C)” on page 90 for a list of possible values.
478
DbName ESS_STR_T Database name. If NULL, lists objects in the application subdirectory.
pCount ESS_PUSHORT_T Address of variable to receive the count of objects of the appropriate type(s).
ppObjList “ESS_OBJINFO_T” on Address of pointer to receive allocated array of object info structures.
page 146
Notes
l The memory allocated for ppObjList should be freed using EssFree.
l This function does not guarantee a consistent order of the returned objects, as this may vary
by operating system.
Return Value
If successful, returns a count of the number of objects of the appropriate type(s) in pCount, and
an array of matching object structures in ppObjList.
Access
This function requires no special privileges; note however that server objects will only be listed
if the caller has the appropriate level of access to the application and/or database (depending on
the object type).
Example
ESS_FUNC_M
ESS_ListObjects (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_POBJINFO_T pObject, pNextObject = NULL;
ESS_SHORT_T objType = 0;
ESS_USHORT_T objCnt;
ESS_USHORT_T objInd;
ESS_STR_T AppName;
ESS_STR_T DbName;
Appname = "Sample";
DbName = "Basic";
objType = ESS_OBJTYPE_OUTLINE;
sts = EssListObjects (hCtx, objType, AppName,
DbName, &objCnt, &pObject);
if (!sts)
{
if (objCnt && pObject)
{
pNextObject = pObject;
for (objInd = 0; objInd < objCnt; objInd++)
{
if (pNextObject)
{
printf ("Name: %s \r\nUser: %s\r\nTime Stamp: %ld\r\n",
pNextObject->Name,
pNextObject->User,
479
pNextObject->TimeStamp);
pNextObject = pNextObject + 1;
}
}
EssFree (hInst, pObject);
}
else
printf ("\r\nObject List is Empty\r\n\r\n");
}
return(sts);
}
See Also
l EssGetObject
l EssGetObjectInfo
EssListRequests
Returns information about active sessions and requests.
Syntax
ESS_FUNC_M EssListRequests (hCtx, UserName, AppName, DbName, RequestCount, pRequestInfo);
RequestCount ESS_PUSHORT_T Number of requests (output).
ppRequestInfoStruct ESS_PPREQUESTINFO_T Request type (output).
Notes
l A session is the time in seconds between a user's login and logout.
l A request is a query sent to Essbase by a user or by another process; for example, starting an
application or restructuring a database outline. Each session can process only one request
at a time; therefore, sessions and requests have a one-to-one relationship.
l Some of the listed requests may have been recently terminated, but are still listed as active
due to network delay.
l This function returns information on requests/sessions initiated by the process specified by
the UserName, AppName, and DbName. If these parameters are null or empty, then all the
processes in the system are listed. This function returns the number of current requests and
one ESS_REQUESTINFO_T structure for each request.
l The returned ppRequestInfoStruct needs to be freed by calling EssFree.
480
Return Value
Example
#include <stdio.h>
#include <essapi.h>
ESS_FUNC_M ESS_ListRequest ()
{
ESS_HCTX_T hCtx;
ESS_USHORT_T Items;
ESS_HINST_T hInst ;
ESS_PREQUESTINFO_T requestInfo;

/* structure */
{
NULL, /* user-defined message context */
NULL, /* local path */
/* Set to NULL */
};
EssInit (&InitStruct, &hInst);
sts = EssLogin (hInst, "local", "admin", "password", &Items, &pAppsDbs, &hCtx);
sts = EssListRequests( hCtx, NULL, NULL, NULL, &numRequest, &requestInfo);
printf ( "Total requests on the server %d\n", numRequest );

{

{
481
printf ( "\n\n--------------------------------------\n\n",
sts = EssKillRequest (hCtx, &requestInfo[index] );
index++;
}

}
EssLogout (hCtx);
EssTerm (hInst);
return(sts);
}
void main()
{
ESS_ListRequest ();
}
See Also
l EssListRequestsEx
l EssKillRequest
l “ESS_REQUESTINFO_T” on page 173
l “ESS_REQ_STATE_T” on page 179
EssListRequestsEx
Returns information about active sessions and requests. Similar to EssListRequests, but
Syntax
ESS_FUNC_M EssListRequestsEx (hCtx, UserId, bIsIdentity, AppName, DbName, RequestCount,
pRequestInfo);
UserId ESS_STR_T User name or identity (input). If an identity, includes a unique identity
string identifying the user in a user directory.
bIsIdentity ESS_BOOL_T Indicates if a user identity or name is used (input). If TRUE, indicates
that UserId is a unique identity attribute. If FALSE, UserId is a user name.
482
RequestCount ESS_PUSHORT_T Number of requests (output).
pRequestInfo ESS_PREQUESTINFOEX_T Request type (output).
Notes
l A session is the time in seconds between a user's login and logout.
l A request is a query sent to Essbase by a user or by another process; for example, starting an
application or restructuring a database outline. Each session can process only one request
at a time; therefore, sessions and requests have a one-to-one relationship.
l Some of the listed requests may have been recently terminated, but are still listed as active
due to network delay.
l This function returns information on requests/sessions initiated by the process specified by
the UserID, AppName, and DbName. If these parameters are null or empty, then all the
processes in the system are listed. This function returns the number of current requests and
one ESS_REQUESTINFOEX_T structure for each request.
l The returned ppRequestInfoStruct needs to be freed by calling EssFree.
Return Value
Access
Example
void ListRequestsEx ()
{
ESS_STR_T userId;
ESS_PREQUESTINFOEX_T requestInfo;
userId = "admin";
&requestInfo);
{
{
483
printf ( "\n\n--------------------------------------\n\n",
index++;
}

}
userId = " native://nvid=f0ed2a6d7fb07688:5a342200:1265973105c:-7f46?USER ";

&requestInfo);
{
{
printf ( "\n\n--------------------------------------\n\n",
index++;
}

}
}
See Also
l EssKillRequestEx
484
EssListSpoolFiles
Lists all trigger log files for a database.
Syntax
ESS_FUNC_M EssListSpoolFiles (hCtx, AppName, DbName, pCount, ppFileList);
pCount ESS_PUSHORT_T Address of variable to receive count of spool file names.
ppFileList ESS_PPOBJINFO_T Address of pointer to receive an allocated array of spool file name objects.
Notes
The memory allocated for this function should be freed by calling EssFree.
Return Value
If successful, returns the count of spool files in the database in pCount, and an array of spool file
names in ppFileList.
Access
See Also
l EssGetSpoolFile
l EssDeleteSplFile
l EssMdxTrig
EssListSSMigrFailedGroups
Displays groups that did not successfully migrate to Shared Services.
Syntax
ESS_FUNC_M EssListSSMigrFailedGroups (hCtx, count, pNativeUserList);
485
count ESS_PUSHORT_T Address of variable to receive count of migration failed groups.
pNativeUserList ESS_PPUSERNAME_T Address of pointer to receive an allocated array of migration failed groups.
Notes
If Essbase has not been migrated to Shared Services, this function is not supported and returns
an error.
Return Value
Example
ESS_FUNC_M ESS_SS_ListSSMigrFailedGroups(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_PUSERNAME_T pNativeUserList = NULL;
ESS_USHORT_T Count = 0,
index;
sts = EssListSSMigrFailedGroups(hCtx, &Count, &pNativeUserList);
if (!sts)
{
if (Count && pNativeUserList)
{
printf ("\n------- Group List -------\n\n");
for (index = 0; index < Count; index++)

{
if (pNativeUserList[index])
printf ("%s\n", pNativeUserList[index]);
}
EssFree(hInst, pNativeUserList);
}
else
printf("\nGroup list is empty\n\n");
}
else
printf("Failed to get Shared Services migration failed Groups list.\n");
return (sts);
}
See Also
l EssListSSMigrFailedUsers
486
EssListSSMigrFailedUsers
Displays users that did not successfully migrate to Shared Services.
Syntax
ESS_FUNC_M EssListSSMigrFailedUsers (hCtx, count, pNativeUserList);
count ESS_PUSHORT_T Address of variable to receive count of migration failed users.
pNativeUserList ESS_PPUSERNAME_T Address of pointer to receive an allocated array of migration failed users.
Return Value
Example
ESS_FUNC_M ESS_SS_ListSSMigrFailedUsers(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
index;
sts = EssListSSMigrFailedUsers(hCtx, &Count, &pNativeUserList);
if (!sts)
{
{
printf ("\n------- User List -------\n\n");

{
}
}
else
printf("\nUser list is empty\n\n");
}
else
printf("Failed to get Shared Services migration failed Users list.\n");
return (sts);
}
487
See Also
l EssListSSMigrFailedGroups
EssListTransactions
Returns transaction messages to a client buffer or to a comma-separated file. You can export
comma-separated files to relational databases for processing with third-party tools.
Syntax
ESS_FUNC_M EssListTransactions(hCtx, TimeSrc, InpTime,
ListOption, FileName, pCount, ppResults);
hCtx ESS_HCTX_T Login context must be set active before calling this API.
TimeSrc ESS_USHORT_T The option that specifies where to get the start time for display
transactions.
InpTime ESS_TIME32_T Input the time if TimeSrc is ESS_TRLOG_TIMESPECIFIED. The

time is a ULONG representing the number of seconds elapsed since
January 1, 1970.
ListOption ESS_USHORT_T The option that specifies the destination of the output. See “List
Option Constants (C)” on page 99
FileName ESS_STR_T If ListOption is either of the LIST_TRANSACTIONS_* options, then

the content is written to this file on the server machine:
l You can enter a full path.
l Default:
$ARBORPATH/app
pCount ESS_PULONG_T Number of entries returned
ppResults ESS_PPTRANSACTION_ENTRY_T The entries returned if ListOption is

ESS_LIST_TRANSACTIONS_TOCLIENT
Return Value
l 0—If successful
m pCount contains the number of returned entries
m ppResults contains the returned entries if ListOptions is
ESS_LIST_TRANSACTIONS_TOCLIENT
Access
You must have an active database using set active before calling list transactions.
The caller must have Essbase Administrator access to the database.
488
Example
void ListAndReplayTransactions()
{
ESS_USHORT_T TimeSrc;
ESS_TIME32_T timestamp = 0;
ESS_USHORT_T listOption;
ESS_STR_T FileName = ESS_NULL;
ESS_ULONG_T Count = 0;
ESS_PTRANSACTION_ENTRY_T pResults;
ESS_CHAR_T listTime[ESS_TIMESIZE];
ESS_TRANSACTION_REPLAY_INP_T ReplayInp;
ESS_PSEQID_T pSeqIds = ESS_NULL;
ESS_OBJDEF_T Data;
ESS_STR_T Script;
/* Load data from server */

Data.hCtx = hCtx;
Data.FileName = "Calcdat";
sts = EssImport (hCtx, ESS_NULL, &Data,
&pMbrErr, NULL, isAbortOnError);
printf("EssImport sts: %ld\r\n",sts);
/* List and replay with a specified time */

TimeSrc = 1;
strcpy(listTime, "09/18/2007:00:00:00");
/* mm/dd/yyyy:hh:mm:ss */
timestamp = adtGenericGetTime(listTime);
listOption = ESS_LIST_TRANSACTIONS_TOCLIENT;
sts = EssListTransactions(hCtx, TimeSrc,
timestamp, listOption,
FileName, &Count, &pResults);
/* This function converts listTime to the number of

seconds since January 1, 1970. */
printf("EssListTransactions sts: %ld\r\n",sts);

if (Count && pResults)
PrintTransactionLog(Count, pResults);
memset(&ReplayInp, 0, sizeof
(ESS_TRANSACTION_REPLAY_INP_T));
ReplayInp.InpType = ESS_REPLAY_BASED_GIVENTIME;
ReplayInp.value.InpTime = timestamp;
sts = EssReplayTransactions (hCtx, AppName, DbName,
ReplayInp, pSeqIds);
printf("EssReplayTransactions sts: %ld\r\n",sts);
printf("\n\n");
/* Run a calc*/
489
printf("EssCalc sts: %ld\r\n",sts);
if (!sts)
{
while (!sts && (pState.State != ESS_STATE_DONE))
}
/* List and replay with last replay time */

TimeSrc = 2;
timestamp = 0;

memset(&ReplayInp, 0, sizeof
ReplayInp.InpType = ESS_REPLAY_BASED_LASTREPLAYTIME;
sts = EssReplayTransactions (hCtx, AppName,
DbName, ReplayInp, pSeqIds);
if(pSeqIds)
EssFree(hInst, pSeqIds);
if(pResults)
EssFree(hInst, pResults);
if(pMbrErr)
EssFree(hInst, pMbrErr);
}
See Also
l “ESS_SEQID_T” on page 180
l “ESS_DISKVOLUME_REPLACE_T” on page 131
l “ESS_TRANSACTION_ENTRY_T” on page 181
l “ESS_TRANSACTION_REPLAY_INP_T” on page 182
l “ESS_TRANSACTION_REQSPECIFIC_T” on page 182
l EssReplayTransactions
EssListUsers
Lists all users who have access to a particular Essbase Server, application or database.
Syntax
ESS_FUNC_M EssListUsers (hCtx, AppName, DbName, pCount, ppUserList);
490
DbName ESS_STR_T Database name. If NULL, lists users for all databases within the
application.
ppUserList “ESS_USERINFO_T, Address of pointer to receive an allocated array of user info structures.
ESS_GROUPINFO_T” on page The AppName and DbName fields of the returned user info structures
186 contain NULL values.
Notes
application and database are listed. If DbName is NULL, only users with access to the
specified application are listed. If AppName is NULL, all users that exist on the server are
listed.
NULL values.
Return Value
Access
Example
ESS_STS_T
ESS_ListUsers (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STS_T sts;
ESS_USHORT_T Count;
ESS_PUSERINFO_T Users = NULL;
ESS_USHORT_T ind;
sts = EssListUsers (hCtx, NULL, NULL, &Count,

&Users);
if (!sts)
{
if (Count && Users)
{
printf ("\r\n-------User List-------\r\n\r\n");
{
printf ("Name->%s Application->%s database->%s\r\n",
491
Users[ind].Name, Users[ind].AppName,
Users[ind].DbName);
}
EssFree (hInst, Users);
}
else
}
return (sts);
}
See Also
l EssGetUser
l EssListGroups
l EssListLocks
EssListUsersEx
Lists all users who have access to a particular Essbase Server, application or database.
Syntax
ESS_FUNC_M EssListUsersEx (hCtx, AppName, DbName, SecurityProvider, pCount, ppUserList);
DbName ESS_STR_T Database name. If NULL, lists users for all databases within
application.
SecurityProvider ESS_STR_T Name of the external authentication mechanism.
ppUserList “ESS_USERINFOEX_T” on page Address of pointer to receive an allocated array of user info
189 structures. The AppName and DbName fields of the returned user
info structures contain NULL values.
Notes
application and database are listed. If DbName is NULL, only users with access to the
specified application are listed. If AppName is NULL, all users that exist on the server are
listed.
NULL values.
492
Return Value
Access
Example
ESS_STS_T
ESS_ListUsers (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STS_T sts;
ESS_USHORT_T Count;
ESS_USHORT_T ind;
sts = EssListUsersEx (hCtx, NULL, NULL, &Count,

&Users);
if (!sts)
{
if (Count && Users)
{
printf ("\r\n-------User List-------\r\n\r\n");
{
Users[ind].DbName);
}
}
else
}
return (sts);
}
See Also
l EssGetUser
l EssListGroups
l EssListLocks
l EssCreateExtUser
l EssGetUserEx
l EssSetUserEx
493
EssListUsersInfoEx
Lists all users who have access to a particular Essbase Server, application or database. Similar to
EssListUsers, but the user list structure can include user directories and unique identity
attributes.
Syntax
ESS_FUNC_M EssListUsersInfoEx (hCtx, AppName, DbName, pCount, ppUserList);
AppName ESS_STR_T Application name (input). If NULL, lists all users.
DbName ESS_STR_T Database name (input). If NULL, lists users for all databases within the
application.
pCount ESS_PUSHORT_T Address of variable to receive count of users (output).
ppUserList ESS_PPUSERINFOID_T Address of pointer to receive an allocated array of user info structures (output).
The user list structure can include user directories and unique identity attributes.
Return Value
If successful, returns a count of the number of users in pCount, and a list of users with access to
Access
Example
void DisplayUserInfoID2(ESS_USERINFOID_T userInfo)

{
printf("\tUser Name: %s\n", userInfo.Name);

printf("\tProvider Name: %s\n", userInfo.ProviderName);
printf("\tConnparam: %s\n", userInfo.connparam);
printf("\tDescription: %s\n", userInfo.Description);
printf("\tEMail Identification: %s\n", userInfo.EMailID);
if (userInfo.LockedOut)
else
if (userInfo.PwdChgNow)
else
printf( "\tConnected Application: %s\n", userInfo.AppName);
494
printf( "\tConnected Database: %s\n", userInfo.DbName);
if (userInfo.Login)
else
switch(userInfo.Access)
{
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userInfo.Access);
break;
break;
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userInfo.Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userInfo.Access);
break;
495
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userInfo.Access);
break;
case ESS_PRIV_CALC:
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userInfo.Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userInfo.Access);
break;
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userInfo.Access);
break;
default:
}
switch(userInfo.MaxAccess)
{
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userInfo.MaxAccess);
break;
break;
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userInfo.MaxAccess);
break;
496
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userInfo.MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userInfo.MaxAccess);
break;
case ESS_PRIV_CALC:
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userInfo.MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userInfo.MaxAccess);
break;
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userInfo.MaxAccess);
break;
default:
}
printf("\tPassword Expiration in Dates: %d\n",userInfo.Expiration);

//EssSdCTime(NULL, userInfo.LastLogin, sizeof(time_string), time_string);
printf("\tFailed Login Attempts Since Then: %d\n", userInfo.FailCount);
printf("\tLogin ID: %ld\n", userInfo.LoginId);
printf( "\n");
}
ESS_STS_T ESS_ListUsersInfo (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_PUSERINFOID_T pUserList;
sts = EssListUsersInfoEx(hCtx, AppName, "", &count, &pUserList);

printf("EssListUsersInfoEx sts: %ld\n", sts);
if(!sts)
{
printf("\tNumber of users: %d\n\n", count);
{
DisplayUserInfoID2(pUserList[i]);
}
}
497
return (sts);
}
See Also
l EssCreateExtUser
EssListVariables
Lists substitution variables at the server, application, and database levels, according to the input
criteria.
Syntax
ESS_FUNC_M EssListVariables (hCtx, pCriteria, pNumVars, ppVarList);
pCriteria “ESS_VARIABLE_T” on The pointer to the structure containing the description of the substitution
page 191 variables being listed.
l The members VarName and VarValue are ignored.
l If the Server member is given but AppName and DbName are empty, then
the function will list substitution variables at the server level only.
l If the Server and AppName members are given but DbName is empty, it
lists all variables at both the given server and application levels.
l If all three of Server, AppName, and DbName members are given, it lists
variables from all three specified levels.
l If a field is empty, then that field is treated as a "don't care."
pNumVars ESS_PULONG_T The pointer to an unsigned long value indicating the number of variables being
returned in the ppVarList parameter.
ppVarList “ESS_VARIABLE_T” on The pointer to an array of substitution variable structures. It is the responsibility
page 191 of the caller to free this array by calling EssFree.
Return Value
Example
/*
** ESS_ListVariables() lists the substitution variables using
** the API EssListVariables.
*/
ESS_FUNC_M
ESS_ListVariables (ESS_HCTX_T hCtx)
{
ESS_PVARIABLE_T pVariables;
ESS_ULONG_T ulCount, i;
498
printf("\n *****************************************");
printf("\n **** An example of using EssListVariables");
printf("\n *****************************************");
/*****************************************************************/
/* List Variables at the level of the Server/App/Db */
/* Variables under that specific server will be listed */
/* Variables under that specific server/ App will be listed */
/* Variables under that specific server/ App /DB will be listed */
/*****************************************************************/
strcpy(Variable.VarName, ""); // ignored by EssListVariables
{
printf("\n--- Number of Substitution Variables at the Server, App and Db
{
}
}
/****************************************************************/
/* Variables under that specific Server will be listed */
/* Variables under that specific Server/App will be listed */
/****************************************************************/
{

{
printf("\n--- Number of Substitution Variables at the Server and App
{
}
}
}
/***************************************************************/
/* List Variables at the level of the Server */
/***************************************************************/
499
{
{
printf("\n--- Number of Substitution Variables at the Server level is:
%ld\n", ulCount);
{
}
}
}
printf("\n --> No Errors in EssListVariables\n\n\n");
else
printf("\n --> Error in EssListVariables number: %d\n\n\n", sts);
return (sts);
} /* end ESS_ListVariables */
Output
*****************************************
**** An example of using EssListVariables
*****************************************
--- Number of Substitution Variables at the Server, App and Db level is: 3
Variable name : QuarterName
Server name : local
Database name : Basic
Variable value : Qtr2
Server name : local
Database name :
Server name : local
Application name :
Database name :
--- Number of Substitution Variables at the Server and App level is: 2
Server name : local
Database name :
500
Server name : local
Application name :
Database name :
--- Number of Substitution Variables at the Server level is: 1

Server name : local
Application name :
Database name :
--> No Errors in EssListVariables
See Also
l EssCreateVariable
l EssDeleteVariable
l EssGetVariable
EssLoadAlias
Creates and permanently loads an alias table for the active database from a structured text file.
Syntax
ESS_FUNC_M EssLoadAlias (hCtx, AliasName, FileName);
AliasName ESS_STR_T Name of alias table to load.
FileName ESS_STR_T Full path name of structured alias names file on the server.
Notes
l This function cannot complete successfully if AliasName already exists. Before you can load
an alias table with the same name as an existing table, you must delete the existing alias table.
l The alias table file format is described in the Oracle Essbase Database Administrator's
Guide.
Return Value
None.
Access
501
Example
ESS_FUNC_M
ESS_LoadAlias (ESS_HCTX_T hCtx)
{
ESS_STR_T TableName;
ESS_STR_T FileName;
TableName = "NewAlias";
FileName = "NEW.ALT";
sts = EssLoadAlias (hCtx, TableName, FileName);
return (sts);
}
See Also
l EssListAliases
l EssSetActive
EssLoadApplication
Starts an application on the server.
Syntax
ESS_FUNC_M EssLoadApplication (hCtx, AppName);
AppName ESS_STR_T Name of application to load.
Notes
To load an application, the connected user must have load access to the application.
Return Value
None.
Access
This function requires the caller to have Application Load/Unload privilege
(ESS_PRIV_APPLOAD) for the specified application.
Example
ESS_FUNC_M
ESS_LoadApp (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
sts = EssLoadApplication (hCtx, AppName);
502
return (sts);
}
See Also
l EssLoadDatabase
l EssUnloadApplication
EssLoadBufferInit
Creates a temporary data load buffer, which provides temporary storage for tuples during a data
load into an aggregate storage database. Applies only to aggregate storage databases.
Syntax
ESS_FUNC_M EssLoadBufferInit (hCtx, AppName, DbName, ulBufferId,
ulOptionFlags, ulSize);
AppName ESS_STR_T Name of the application for which to create the load buffer.
DbName ESS_STR_T Name of the database for which to create the load buffer.
ulBufferId ESS_ULONG_T ID number for the data load buffer (a number between 1 and 999,999, inclusive).
If the ID is already in use, the operation fails.
503
ulDuplicateAggregationMethod ESS_ULONG_T One of the following constants for combining multiple values for the same cell
within the buffer:
l ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD: Add values
when the buffer contains multiple values for the same cell.
#define ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD 0
l ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ASSUME_EQUAL:
Verify that multiple values for the same cells are identical; if they are, ignore
the duplicate values. If the values for the same cell differ, stop the data load
with an error message.
#define
ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ASSUME_EQUAL
1
l ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_USE_LAST:
Combines duplicate cells by using the value of the cell that was loaded last
into the load buffer. This option is intended for relatively small data loads
of up to 10,000s of cells.
#define
ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_USE_LAST 2
When using data load buffers with the use_last option, data loads are
significantly slower, even if there are not any duplicate values.
Caution! The use_last method has significant performance impact, and

is not intended for large data loads. If your data load is larger
than one million cells, consider separating the numeric data
into a separate data load process (from any typed measure
data). The separate data load can use the add method instead.
504
ulOptionFlags ESS_ULONG_T One or more of the following load buffer options:

l ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES:
Ignores #MISSING values in the incoming data stream.
#define
ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES
0x00000001
l ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES:
Ignores zeros in the incoming data stream.
#define
ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES
0x00000002
l ESS_ASO_DATA_LOAD_BUFFER_WAIT_FOR_RESOURCES: Tells
Essbase to wait up to the amount of time specified by the
ASOLOADBUFFERWAIT configuration setting in essbase.cfg for
resources to become available in order to process load buffer operations.
#define
ESS_ASO_DATA_LOAD_BUFFER_WAIT_FOR_RESOURCES
0x00000004
Use bitwise OR (|) to specify multiple ulOptions; for example:

ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES |
ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES
ulSize ESS_ULONG_T Percentage of total load buffer resources this load buffer may use. Possible values:
0 to 100.
For a value of 0, Essbase uses a self-determined, default load buffer size.
If the total size of all load buffers exceeds 100, the operation fails.
Notes
Multiple buffers can exist on a single aggregate storage database; however, only one data load
may use a given load buffer at a time.
Return Value
Example
{
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
505
ESS_ULONG_T ulSize;
ulSize = 100;
ulBufferId = 201;

Store = ESS_TRUE;
Unlock = ESS_FALSE;

ulBufferId);
ulBufferCnt = 1;
ulCommitType,
See Also
l EssSendString
l EssEndDataload
l EssLoadBufferTerm
l EssImportASO
l EssUpdateFileASO
506
EssLoadBufferTerm
Destroys the temporary data-load memory buffer(s) allocated by EssLoadBufferInit for
loading data into an aggregate storage database. Optionally, the data can be committed first.
Applies only to aggregate storage databases.
Syntax
ESS_FUNC_M EssLoadBufferTerm (hCtx, AppName, DbName, ulBufferCnt, *ulBufferIdAry,
ulCommitType,
AppName ESS_STR_T Name of the application.
DbName ESS_STR_T Name of the database.
ulBufferCnt ESS_ULONG_T Number of buffers in the list.
*ulBufferIdAry ESS_ULONG_T Array of buffer IDs that will be affected by this operation.
507
ulCommitType ESS_ULONG_T One of the following constants for combining the values stored in the buffer with
the values already stored in the database:
l ESS_ASO_DATA_LOAD_BUFFER_STORE_DATA: Replace existing cell
values in the database with the new values from the load buffer. Cells in the
database that do not have corresponding values in the buffer are not updated.
#define ESS_ASO_DATA_LOAD_BUFFER_STORE_DATA 0
l ESS_ASO_DATA_LOAD_BUFFER_ADD_DATA: Add new values to the
existing ones.
#define ESS_ASO_DATA_LOAD_BUFFER_ADD_DATA 1
l ESS_ASO_DATA_LOAD_BUFFER_SUBTRACT_DATA: Subtract new
values from the existing ones.
#define ESS_ASO_DATA_LOAD_BUFFER_SUBTRACT_DATA 2
l ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_ALL_DATA: Atomically
destroy all existing data cells in the database (even cells in the database that do
not have corresponding values in the load buffer) and load the contents of the
load buffer in one operation.
#define ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_ALL_DATA 3
When using the override all data option, the ulOptions setting is ignored. Essbase
always writes the data currently stored in the buffer to the main slice in the
database.
l ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_INCREMENTAL_DATA:
Atomically destroy all data cells currently stored in any incremental slice and
load the contents of the load buffer.
#define
ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_INCREMENTAL_DATA 4
When using the override incremental data option and the ulOptions setting is
main slice, Essbase ignores the ulOptions setting and writes the data currently
stored in the buffer to a new slice in the database.
When committing multiple buffers, the values from different buffers are always
combined using the add operation, regardless of this ulCommitType setting or how
the buffers themselves are configured.
Note: If the ulActionType setting is abort, the ulCommitType setting is ignored.
ulActionType ESS_ULONG_T One of the following constants:

l ESS_ASO_DATA_LOAD_BUFFER_COMMIT: Load the data from the load
buffer to the database; then destroy the buffer.
#define ESS_ASO_DATA_LOAD_BUFFER_COMMIT 1
l ESS_ASO_DATA_LOAD_BUFFER_ABORT: Destroy the load buffer. All data
in the buffer is lost.
#define ESS_ASO_DATA_LOAD_BUFFER_ABORT 2
When using the abort option, the ulCommitType and ulOptions settings are
ignored
508
ulOptions ESS_ULONG_T One of the following constants:

l ESS_ASO_DATA_LOAD_INCR_TO_MAIN_SLICE: Write the data
currently stored in the buffer to the main slice in the database.
#define ESS_ASO_DATA_LOAD_INCR_TO_MAIN_SLICE 0
When using the incremental to main slice option, and the ulCommitType setting
is override incremental data, Essbase ignores the ulOptions setting and writes
the data currently stored in the buffer to a new slice in the database.
l ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE: Write the data currently
stored in the buffer to a new slice in the database. This operation speeds up the
data load.
#define ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE 1
l ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE_LIGHTWEIGHT:
Write the data currently stored in the buffer to a new slice in the database, as a
lightweight operation. This option is intended only for very small data loads of
up to 1,000s of cells that occur concurrently (for example, grid client data-
update operations).
#define
ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE_LIGHTWEIGHT 2
Note: If the ulCommitType setting is override all data, the ulOptions setting is
ignored. Essbase always writes the data currently stored in the buffer to the
main slice in the database. If the ulActionType setting is abort, the
ulOptions setting is ignored
Notes
This function destroys the specified set of load buffers (usually a single load buffer). If the
specified action type is "commit," data currently stored in the buffer is applied to the database
before the buffers are destroyed.
Return Value
Example
{
ESS_BOOL_T Store;
ESS_BOOL_T Unlock;
ESS_ULONG_T ulSize;
509
ulSize = 100;
ulBufferId = 201;

Store = ESS_TRUE;
Unlock = ESS_FALSE;

ulBufferId);
ulBufferCnt = 1;
ulCommitType,
See Also
l EssLoadBufferInit
l EssSendString
l EssEndDataload
l EssImportASO
l EssUpdateFileASO
510
EssLoadDatabase
Starts a database within an application on the server.
Syntax
ESS_FUNC_M EssLoadDatabase (hCtx, AppName, DbName);
DbName ESS_STR_T Name of database to load.
Return Value
None.
Access
This function requires the caller to have database load/unload privilege
(ESS_PRIV_APPLOAD).
Example
ESS_FUNC_M
ESS_LoadDb (ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssLoadDatabase(hCtx, AppName, DbName);
return (sts);
}
See Also
l EssUnloadDatabase
EssLocateIBH
Locates invalid block headers within the database. At the end of the locate process, a server-based
IBH log file is created that can be used later in EssFixIBH to fix the errors.
Syntax
ESS_FUNC_M EssLocateIBH (hCtx, dbName);
511
dbName; ESS_STR_T Name of the database.
See Also
l EssFixIBH
l EssGetIBH
EssLockObject
Locks an object on the server or the client object system to prevent other users from updating
it.
Syntax
ESS_FUNC_M EssLockObject (hCtx, ObjType, AppName, DbName, ObjName);
ObjName ESS_STR_T Name of object to lock.
Notes
l To lock an object, the object must already exist and not be locked by another user.
l This function does not retrieve the object. Use EssGetObject to retrieve the object.
Return Value
None.
Access
This function requires the caller to have application or database design privilege
Example
ESS_FUNC_M
ESS_LockObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
512
ESS_STR_T DbName;
ESS_STR_T ObjName;
AppName = "Sample";
DbName = "Basic";
ObjName = "Basic";
sts = EssLockObject (hCtx, ObjType, AppName,

DbName,ObjName);
if(!sts)
printf("The Object \"%s\" is locked\r\n",
ObjName);
return (sts);
}
See Also
l EssGetObject
l EssGetObjectInfo
l EssListObjects
l EssPutObject
l EssUnlockObject
EssLogin
Logs a user in to an Essbase Server. This function should normally be called after executing a
successful call to EssInit, and prior to making any other API calls which require a context
handle argument.
Syntax
ESS_FUNC_M EssLogin (hInstance, Server, UserName, Password, pDbCount, ppDbList, phCtx);
Server ESS_STR_T Network server name string.

The server name can be expressed as hostname, hostname:port, or as a URL
representing the APS servlet endpoint with the Essbase failover cluster name; for
example:.
Cluster1

For example,
513
UserName ESS_STR_T User name string.
Password ESS_STR_T Password string.
pDbCount ESS_PUSHORT_T Address of variable to receive count of accessible applications/databases.
ppDbList “ESS_APPDB_T” on Address of pointer to receive allocated array of application/database name

page 108 structures.
phCtx ESS_PHCTX_T Pointer to an Essbase Server context handle.
Notes
l If you are programming in Microsoft Windows, you should consider using the
EssAutoLogin function instead of EssLogin.
l Memory allocated for ppDbList must be freed using EssFree.
l You can call this function more than once for the same user name and server. The API
returns a unique context handle for each login to the specified server.
Return Value
If successful, returns an Essbase Server context handle in phCtx, which can be used as an
argument in subsequent calls to other API functions. Also returns a count of databases accessible
to the specified user in pCount, and a list of accessible applications and databases in ppDbList.
Access
by calling EssInit.
Example
ESS_FUNC_M
ESS_Login (ESS_HINST_T hInst)
{
ESS_HCTX_T hCtx;
ESS_USHORT_T Items;
ESS_USHORT_T ind;
ESS_STR_T SvrName;
ESS_STR_T User;
ESS_STR_T Password;
SvrName = "POPLAR";
User = "Joseph";
sts = EssLogin (hInst, SvrName, User, Password,

&Items, &pAppsDbs, &hCtx);
if (!sts)
{
{
514
{
{
printf ("%s\r\n", pAppsDbs[ind].AppName);
printf ("%s\r\n", pAppsDbs[ind].DbName);
}
}
}
}
return(sts);
}
See Also
l EssAutoLogin
l EssLoginAs
l EssLoginEx
l EssLoginExAs
l EssInit
l EssListDatabases
l EssLogout
l EssSetActive
EssLoginAs
Logs in to Essbase Server as another user. Logging in as another user can help administrators
create scheduled reports with user-appropriate permissions.
This function should normally be called after executing a successful call to EssInit, and prior
to making any other API calls which require a context handle argument.
Syntax
ESS_FUNC_M EssLoginAs (hInstance, Server, UserName, Password, UserNameAs, pDbCount,
ppDbList, phCtx);
515

example:
Cluster1

For example,
UserName ESS_STR_T User name string.
Password ESS_STR_T Password string.
UserNameAs ESS_STR_T User name string for the user you want to impersonate.

Notes
l You can call this function more than once for the same user name and server. The API
returns a unique context handle for each login to the specified server.
Return Value
Access
You must be an administrator to log in as another user.
by calling EssInit.
See Also
l EssAutoLogin
l EssLoginExAs
l EssInit
l EssListDatabases
516
l EssLogout
l EssSetActive
EssLoginEx
Logs in a user to an Essbase Server using a user authentication token rather than a username
and password. This function should normally be called after executing a successful call to
EssInit, and prior to making any other API calls which require a context handle argument.
Syntax
ESS_FUNC_M EssLoginEx (hInstance, Server, Token, pDbCount, ppDbList, phCtx);

example:
Cluster1

For example,
Token ESS_STR_T The token representing the username and password of an authenticated user.
ppDbList “ESS_APPDB_T” on Address of pointer to receive allocated array of application/database name structures.
page 108
Notes
l If this function fails, the corresponding EssLogin function is automatically called in order
to try to verify a username and password for the user.
Return Value
517
Access
by calling EssInit.
See Also
l EssLogin
l EssLoginAs
l EssLoginExAs
l EssAutoLogin
l EssInit
l EssListDatabases
l EssLogout
l EssSetActive
EssLoginExAs
Logs in an administrator to an Essbase Server as another user, and using a user authentication
token rather than the administrator username and password. This function should normally be
called after executing a successful call to EssInit, and prior to making any other API calls which
require a context handle argument.
Logging in as another user can help administrators create scheduled reports with user-
appropriate permissions.
Syntax
ESS_FUNC_M EssLoginExAs (hInstance, Server, Token, UserNameAs, pDbCount, ppDbList,
phCtx);

example:
Cluster1

For example,
Token ESS_STR_T The token representing the user name and password of an authenticated user.
UserNameAs ESS_STR_T User name string for the user you want to impersonate.
518

Notes
l If this function fails, the corresponding EssLoginAs function is automatically called in
order to try to verify a username and password for the user.
Return Value
Access
You must be an administrator to log in as another user.
by calling EssInit.
See Also
l EssLogin
l EssLoginAs
l EssAutoLogin
l EssInit
l EssListDatabases
l EssLogout
l EssSetActive
EssLoginSetPassword
Logs in a user, and changes the password. Use this function if the password expires, or must be
changed at the next login.
Syntax
HInstance ESS_HINST_T API instance handle.
519

example:
Cluster1

For example,
Password ESS_STR_T Old password.
NewPassword ESS_STR_T New password.
pDbCount ESS_PUSHORT_T Number of accessible databases.
ppDbList ESS_PPAPPDB_T Address of the pointer to an array of accessible application-database structures.
phCtx ESS_PHCTX_T Pointer to the context handle.
Notes
l Call this function after you call EssLogin, and after you receive status code 1051090
(Password has expired), or 1051093 (Change password now).
l In Microsoft Windows, consider using EssAutoLogin, instead of EssLoginSetPassword.
l Free memory allocated for ppDbList using EssFree.
Return Value
If successful, this function returns:
l In hCtx, the context handle.
l In pDbCount, the number of databases accessible to the user.
l In ppDbList, the pointer to an array of accessible application-database structures.
Access
Before you call this function, call EssInit to initialize the API, and obtain a valid instance
handle.
Example
ESS_FUNC_M
ESS_LoginSetPassword (ESS_HINST_T hInst)
{
520
ESS_HCTX_T hCtx;
ESS_USHORT_T Items;
ESS_USHORT_T ind;
ESS_STR_T SvrName;
ESS_STR_T User;
ESS_STR_T Password;
ESS_STR_T NewPassword;
SvrName = "POPLAR";
User = "Joseph";
NewPassword = "NewPassword";
sts = EssLoginSetPassword (hInst, SvrName, User, Password, NewPassword

if (!sts)
{
{
{
{
printf ("%s\r\n", pAppsDbs[ind].AppName);
printf ("%s\r\n", pAppsDbs[ind].DbName);
}
}
}
if (pAppsDbs)
EssFree(hInst,pAppsDbs);
}
return(sts);
}
See Also
l EssAutoLogin
l EssInit
l EssListDatabases
l EssLogout
l EssSetActive
EssLogout
Logs out a user from an Essbase Server.
Syntax
ESS_FUNC_M EssLogout (hCtx);
521
hCtx ESS_HCTX_T API context handle to logout.
Notes
l This function logs out only the login represented by the specified context handle. No other
logins or contexts are affected, even if using the same user name.
l This function should only be used for login contexts. For local contexts, use the
EssDeleteLocalContext function.
Return Value
None.
Access
To call this function, the caller must have previously logged in successfully using either the
EssLogin or EssAutoLogin functions.
Example
ESS_FUNC_M
ESS_Logout (ESS_HCTX_T hCtx)
{
return(sts);
}
See Also
l EssAutoLogin
l EssDeleteLocalContext
l EssGetActive
l EssLogin
l EssLogoutUser
EssLogoutUser
Allows a Supervisor or an Application Designer to disconnect another user from an Essbase
Server.
Syntax
ESS_FUNC_M EssLogoutUser (hCtx, LoginId);
hCtx ESS_HCTX_T API context handle of user forcing the log out.
LoginId ESS_LOGINID_T Login ID of user to be logged out.
522
Notes
l LoginId can be obtained from the user information structure returned by the
EssListConnections function.
l This function logs out only the login represented by the specified LoginId. No other logins
or contexts are affected.
l A Supervisor can log out anyone logged in to the server to which hCtx is logged in. An
Application Designer can log out only those users connected to an application for which
hCtx is an Application Designer. You cannot log yourself out.
Return Value
None.
Access
To call this function, you must have Supervisor or Application Designer privilege.
Example
ESS_FUNC_M ESS_LogoutUser (ESS_HCTX_T hCtx,
ESS_HINST_T hInst)
{
ESS_USHORT_T usrcnt;
ESS_PUSERINFO_T users;
sts = EssListConnections(hCtx, &usrcnt,
&users);
if(!sts)
{
if(usrcnt > 0)
{
/***************************************
* Log out first user from the list *
***************************************/
sts = EssLogoutUser(hCtx, users[0].LoginId);
if(!sts)
EssFree(hInst, users);
}
}
return(sts);
}
See Also
l EssLogout
EssLogSize
Returns the size of the Essbase Server log file (essbase.log), or of the application log file
(appname.log).
523
Syntax
ESS_FUNC_M EssLogSize (hCtx, AgentLog, pszAppName, pulLogSize);
AgentLog ESS_BOOL_T If TRUE, the size of the Essbase Server log file (essbase.log) is returned. If
FALSE, the size of the application log file (appname.log) is returned.
pszAppName ESS_STR_T Application name.
pulLogSize ESS_PULONG_T Size of log file returned.
Notes
Return Value
Access
This function does not require the caller to have access privileges.
Example
ESS_FUNC_M ESS_LogSize (ESS_HCTX_T hCtx)
{
ESS_STR_T pszAppName = NULL;
ESS_ULONG_T ulLogSize = 0;
pszAppName = "Sample";
/*
* Get the log file size for the "Sample" application.
*/
sts = EssLogSize(hCtx, ESS_FALSE, pszAppName, &ulLogSize);
return(sts);
}
See Also
l EssDeleteLogFile
l EssGetLogFile
l EssWriteToLogFile
EssLROAddObject
Links reporting objects to a data cell in an Essbase database.
524
Syntax
ESS_FUNC_M EssLROAddObject (hCtx, memCount, pMemComb, usOption,
pLRODesc);
memCount ESS_ULONG_T The number of members specified in pMemComb.
pMemComb ESS_PVOID_T Array of the member names that define the data cell to be linked.
usOption ESS_USHORT_T Option specifying where to store the object. Use one of these values:
l ESS_STORE_OBJECT_API to store an object on the server.
l ESS_NOSTORE_OBJECT_API to not store the object on a server.
pLRODesc “ESS_LRODESC_API_T” on Pointer to object's description structure.

page 102
Notes
l The linked object can be any of the following types:
m A flat file, such as a Word document, Excel spreadsheet, or bitmap image.
m A cell note containing up to 599 characters of text.
m A link to a URL.
m A link to another Essbase database (a linked partitions feature).
l If you elect not to store the object on the server (usOption), your application is responsible
for all file management tasks for the object (that is, because the object is not being stored
with the Essbase database, some other program must take responsibility for it).
l The usOption parameter is ignored for cell notes, which are always stored on the server.
l The usOption parameter for a URL linked object should always be
ESS_NOSTORE_OBJECT_API.
l EssLROAddObject uses the currently logged in user name as the "created by" user name for
the object and ignores any user name specified in the pLRODesc object description structure.
Return Value
If successful, returns ESS_STS_NOERR. Otherwise, returns an error code.
Access
A call to this function requires write privileges (ESS_PRIV_WRITE) to the active database.
Example
ESS_STS_T ESS_LROAddObject (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_PMBRNAME_NONUNI_T pMemComb = NULL;
ESS_LRODESC_API_T lroDesc;
ESS_USHORT_T usOption = 0;
525
ESS_ULONG_T memCount;
memset (&lroDesc, 0 , sizeof(ESS_LRODESC_API_T));
lroDesc.usObjType = 0; /* Creating a cell note */

strcpy(lroDesc.lro.note, "The profit for Colas in the East based on actuals");
usOption = ESS_NOSTORE_OBJECT_API;
strcpy(lroDesc.userName, "user1");
memCount = 5;
sts = EssAlloc(hInst, memCount*sizeof(ESS_MBRNAME_NONUNI_T),

(ESS_PPVOID_T)&pMemComb);
if (sts)
{
printf("could not allocate memory\n");
return sts;
}
memset(pMemComb, 0, memCount*sizeof(ESS_MBRNAME_NONUNI_T));
strcpy( pMemComb[0], "Profit");
strcpy( pMemComb[1], "East");
strcpy( pMemComb[2], "Actual");
strcpy( pMemComb[3], "Colas");
strcpy( pMemComb[4], "Year");
sts = EssLROAddObject( hCtx, memCount, pMemComb, usOption, &lroDesc);
if (sts)
{
printf( "Could not attach LRO\n");
}
EssFree(hInst, pMemComb);
return sts;
}
See Also
l “LRO Constant and Structure Definitions (C)” on page 101
l EssLROGetObject
l EssLROUpdateObject
l EssLRODeleteObject
EssLRODeleteCellObjects
Deletes all objects linked to a given data cell in an Essbase database. To delete a specific object
linked to a cell, use EssLRODeleteObject.
Syntax
ESS_FUNC_M EssLRODeleteCellObjects (hCtx, memCount, pMemComb, pulLROCount, pLRODescList);
526
memCount ESS_ULONG_T Number of members specified in pMemComb.
pMemComb ESS_PVOID_T Array of member names.
pulLROCount ESS_ULONG_T Number of LRO catalog entries deleted.
pLRODescList “ESS_LRODESC_API_T” on page 102 List of LRO catalog entries deleted.
Notes
l This function deletes all objects linked to the specified cell along with their catalog entries.
l If the object is not stored on the server, only the cell link is destroyed; the file is not deleted.
l The caller is responsible for freeing memory allocated for pLRODescList.
Return Value
Access
Example
ESS_FUNC_M ESS_LRO DeleteCellObjects (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_LRODESC_API_T plroDescList=NULL;
ESS_ULONG_T ulLroCount;
memCount = 5;
if(sts)
{
printf("Could not allocate memory \n");
return sts;
}
sts = EssLRODeleteCellObjects(hCtx, memCount, pMemComb, &ulLroCount,
&plroDescList);
if (sts)
{
printf ("Could not delete cell objects. \n");
}
EssFree( hInst, pMemComb);
if (plroDescList)
EssFree(hInst, plroDescList);
527
return sts;
}
See Also
l EssLROAddObject
l EssLROPurgeObjects
EssLRODeleteObject
Deletes a specific object linked to a data cell in an Essbase database. To delete all objects linked
to a cell, use EssLRODeleteCellObjects.
Syntax
ESS_FUNC_M EssLRODeleteObject (hCtx, plinkId);
plinkId “ESS_LROHANDLE_API_T” on page 103 Pointer to object identification structure.
Notes
l The specified object is deleted and also removed from the Catalog list.
l If the object is not stored on the server, only the cell link is destroyed; the file is not deleted.
Return Value
Access
Example
ESS_FUNC_M Ess_LRO DeleteObject (ESS_HCTX_T hCtx)
{
ESS_LROHANDLE_API_T linkId;
memset(&linkId, 0, sizeof(ESS_LROHANDLE_API_T));
linkId.hObject = 26;
linkId.cellKey.cellOffset = 282;
linkId.cellKey.blkOffset = 113;
linkId.cellKey.segment = 0;
sts = EssLRODeleteObject(hCtx, &linkId);
if (sts)
{
printf("Could not delete object\n");
}
return sts;
}
528
See Also
l EssLROAddObject
l EssLRODeleteCellObjects
EssLROGetCatalog
Retrieves a list of LRO catalog entries for a given data cell in an Essbase database.
Syntax
ESS_FUNC_M EssLROGetCatalog (hCtx, memCount, pMemComb, pulLROCount, ppLRODescList)
memCount ESS_ULONG_T Number of members specified in pMemComb.
pMemComb ESS_PMBRNAMECOMB_T Array of member names.
pulLROCount ESS_ULONG_T * Number of LRO catalog entries returned to caller.
pLRODescList “ESS_LRODESC_API_T” on page 102 Address of pointer to the list of LRO catalog entries returned
to caller.
Return Value
Access
Example
ESS_FUNC_M ESS_LRO GetCatalog (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_PLRODESC_API_T plroDescList=NULL;
ESS_USHORT_T usOption = 0;
memCount = 5;
if(sts)
{
printf("Could not allocate memory \n");
return sts;
}
529
sts = EssLROGetCatalog(hCtx, memCount, pMemComb, &ulLroCount, &plroDescList);
if (sts)
{
printf ("Could not get the catalog \n");
}
if(plroDescList)
{
}
return sts;
}
See Also
l EssLROGetCatalogBatch
l EssLROAddObject
l EssLROGetObject
EssLROGetCatalogBatch
Retrieves a list of LRO catalog entries for multiple data cells in an Essbase database.
Syntax
ESS_FUNC_M EssLROGetCatalogBatch (hCtx, memCount, pMemComb, cellCount, pulLROCount,
ppLRODescList)
memCount ESS_ULONG_T * Array of 'Number of members' specified in pMemComb,, one for

each cell.
pMemComb ESS_PMBRNAMECOMB_T * Array of 'member name' combination. Each element of array itself
is an array of member names, one for each cell.
cellCount ESS_ULONG_T Count of LRO cells.
pulLROCount ESS_ULONG_T * Array of 'Number of LRO' catalog entries returned to caller. Each
element in array corresponds to the number of LRO catalog entries
for an input cell.
pLRODescList “ESS_LRODESC_API_T” on page Address of pointer to the list of LRO catalog entries returned to
102 caller.
530
Notes
To use this function, initialize the program with the MaxBuffer field of the initialization structure
ESS_INIT_T set to 0xFFFFFFFF bytes.
Return Value
Access
Example
/*
* ESS_GetLinkedObjectCatalogBatch() -- Gets a list of LRO description for a list of
given data cell
* From the Database Sample.Basic, it will fetch LROs for the following Cells.
* 1) "Jan", "Sales", "100-10", "New York", "Actual"
* 2) "Feb", "COGS", "200-10", "Utah", "Budget"
* 3) "Mar", "Payroll", "300-10", "Texas", "Variance"
*/
ESS_STS_T ESS_GetLinkedObjectCatalogBatch(ESS_HINST_T hInst, ESS_HCTX_T hCtx)
{
ESS_STS_T status = 0;
ESS_UINT_T memberLength = ESS_MBRNAMELEN_NONUNI;
ESS_PMBRNAME_NONUNI_T *ppMemComb=NULL;
ESS_ULONG_T *pulLroCount= NULL;
ESS_PLRODESC_API_T pLroDescList = NULL;
ESS_PLRODESC_API_T *ppLroDescList = NULL;
ESS_ULONG_T cellCount = 3; /* Number of cells for which to
retrieve LROs */
ESS_ULONG_T mbrsCount[3] = {5, 5, 5}; /* Number of members in
combinations for each cell */
ESS_ULONG_T i,j,k,offset;
ESS_CHAR_T *pMember = NULL;
ESS_CHAR_T response;
status = EssAlloc(hInst, cellCount * sizeof(ESS_PMBRNAMECOMB_T),

(ESS_PPVOID_T)&ppMemComb);
if (status)
goto exit;
/* Member combination for Cell # 1 */

status = EssAlloc(hInst, mbrsCount[0] * memberLength, (ESS_PPVOID_T)&(ppMemComb[0]));
if (status)
goto exit;
pMemComb = ppMemComb[0];
memset(pMemComb, 0, mbrsCount[0]* memberLength);
strcpy((pMemComb)[0], "Jan");
strcpy((pMemComb)[1], "Sales");
strcpy((pMemComb)[2], "100-10");
strcpy((pMemComb)[3], "New York");
strcpy((pMemComb)[4], "Actual");
531
if (status)
goto exit;
memset(pMemComb, 0, mbrsCount[1] * memberLength);
strcpy((pMemComb)[0], "Feb");
strcpy((pMemComb)[1], "COGS");
strcpy((pMemComb)[3], "Utah");
strcpy((pMemComb)[4], "Budget");

if (status)
goto exit;
memset(pMemComb, 0, mbrsCount[2] * memberLength);
strcpy((pMemComb)[0], "Mar");
strcpy((pMemComb)[1], "Payroll");
strcpy((pMemComb)[3], "Texas");
strcpy((pMemComb)[4], "Variance");
/* Will hold inormation about how many LROs fetched for each Cell */
status = EssAlloc(hInst, cellCount * sizeof(ESS_ULONG_T),
(ESS_PPVOID_T)&pulLroCount);
if (status)
goto exit;
memset(pulLroCount, 0, cellCount * sizeof(ESS_ULONG_T));
ppLroDescList = &pLroDescList;
status = EssLROGetCatalogBatch(hCtx, mbrsCount, ppMemComb, cellCount, pulLroCount,

ppLroDescList);
if (status)
goto exit;
for (k=0, offset=0; k<cellCount; k++)

{
ESS_LRODESC_API_T *pLroDesc = &pLroDescList[offset];
for (i=0; i<pulLroCount[k]; i++, offset++)
{
printf("***** information for linked object ********\n");
printf("Object type - %2d\n", (pLroDesc+i)->usObjType);
printf("Link Id : \n");
printf(" Object handle - %d \n", (pLroDesc+i)->linkId.hObject);
printf(" Cell offset - %d \n", (pLroDesc+i)->linkId.cellKey.cellOffset);
printf(" Block offset - %lf \n", (pLroDesc+i)->linkId.cellKey.blkOffset);
printf(" Segment - %lf \n", (pLroDesc+i)->linkId.cellKey.segment);
if ((pLroDesc+i)->usObjType > 0)
{
printf("Object name - %s\n",(pLroDesc+i)->lro.lroInfo.objName);
printf("Object description - %s\n",(pLroDesc+i)->lro.lroInfo.objDesc);
}
else
532
{
printf("Cell notes - %s\n",(pLroDesc+i)->lro.note);
}
printf("User name - %s\n", (pLroDesc+i)->userName);
printf("Security Access Level - %d\n", (pLroDesc+i)->accessLevel);
if ((pLroDesc+i)->pMemComb)
{
printf("Member Name : \n");
pMember = (ESS_CHAR_T *) (pLroDesc+i)->pMemComb;
for (j=0; j < (pLroDesc+i)->memCount; j++)
{
printf(" %s\n",pMember);
pMember += memberLength;
}
EssFree(hInst, (pLroDesc+i)->pMemComb);
}
printf("\n");
}
}
printf("********* complete **********\n");
exit:
if (status)
printf("Fail Getting Catalog Information.\n");
if (ppMemComb)
{
for(i=0; i<cellCount; i++)
{
EssFree(hInst, ppMemComb[i]);
}
EssFree(hInst, ppMemComb);
}
if (pLroDescList)
EssFree(hInst, pLroDescList);
if (pulLroCount)
EssFree(hInst, pulLroCount);
return(status);
See Also
l EssLROGetCatalog
l EssLROAddObject
l EssLROGetObject
533
EssLROGetObject
Retrieves an object linked to a data cell in an Essbase database.
Syntax
ESS_FUNC_M EssLROGetObject (hCtx, plinkId, targetFile, usOption,
pRetLRODesc);
plinkId ; “ESS_LROHANDLE_API_T” on Pointer to object identification structure.

page 103
targetFile ESS_STR_T The name of the target file into which the object is retrieved.
usOption ESS_USHORT_T Option specifying whether to retrieve the object, its catalog entry,
or both. Use one of the following:
l ESS_LRO_OBJ_API retrieves only the object.
l ESS_LRO_CATALOG_API retrieves only the catalog entry.
l ESS_LRO_BOTH_API retrieves object and catalog entry.
pRetLRODesc “ESS_LRODESC_API_T” on page Pointer to object's description structure.

102
Notes
Cell notes are part of the catalog entry for an object. To retrieve a cell note, use
ESS_LRO_CATALOG_API for the usOption parameter. The linked note is contained in
structure “ESS_LRODESC_API_T” on page 102.
Return Value
Access
Example
ESS_FUNC_M ESS_LRO GetObject (ESS_HCTX_T hCtx)
{
ESS_USHORT_T usOption = 2; /* Default is catalog */
ESS_CHAR_T targetFile[ESS_ONAMELEN_API];
memset(&lroDesc, 0, sizeof(ESS_LRODESC_API_T));
memset(&linkId, 0, sizeof(ESS_LROHANDLE_API_T));
/* Linked object is a LRO. (Windows Application) */
linkId.hObject = 4;
linkId.cellKey.blkOffset = 113.0;
linkId.cellKey.segment = 0.0;
534
usOption = ESS_LRO_BOTH_API ; /* Get the catalog and the object */
strcpy ( targetFile , "c:\\temp\\lrofile");
sts = EssLROGetObject(hCtx, &linkId, targetFile, usOption, &lroDesc);
if (sts)
{
printf("Could not get object\n");
}
return sts;
}
See Also
l EssLROAddObject
EssLROListObjects
Retrieves a list of all objects linked to cells in the active database for a given user name and/or
modification date.
Syntax
ESS_FUNC_M EssLROListObjects (hCtx, userName, listDate, pulLROCount, pLRODescList));
userName ESS_CHAR_T A user name. If specified, returns a list of all objects last modified by
the given user.
listDate ESS_TIME_T A modification date. If specified, returns a list of all objects modified
before the given date. The time is a ULONG representing the
number of seconds since January 1, 1970.
pulLROCount ESS_ULONG_T * Number of LRO catalog entries returned.
pLRODescList; “ESS_LRODESC_API_T” on Address of pointer to the list of LRO catalog entries returned.
page 102
Notes
l If you specify both the userName and listDate parameters, objects meeting both criteria are
listed.
Return Value
Access
A call to this function requires read privileges (ESS_PRIV_READ) to the active database.
535
Example
ESS_FUNC_M ESS_LRO ListObjects (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_CHAR_T userName[ESS_USERNAMELEN];
ESS_CHAR_T listDate[ESS_DATESIZE];
ESS_CHAR_T buf[ESS_DATESIZE];
ESS_TIME_T timestamp;
struct tm *pTmStruct, time_str;
strcpy( userName, "user1");
strcpy( listDate, "09/05/1997");
time(&timestamp);
pTmStruct = localtime((ESS_PLONG_T)&timestamp);
memset(&time_str, 0, sizeof(struct tm));
strncpy (buf, (const char *)&listDate[8], 2);
time_str.tm_year = atoi(buf);
strncpy(buf, listDate, 2);
time_str.tm_mon = atoi(buf)-1;
strncpy(buf, (const char *)&listDate[3], 2);
time_str.tm_mday = atoi(buf);
time_str.tm_hour = 0;
time_str.tm_min = 0;
time_str.tm_sec = 1;
time_str.tm_isdst = -1;
if ((time_str.tm_mon != pTmStruct->tm_mon) ||
(time_str.tm_year != pTmStruct->tm_year) ||
(time_str.tm_mday != pTmStruct->tm_mday))
{
time_str.tm_mday++;
timestamp = mktime(&time_str);
}
sts = EssLROListObjects(hCtx, userName, timestamp, &ulLroCount, &plroDescList);
if(sts)
{
printf("Could not list linked objects. \n");
}
if (plroDescList)
return sts;
}
See Also
l EssLROGetCatalog
EssLROPurgeObjects
Deletes all objects linked to cells in the active database for a given user name and/or modification
date.
536
Syntax
ESS_FUNC_M EssLROPurgeObjects (hCtx, userName, purgeDate, pulLROCount, pLRODescList);
userName ESS_STR_T Pointer to a user name. If specified, deletes all objects last modified
by the given user.
purgeDate ESS_TIME_T A modification date. If specified, returns a list of all objects modified
before the given date. The date is a ULONG representing the number
of seconds elapsed since January 1, 1970.
pulLROCount ESS_ULONG_T Number of LRO catalog entries purged.
pLRODescList “ESS_LRODESC_API_T” on Address of pointer to the list of LRO catalog entries purged.
page 102
Notes
l If you specify both the userName and purgeDate parameters, objects meeting both criteria
are deleted.
Return Value
Access
A call to this function requires design privileges (ESS_PRIV_DBDESIGN) for the active database.
Example
ESS_FUNC_M ESS_LRO PurgeObjects (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_CHAR_T userName[ESS_USERNAMELEN];
ESS_CHAR_T purgeDate[ESS_DATESIZE];
ESS_CHAR_T buf[ESS_DATESIZE];
ESS_TIME_T timestamp;
struct tm *pTmStruct, time_str;
strcpy( userName, "user1");
strcpy( purgeDate, "09/05/1997");
time(&timestamp);
pTmStruct = localtime((ESS_PLONG_T)&timestamp);
memset(&time_str, 0, sizeof(struct tm));
strncpy (buf, (const char *)&purgeDate[8], 2);
time_str.tm_year = atoi(buf);
strncpy(buf, listDate, 2);
time_str.tm_mon = atoi(buf)-1;
strncpy(buf, (const char *)&purgeDate[3], 2);
time_str.tm_mday = atoi(buf);
time_str.tm_hour = 0;
537
time_str.tm_min = 0;
time_str.tm_sec = 1;
time_str.tm_isdst = -1;
if ((time_str.tm_mon != pTmStruct->tm_mon) ||
(time_str.tm_year != pTmStruct->tm_year) ||
(time_str.tm_mday != pTmStruct->tm_mday))
{
time_str.tm_mday++;
timestamp = mktime(&time_str);
}
sts = EssLROPurgeObjects(hCtx, userName, timestamp, &ulLroCount, &plroDescList);
if(sts)
{
printf("Could not purge linked objects. \n");
}
if (plroDescList)
return sts;
}
See Also
l EssLROGetCatalog
l EssLRODeleteCellObjects
EssLROUpdateObject
Stores an updated version of an LRO on the server.
Syntax
ESS_FUNC_M EssLROUpdateObject (hCtx, plinkId, usOption, pLRODesc);
plinkId “ESS_LROHANDLE_API_T” on Pointer to object identification structure.

page 103
usOption ESS_USHORT_T Option specifying whether to store the object, its catalog entry, or
both. Use one of the following:
l ESS_LRO_OBJ_API stores only the object.
l ESS_LRO_CATALOG_API stores only the catalog entry.
l ESS_LRO_BOTH_API stores the object and the catalog entry.
pLRODesc “ESS_LRODESC_API_T” on page Pointer to object's description structure.

102
Notes
l The linked object can be any of the following types:
538
m A flat file, such as a Word document, Excel spreadsheet, or bitmap image.
m A cell note containing up to 599 characters of text.
m A link to another Essbase database (Linked Partitions feature).
l Cell notes are part of the catalog entry for an object. To store a cell note, use
ESS_LRO_CATALOG_API for the usOption parameter. The linked note is contained in
structure “ESS_LRODESC_API_T” on page 102.
l The name of the last user to modify the object and the modification date are also updated.
Return Value
Access
Example
ESS_STS_T ESS_LRO UpdateObject (ESS_HCTX_T hCtx)
{
ESS_USHORT_T usOption = 2; /* Default is catalog */
memset (&linkId, 0, sizeof(ESS_LROHANDLE_API_T));

memset (&lroDesc, 0, sizeof(ESS_LRODESC_API_T));
linkId.hObject = 25;
linkId.cellKey.blkOffset = 113.0;
linkId.cellKey.segment = 0.0;
/* Linked object is a LRO. (Windows Application) */

lroDesc.usObjType = 1;
/* Update both object and catalog */

usOption = ESS_LRO_BOTH_API;
strcpy (lroDesc.lro.lroInfo.objName, "e:\\lro\\lroex.c");
strcpy (lroDesc.lro.lroInfo.objDesc, "My C file");
strcpy (lroDesc.userName, "user1");

lroDesc.linkId.hObject = linkId.hObject;
sts = EssLROUpdateObject(hCtx, &linkId, usOption, &lroDesc);

if (sts)
{
printf("Could not update linked object.\n");
}
return sts;
}
See Also
539
l EssLROGetObject
l EssLROAddObject
EssMdxTrig
Manipulates triggers based on the operations specified in an MDX statement. The MDX can
create, replace, delete, enable, or disable a specific trigger.
Syntax
ESS_FUNC_M EssMdxTrig (hCtx, AppName, DbName, mdxStatement);
mdxStatement ESS_STR_T An MDX statement that specifies whether to create, replace, delete, enable, or disable
a specific trigger.
Access
See Also
l EssListSpoolFiles
l EssGetSpoolFile
l EssDeleteSplFile
EssMergeDatabaseData
Merges two or more data slices into a single data slice. Optionally, the primary database slice
can be excluded.
This function applies only to aggregate storage databases.
Syntax
ESS_FUNC_M EssMergeDatabaseData (hCtx, AppName, DbName, ulOptions);
AppName ESS_STR_T Use NULL. Function always applies to the currently selected database.
540
DbName ESS_STR_T Use NULL. Function always applies to the currently selected database.
ulOptions ESS_ULONG_T One of the following constants:

l #define ESS_MERGE_DATABASE_DATA_ALL 1: Merges all data slices into
one.
l #define ESS_MERGE_DATABASE_DATA_INCREMENTAL 2: Merges all
incremental slices into one slice, but does not merge this slice with the primary slice.
Afterwards, there will be two slices.
Return Value
Example
void TestMergeDatabaseData(ESS_HCTX_T hCtx, ESS_STR_T AppName, ESS_STR_T DbName)
{
ESS_OBJDEF_T Rules;
ESS_OBJDEF_T Data;
ESS_ULONG_T ulSize;
ESS_ULONG_T options;
printf("\nCreate the buffer:\n");

ulSize = 100;
ulBufferId = 1;
/* Server object */
Rules.hCtx = hCtx;
Rules.AppName = AppName;
Rules.DbName = DbName;
Rules.FileName = "ddldinaq";
Data.hCtx = hCtx;
Data.FileName = "ddldinaq_slice1a";
541
printf("\nLoad into buffer:\n");

sts = EssImportASO (hCtx, &Rules, &Data, &pMbrErr, pMbrUser, isAbortOnError,
ulBufferId);
printf("EssImportASO sts: %ld\n",sts);
if(pMbrErr)
ulBufferCnt = 1;
printf("\Create a new slice:\n");
ulOptions = ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE;
ulCommitType,
options = ESS_MERGE_DATABASE_DATA_ALL;
printf("\nMerge all data into one slice:\n");
sts = EssMergeDatabaseData(hCtx, AppName, DbName, options);
printf("EssMergeDatabaseData sts: %ld\n",sts);
}
See Also
l EssLoadBufferInit
l EssSendString
l EssEndDataload
l EssLoadBufferTerm
l EssImportASO
l EssUpdateFileASO
EssPartialDataClear
Clears the data specified in a well-defined, symmetrical region in the active aggregate storage
database. There are two methods for selectively clearing data from a region:
l Physical, in which the input cells in the specified region are physically removed from the
aggregate storage database. The process for physically clearing data completes in a length of
time that is proportional to the size of the input data, not the size of the data being cleared.
l Logical, in which the input cells in the specified region are written to a new data slice with
negative, compensating values that result in a value of zero for the cells you want to clear.
The process for logically clearing data completes in a length of time that is proportional to
the size of the data being cleared.
542
Syntax
ESS_FUNC_M EssPartialDataClear (hCtx, RegionSpec, bPhysical);
hCtx ESS_HCTX_T API context handle (logged in)
RegionSpec ESS_STR_T Region specification (a valid MDX set expression)

The region must be symmetrical. Members in any dimension in the region must be stored
members. When physically clearing data, members in the region can be upper-level
members from primary and alternate hierarchies. (If the region contains upper-level
members from alternate hierarchies, you may experience a decrease in performance.)
When logically clearing data, members in the region can be upper level members from the
primary hierarchy only. Members cannot be dynamic members (members with implicit
or explicit MDX formulas), nor can they be from an attribute dimension.
bPhysical ESS_BOOL_T If TRUE, specifies clearing the data in the region using the physical clear region operation.
If FALSE or not specified, data is cleared using the logical clear region operation.
Notes
The caller must have Database Manager or Administrator permission to clear data.
Return Value
Return value for this function is zero upon successful completion; otherwise, an error code is
returned.
Access
This function applies to aggregate storage databases only.
Example
ESS_FUNC_M
TestPartialDataClear(ESS_HCTX_T hCtx)
{
ESS_STS_T sts;
ESS_STR_T regionSpec="{Feb}";
/* Perform a logical clear of February data */

sts = EssPartialDataClear(hCtx, regionSpec, ESS_FALSE);
return(sts);
}
EssPartitionApplyOtlChangeFile
Replaced by EssPartitionApplyOtlChangeFileEx, but this format is maintained for backward
compatability. For complete information, see EssPartitionApplyOtlChangeFileEx.
Syntax
ESS_FUNC_M EssPartitionApplyOtlChangeFile (hCtx, usFileName, ppszFileName);
543
usFileName ESS_USHORT_T Number of outline change files.
ppszFileName ESS_PSTR_T Array of file names; array size is defined by usFileName.
EssPartitionApplyOtlChangeFileEx
Applies outline change files (*.CHG) on the source to a target outline. This function is designed
to be used in batch with EssPartitionGetOtlChanges and can specify a list of change files.
This function can be used with filters.
Use this function instead of EssPartitionApplyOtlChangeFile whenever there exists more
then one partition of the same type and the same metadata direction between the application/
database pair.
Syntax
ESS_FUNC_M EssPartitionApplyOtlChangeFileEx (hCtx, usFileName, ppszFileName,
usDataDirectionType);
usFileName ESS_USHORT_T Number of outline change files.
ppszFileName ESS_PSTR_T Array of file names; array size is defined by usFileName
usDataDirectionType ESS_USHORT_T One of the following Direction Type constants:

Notes
EssPartitionGetOtlChanges returns the name of the change file.
Return Value
Access
A call to this function requires database designer permission.
Example
ESS_FUNC_M ESS_PartitionApplyOtlChangeFileEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_FUNC_M sts;
ESS_STR_T hostname, appname, dbname;
ESS_USHORT_T usType, uscnt, dataFlowDir, *dataFlowDirs = ESS_NULL;
ESS_ULONG_T uldimfilter=0,ulmbrfilter=0,ulmbrattrfilter=0;
ESS_PARTOTL_QUERY_T MetaQuery;
544
ESS_PARTOTL_CHG_FILE_T MetaChangeFile;
ESS_PPART_INFO_T partitionp = NULL;
memset(&MetaQuery, 0, sizeof(ESS_PARTOTL_QUERY_T));
hostname = "local";
appname = "app1";
dbname = "src1";
usType = ESS_PARTITION_OP_LINKED;
dataFlowDir = ESS_PARTITION_DATA_SOURCE;
uldimfilter = ESS_DIMCHG_ALL;
ulmbrfilter = ESS_PARTITION_OTLMBR_ALL;
ulmbrattrfilter = ESS_PARTITION_OTLPARTITION_OTLMBRATTR_ALL;
MetaQuery.HostDatabase.pszHostName = hostname;
MetaQuery.HostDatabase.pszAppName = appname;
MetaQuery.HostDatabase.pszDbName = dbname;
MetaQuery.usOperationType = usType;
MetaQuery. usDataDirectionType = dataFlowDir;
MetaQuery.MetaFilter.TimeStamp = 0;
MetaQuery.MetaFilter.ulDimFilter = uldimfilter;
MetaQuery.MetaFilter.ulMbrFilter = ulmbrfilter;
MetaQuery.MetaFilter.ulMbrAttrFilter = ulmbrattrfilter;
sts = EssPartitionGetOtlChanges(hCtx, &MetaQuery, &MetaChangeFile);
if (!sts)
sts = EssAlloc(hInst, MetaChangeFile.usFileNum *sizeof(ESS_USHORT_T),
&dataFlowDirs);
if (!sts)
for (uscnt=0;uscnt< MetaChangeFile.usFileNum;uscnt++)
dataFlowDirs[uscnt] = dataFlowDir;
if (!sts)
{
sts = EssPartitionApplyOtlChangeFile
(hCtx, MetaChangeFile.usFileNum, MetaChangeFile.ppszFileName);
printf("EssPartitionApplyOtlChangeFile sts: %ld\n",sts);
}
if(&MetaChangeFile) EssFree(hInst,&MetaChangeFile);
if(&dataFlowDirs) EssFree(hInst, &dataFlowDirs);
return(sts);
See Also
l “Constant and Structure Definitions for Partitions (C)” on page 103
l EssPartitionApplyOtlChangeRecs
l EssPartitionCloseDefFile
l EssPartitionFreeDefCtx
545
l EssPartitionFreeOtlChanges
l EssPartitionGetAreaCellCount
l EssPartitionGetList
l EssPartitionGetOtlChanges
l EssPartitionGetReplCells
l EssPartitionNewDefFile
l EssPartitionOpenDefFile
l EssPartitionPurgeOtlChangeFile
l EssPartitionPutReplCells
l EssPartitionReadDefFile
l EssPartitionReadOtlChangeFile
l EssPartitionReplaceDefFile
l EssPartitionResetOtlChangeTime
l EssPartitionValidateDefinition
l EssPartitionWriteDefFile
EssPartitionApplyOtlChangeRecs
Applies outline changes to a target outline. This function is designed to be used interactively
with EssPartitionReadOtlChangeFile after a call to EssPartitionGetOtlChanges. The
change file returned by EssPartitionReadOtlChangeFile can be edited to set the reject flags. The
reject flags are set in “ESS_PARTOTL_MBR_RSRVD_API_T” on page 157, which is referenced
from ESS_PARTOTL_SELECT_APPLY_T.
Syntax
ESS_FUNC_M EssPartitionApplyOtlChangeRecs (hCtx, pApplyRecords);
pApplyRecords “ESS_PARTOTL_SELECT_APPLY_T” on page 165 Records to apply.
Notes
l There may be dependencies among change records.
l Rejecting a record may cause a failure when applying another record. For example, you have
two records "add A" and "add AA as a child of A". Rejecting the first record and accepting
the second causes an apply failure.
Return Value
Access
A call to this function requires database designer access privileges.
546
Example
ESS_FUNC_M Ess_PartitionApplyOtlChangeRecs (ESS_HCTX_T hCtx)
{
ESS_PARTOTL_SELECT_APPLY_T ApplyRecords;
ESS_STR_T chgfilename;
ESS_TIME_T time = 0;
ESS_PARTOTL_CHANGE_API_T OtlChg;
ESS_PARTOTL_SELECT_CHG_T SelectMetaRecords;
ESS_PARTOTL_READ_T MetaChangeRead;
memset(&ApplyRecords, 0, sizeof(ESS_PARTOTL_SELECT_APPLY_T));
memset(&SelectMetaRecords, 0, sizeof(ESS_PARTOTL_SELECT_CHG_T));
memset(&MetaChangeRead, 0, sizeof(ESS_PARTOTL_READ_T));
chgfilename = "C:\\Hyperion\\products\\Essbase\\EssbaseServer\\app\\app1\\trg1\
\ess00001.chg";
ulmbrattrfilter = ESS_PARTITION_OTLPARTITION_OTLMBRATTR_ALL;
SelectMetaRecords.pszFileName = chgfilename;
SelectMetaRecords.QueryFilter.TimeStamp = time;
SelectMetaRecords.QueryFilter.ulDimFilter = uldimfilter;
SelectMetaRecords.QueryFilter.ulMbrFilter = ulmbrfilter;
SelectMetaRecords.QueryFilter.ulMbrAttrFilter = ulmbrattrfilter;
MetaChangeRead.pOtlChg = &OtlChg;
sts = EssPartitionReadOtlChangeFile (hCtx, &SelectMetaRecords, &MetaChangeRead);
printf("\tEssPartitionReadOtlChangeFile sts: %ld\n",sts);
if (!sts)
{
ApplyRecords.pszFileName = chgfilename;
ApplyRecords.pOtlChg = MetaChangeRead.pOtlChg;
ApplyRecords.SourceTime = MetaChangeRead.SourceTime;
sts = EssPartitionApplyOtlChangeRecs(hCtx, &ApplyRecords);
printf("EssPartitionApplyOtlChangeRecs sts: %ld\n",sts);
}
sts = EssPartitionFreeOtlChanges(hCtx);
return(sts);
See Also
l EssPartitionApplyOtlChangeFile
547
EssPartitionCloseDefFile
Closes the shared partition definition file.
Syntax
ESS_FUNC_M EssPartitionCloseDefFile (hCtx, iFileHandle);
hCtx ESS_HCTX_T Net context.
iFileHandle ESS_INT_T File handle to close.
Notes
Use this function as part of a sequence of definition operations.
1. Use EssPartitionOpenDefFile to open existing definition files.
2. Use EssPartitionNewDefFile to create and open a new definition file.
3. Use EssPartitionReadDefFile or EssPartitionWriteDefFile to read or write a
definition file.
4. Close with EssPartitionCloseDefFile.
5. Free the memory with EssPartitionFreeDefCtx.
Return Value
Example
For an example, see EssPartitionNewDefFile
See Also
548
l EssPartitionValidateLocal
EssPartitionFreeDefCtx
Frees memory dynamically allocated under shared-partition context structures.
Syntax
ESS_FUNC_M EssPartitionFreeDefCtx (hCtx, pDdbCtx);
pDdbCtx “ESS_PART_T” on page 146 Pointer to shared-partition context.
Return Value
Returns zero if successful, error code if unsuccessful.
Example
For an example, see EssPartitionNewDefFile.
See Also
549
EssPartitionFreeOtlChanges
Frees memory allocated by the EssPartitionReadOtlChangeFile routine. Call this routine
after processing outline change records.
Syntax
ESS_FUNC_M EssPartitionFreeOtlChanges (hCtx);
Return Value
Example
For an example, see EssPartitionReadOtlChangeFile.
See Also
550
EssPartitionGetAreaCellCount
Returns the number of cells in the specified slice string.
Syntax
ESS_FUNC_M EssPartitionGetAreaCellCount (hCtx, pszSlice, pdCount);
pszSlice ESS_STR_T Input slice definition to be checked.
pdCount ESS_PDOUBLE_T Returns number of cells here.
Return Value
Example
ESS_FUNC_M ESS_PartitionGetAreaCellCount(ESS_HCTX_T hCtx)
{
ESS_DOUBLE_T pdCount;
ESS_STR_T pszSlice;
pszSlice = "@IDESC(East)";
sts = EssPartitionGetAreaCellCount(hCtx, pszSlice, &pdCount);

if (!sts)
{ printf("EssPartitionGetAreaCellCount sts: %ld\n",sts);
printf("\tArea cell count = %g \n",pdCount); }
return(sts);
}
See Also
551
EssPartitionGetAreaLev0CellCount
Returns the number of cells which are level 0 combinations of dimensions in a specified slice
string. This is useful if the target of replicated partition is an aggregate storage cube.
Syntax
ESS_FUNC_M EssPartitionGetAreaLev0CellCount (hCtx, pszSlice, pdCount);
pszSlice ESS_STR_T Input slice definition to be checked.
pdCount ESS_PDOUBLE_T Returns number of cells here.
Return Value
Example
ESS_FUNC_M ESS_PartitionGetAreaLev0CellCount(ESS_HCTX_T hCtx)
{
ESS_DOUBLE_T pdCount;
ESS_STR_T pszSlice;
pszSlice = "@IDESC(East)";
sts = EssPartitionGetAreaLev0CellCount(hCtx, pszSlice, &pdCount);

if (!sts)
{ printf("EssPartitionGetAreaLev0CellCount sts: %ld\n",sts);
printf("\tArea cell count = %g \n",pdCount); }
return(sts);
}
See Also
552
EssPartitionGetList
Returns a list of the partition definitions in which the currently selected database participates.
Syntax
ESS_FUNC_M EssPartitionGetList (hCtx, pSelectPartition, pusCount, ppPartition);
pSelectPartition “ESS_PARTSLCT_T” on page 165 Criteria to select partitions.
pusCount ESS_PUSHORT_T Count of partitions returned.
ppPartition “ESS_PART_INFO_T” on page 148 Pointer to allocated array of partition information structures.
Return Value
Example
ESS_FUNC_M ESS_PartitionGetList(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_USHORT_T op_types = 0;
ESS_USHORT_T dir_types = 0;
ESS_USHORT_T meta_dir_types = 0;
ESS_PARTSLCT_T SelectPartition;
memset(&Selectpartition, 0, sizeof(ESS_PARTSLCT_T));
op_types = ESS_PARTITION_OP_REPLICATED |
ESS_PARTITION_OP_TRANSPARENT;
553
dir_types = ESS_PARTITION_DATA_SOURCE | ESS_PARTITION_DATA_TARGET;
meta_dir_types = ESS_PARTITION_OTL_SOURCE | ESS_PARTITION_OTL_TARGET;
SelectPartition.usOperationTypes = op_types;
SelectPartition.usDirectionTypes = dir_types;
SelectPartition.usMetaDirectionTypes = meta_dir_types;
sts = EssPartitionGetList(hCtx, &SelectPartition, &count, &Partitionp);

printf("EssPartitionGetList sts: %ld\n",sts);
if (!sts)
{
printf("\n# Partitions matching input criteria: %d\n\n", (int)count);

{
ESS_PART_INFO_T *info = &partitionp[i];
printf("%2d: %s %s %s: Host=%s App=%s Db=%s\n", i+1,

info->OperationType==ESS_PARTITION_OP_REPLICATED ? "Replication" :
info->OperationType==ESS_PARTITION_OP_LINKED ? "Link" :
info->OperationType==ESS_PARTITION_OP_TRANSPARENT ? "Transparent" :
"Unknown",
info->DataDirection==ESS_PARTITION_DATA_SOURCE ? "Source" :
info->DataDirection==ESS_PARTITION_DATA_TARGET ? "Target" :"Unknown",
info->MetaDirection==ESS_PARTITION_OTL_SOURCE ? "(Outline Change Source)":
info->MetaDirection==ESS_PARTITION_OTL_TARGET ? "(Outline Change
Target)" :"(Unknown Outline Change Type)",
info->SvrName, info->AppName, info->DbName);
printf(" Outline last changed: %s\n",
info->LastMetaUpdateTime==0 ? "Never\n"
: ctime(&info->LastMetaUpdateTime));
if (info->OperationType==ESS_PARTITION_OP_REPLICATED &&
info->DataDirection==ESS_PARTITION_DATA_TARGET)
{
printf(" Last replicated: %s %s\n",
info->LastRefreshTime==0 ? "Never\n"
: ctime(&info->LastRefreshTime),
info->PartitionUpdatable ? "Locally updatable" :
"Not locally updatable");
}
else if (info->OperationType==ESS_PARTITION_OP_REPLICATED &&
info->DataDirection==ESS_PARTITION_DATA_SOURCE)
{
printf(" Last updated: %s %s\n\n",
info->LastUpdateTime==0 ? "Never\n"
: ctime(&info->LastUpdateTime),
info->IncrRefreshAllowed ? "Incrementally replicatable" :
"Not incrementally replicatable");
}
}#/* end for */
}#/* end if */
if (partitionp) EssFree(hInst, partitionp);
return(sts);
}
554
See Also
EssPartitionGetOtlChanges
Reads outline changes from a .CHG file on a source server and writes them to a .CHG file on the
target server. This function is designed to be used in a batch with
EssPartitionApplyOtlChangeFile, or interactively with a combination of
EssPartitionReadOtlChangeFile and EssPartitionApplyOtlChangeRecs.
Syntax
ESS_FUNC_M EssPartitionGetOtlChanges (hCtx, pQuery, pChangeFile);
pQuery “ESS_PARTOTL_QUERY_T” on page 163 Change query criteria.
pChangeFile “ESS_PARTOTL_CHG_FILE_T” on page 154 Caller allocated change files information structure.
Notes
Call EssPartitionFreeOtlChanges to free change file name strings in pChangeFile.
Return Value
Access
555
Example
ESS_FUNC_M Ess_PartitionGetOtlChanges(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_FUNC_M sts;
ESS_USHORT_T usType, dataFlowDir;
ESS_PARTOTL_QUERY_T MetaQuery;
ESS_PARTOTL_CHG_FILE_T MetaChangeFile;
memset(&MetaQuery, 0, sizeof(ESS_PARTOTL_QUERY_T));
hostname = "local";
appname = "app1";
dbname = "src1";
dataFlowDir = ESS_PARTITION_DATA_SOURCE;
uldimfilter = ESS_PARTITION_OTLDIM_ALL;
ulmbrattrfilter = ESS_PARTITION_OTLMBRATTR_ALL;
MetaQuery.HostDatabase.pszHostName = hostname;
MetaQuery.HostDatabase.pszAppName = appname;
MetaQuery.HostDatabase.pszDbName = dbname;
MetaQuery.usOperationType = usType;
MetaQuery. usDataDirectionType = dataFlowDir;
MetaQuery.MetaFilter.TimeStamp = 0;
MetaQuery.MetaFilter.ulDimFilter = uldimfilter;
MetaQuery.MetaFilter.ulMbrFilter = ulmbrfilter;
MetaQuery.MetaFilter.ulMbrAttrFilter = ulmbrattrfilter;
sts = EssPartitionGetOtlChanges(hCtx, &MetaQuery, &MetaChangeFile);

printf("EssPartitionGetOtlChanges sts: %ld\n",sts);
if (!sts) {
printf("\tNumber of meta change file found: %d\n",MetaChangeFile.usFileNum);
printf("\tName of meta change file found: %s\n",MetaChangeFile.ppszFileName[0]);
}
if(&MetaChangeFile) EssFree(hInst,&MetaChangeFile);
return(sts);
}
See Also
556
EssPartitionGetReplCells
Replicates all data cells that are identified in the replication partition from the source database
to the selected target database.
Syntax
ESS_FUNC_M EssPartitionGetReplCells (hCtx, pReplicatePartition);
pReplicatePartition “ESS_PART_REPL_T” on page 149 Partition information.
Return Value
Access
Example
ESS_FUNC_M Ess_PartitionGetReplCells(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
ESS_PART_REPL_T ReplicatePartition;
memset(&ReplicatePartition, 0, sizeof(ESS_PART_REPL_T));
memset(&HostDatabase, 0, sizeof(ESS_PART_CONNECT_INFO_T));
ReplicatePartition.pHostDatabase = &HostDatabase;
ReplicatePartition.lPartitionCount = -1;
ReplicatePartition.bUpdatedOnly = ESS_FALSE;
sts = EssPartitionGetReplCells(hCtx, &ReplicatePartition);

printf("EssPartitionGetReplCells sts: %ld\n",sts);
return(sts);
}
557
See Also
EssPartitionNewDefFile
Creates and opens a new shared-partition definition file based upon input parameters supplied.
Syntax
ESS_FUNC_M EssPartitionNewDefFile (hCtx, pszFileName, pHostDatabase, piFileHandle,
ppDdbCtx);
hCtx ESS_HCTX_T API network context.
pszFileName ESS_STR_T Name of file to be created (full path).
pHostDatabase “ESS_PART_CONNECT_INFO_T” on page 147 Identifies the host database.
piFileHandle ESS_PINT_T Handle to created file.
ppDdbCtx “ESS_PART_T” on page 146 An initialized distributed context.
Return Value
Example
ESS_FUNC_M ESS_PartitionNewDefFile(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts = 0;
ESS_INT_T iFileHandle;
558
ESS_PART_T *pDdbCtx;
pszFileName = "C:\\Hyperion\\products\\Essbase\\EssbaseServer\\app\\app1\\trg1\
\trg1.ddb";
hostname = "local";
appname = "app1";
dbname = "dbname";
HostDatabase.pszHostName = hostname;
HostDatabase.pszAppName = appname;
HostDatabase.pszDbName = dbname;
sts = EssPartitionNewDefFile(hCtx,pszFileName,&HostDatabase,&iFileHandle,&pDdbCtx);
printf("EssPartitionNewDefFile sts: %ld\n",sts);
if (!sts)
{
/* ...
... process definition file information
...
*/
sts = EssPartitionWriteDefFile(hCtx,iFileHandle,pDdbCtx);
printf("\tEssPartitionWriteDefFile sts: %ld\n",sts);
sts = EssPartitionCloseDefFile(hCtx,iFileHandle);
printf("\tEssPartitionCloseDefFile sts: %ld\n",sts);
sts = EssPartitionFreeDefCtx(hCtx,pDdbCtx);
printf("\tEssPartitionFreeDefCtx sts: %ld\n",sts);
}
return (sts);
}
See Also
559
EssPartitionOpenDefFile
Opens an existing shared-partition definition file.
Syntax
ESS_FUNC_M EssPartitionOpenDefFile (hCtx, pszFileName, piFileHandle, ppDdbCtx);
pszFileName ESS_STR_T Name of file to be opened (complete path).
piFileHandle ESS_PINT_T Handle to created file.
ppDdbCtx “ESS_PART_T” on page 146 An initialized distributed context.
Notes
3. Use EssPartitionReadDefFile or EssPartitionWriteDefFile to read or write a
definition file.
Return Value
Example
ESS_FUNC_M ESS_PartitionOpenDefFile(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts = 0;
ESS_INT_T iFileHandle;
ESS_PART_T DdbCtx, *pDdbCtx;
pszFileName = "C:\\Hyperion\\products\\Essbase\\EssbaseServer\\app\\app1\\trg1\
\trg1.ddb";
sts = EssPartitionOpenDefFile(hCtx,pszFileName,&iFileHandle,&pDdbCtx);
printf("EssPartitionOpenDefFile sts: %ld\n",sts);
560
if (!sts)
{
sts = EssPartitionReadDefFile(hCtx,iFileHandle,&DdbCtx);
printf("\tEssPartitionReadDefFile sts: %ld\n",sts);
/* ...
... process definition file information
...
*/
sts = EssPartitionCloseDefFile(hCtx,iFileHandle);
printf("\tEssPartitionCloseDefFile sts: %ld\n",sts);
sts = EssPartitionFreeDefCtx(hCtx,pDdbCtx);
printf("\tEssPartitionFreeDefCtx sts: %ld\n",sts);
}
return (sts);
}
See Also
EssPartitionPurgeOtlChangeFile
Purges changes made previous to the time specified with the TimeStamp parameter.
Syntax
ESS_FUNC_M EssPartitionPurgeOtlChangeFile (hCtx, pPartition, TimeStamp);
561
pPartition “ESS_PART_DEFINED_T” on page 147 Partition specification.
TimeStamp ESS_TIME_T Purge all change records before this time.
Return Value
Example
ESS_FUNC_M ESS_PartitionPurgeOtlChangeFile(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
ESS_USHORT_T usType,usdir;
ESS_PART_DEFINED_T Partition;
memset(&Partition, 0, sizeof(ESS_PART_DEFINED_T));
hostname = "local";
appname = "App1";
dbname = "Src1";
usdir = ESS_PARTITION_DATA_TARGET;
Partition.usType = usType;
Partition.usDirection = usdir;
Partition.HostDatabase.pszHostName = hostname;
Partition.HostDatabase.pszAppName = appname;
Partition.HostDatabase.pszDbName = dbname;
sts = EssPartitionPurgeOtlChangeFile (hCtx, &Partition, 0);
printf("EssPartitionPurgeOtlChangeFile sts: %ld\n",sts);
return(sts);
}
See Also
562
EssPartitionPutReplCells
Replicates all data cells that are identified in the replication partition from the selected source
database to the target database.
Syntax
ESS_FUNC_M EssPartitionPutReplCells (hCtx, pReplicatePartition);
pReplicatePartition ESS_PPART_REPL_T Partition information.
Notes
This routine removes the file if it is empty after purging.
Return Value
Access
Example
ESS_FUNC_M Ess_PartitionPutReplCells(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
ESS_PART_REPL_T ReplicatePartition;
memset(&ReplicatePartition, 0, sizeof(ESS_PART_REPL_T));
memset(&HostDatabase, 0, sizeof(ESS_PART_CONNECT_INFO_T));
ReplicatePartition.pHostDatabase = &HostDatabase;
ReplicatePartition.lPartitionCount = -1;
ReplicatePartition.bUpdatedOnly = ESS_FALSE;
sts = EssPartitionPutReplCells(hCtx, &ReplicatePartition);

printf("EssPartitionPutReplCells sts: %ld\n",sts);
return(sts);
}
See Also
563
EssPartitionReadDefFile
Reads a partition definition file into memory.
Syntax
ESS_FUNC_M EssPartitionReadDefFile (hCtx, iFileHandle, pDdbCtx);
iFileHandle ESS_INT_T Handle to partition definitions file.
pDdbCtx “ESS_PART_T” on page 146 Distributed database context to be filled.
Notes
3. Use this function to read, or EssPartitionWriteDefFile to write, a definition file.
Return Value
564
Example
For an example, see EssPartitionOpenDefFile.
See Also
EssPartitionReadOtlChangeFile
Reads changes from a change file (*.CHG) on the target database into memory. This function is
designed to be used interactively with EssPartitionApplyOtlChangeRecs after a call to
EssPartitionGetOtlChanges. This function can be used with filters.
Syntax
ESS_FUNC_M EssPartitionReadOtlChangeFile (hCtx, pSelectMetaRecords, pMetaChangeRead);
pSelectMetaRecords “ESS_PARTOTL_SELECT_CHG_T” on page Criteria to select records to read.

165
pMetaChangeRead ESS_PREAD_T Pointer to meta change records read from the

file.
Notes
This routine returns a time in pMetaChangeRead. It's the same time stamp you should pass to
EssPartitionApplyOtlChangeRecs to update the timestamp at the target database. It's also
565
the same time stamp you should use for EssPartitionPurgeOtlChangeFile to purge applied
records.
Return Value
Access
Example
ESS_FUNC_M ESS_PartitionReadOtlChangeFile(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_FUNC_M sts;
ESS_STR_T chgfilename;
ESS_TIME_T time;
ESS_PARTOTL_CHANGE_API_T OtlChg;
ESS_PARTOTL_SELECT_CHG_T SelectMetaRecords;
ESS_PARTOTL_READ_T MetaChangeRead;
memset(&OtlChg, 0, sizeof(ESS_PARTOTL_CHANGE_API_T));
memset(&SelectMetaRecords, 0, sizeof(ESS_PARTOTL_SELECT_CHG_T));
memset(&MetaChangeRead, 0, sizeof(ESS_PARTOTL_READ_T));
chgfilename = "d:\\essbase5\\app\\app1\\trg1\\ess00001.chg";
time = 0;
ulmbrattrfilter = ESS_PARTITION_OTLMBRATTR_ALL;
SelectMetaRecords.pszFileName = chgfilename;
SelectMetaRecords.QueryFilter.TimeStamp = time;
SelectMetaRecords.QueryFilter.ulDimFilter = uldimfilter;
SelectMetaRecords.QueryFilter.ulMbrFilter = ulmbrfilter;
SelectMetaRecords.QueryFilter.ulMbrAttrFilter = ulmbrattrfilter;
MetaChangeRead.pOtlChg = &OtlChg;
sts = EssPartitionReadOtlChangeFile (hCtx, &SelectMetaRecords, &MetaChangeRead);
printf("EssPartitionReadOtlChangeFile sts: %ld\n",sts);
sts = EssPartitionFreeOtlChanges(hCtx);
printf("\tEssPartitionFreeOtlChanges sts: %ld\n",sts);
return(sts);
}
See Also
566
EssPartitionReplaceDefFile
Tells the server that a new shared-partition file has been sent, which replaces any existing file for
this database.
Syntax
ESS_FUNC_M EssPartitionReplaceDefFile (hCtx);
Return Value
Access
Example
ESS_FUNC_M Ess_PartitionReplaceDefFile(ESS_HCTX_T hCtx)
{
sts = EssPartitionReplaceDefFile(hCtx);
printf("EssPartitionReplaceDefFile sts: %ld\n",sts);
return(sts);
}
See Also
567
EssPartitionResetOtlChangeTime
Takes the “last change” time from the source partition and assigns it as a “last meta change”
time of a destination partition.
Syntax
ESS_FUNC_M EssPartitionResetOtlChangeTime
(hCtx, pSourcePartition, pDestinationPartition);
pSourcePartition “ESS_PART_DEFINED_T” on page 147 Partition for the new time.
pDestinationPartition “ESS_PART_DEFINED_T” on page 147 Partition where the time is reset.
Notes
l The source partition refers to a partition that provides a time stamps and target partition
refers to a partition which receives the time stamp.
l A source partition does not have to be either a data source partition or an outline source
partition.
Return Value
Access
A call to this function requires database manager permission.
Example
ESS_FUNC_M ESS_PartitionResetOtlChangeTime(ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
568
ESS_PART_DEFINED_T SourcePartition, TargetPartition;
memset(&SourcePartition, 0, sizeof(ESS_PART_DEFINED_T));
memset(&TargetPartition, 0, sizeof(ESS_PART_DEFINED_T));
SourcePartition.HostDatabase.pszHostName = "local";
SourcePartition.HostDatabase.pszAppName = "App1";
SourcePartition.HostDatabase.pszDbName = "Src1";
SourcePartition.usType = ESS_PARTITION_OP_LINKED;
SourcePartition.usDirection = ESS_PARTITION_DATA_SOURCE;
TargetPartition.HostDatabase.pszHostName = "local";
TargetPartition.HostDatabase.pszAppName = "App1";
TargetPartition.HostDatabase.pszDbName = "Trg1";
TargetPartition.usType = ESS_PARTITION_OP_LINKED;
TargetPartition.usDirection = ESS_PARTITION_DATA_TARGET;
sts = EssPartitionResetOtlChangeTime (hCtx, &SourcePartition, &TargetPartition);

printf("EssPartitionResetOtlChangeTime sts: %ld\n",sts);
return(sts);
See Also
EssPartitionValidateDefinition
Verifies the local partition definition (specified by ESS_PPARTSLCT_VALIDATE_T) against
the corresponding partition definition in pRemoteDDBFilename on the remote server.
569
Syntax
ESS_FUNC_M EssPartitionValidateDefinition (hCtx, pSelectVerify,
pulInvalidComponent, ppInvalidComponent, pRemoteDDBFileName);
pSelectVerify “ESS_PARTSLCT_VALIDATE_T” on page Description of the partition to verify.

166
pulInvalidComponent ESS_PULONG_T Number of errors and warnings resulting

from validation.
ppInvalidComponent “ESS_PARTDEF_INVALID_T” on page 149 List of errors and warnings resulting from
validation.
pRemoteDDBFileName ESS_STR_T Remote server partition definition file name.
Notes
l Call the function EssFree to free the invalid component when pulInvalidComponent is not
0.
l The remote partition definition file can reside locally or on the remote host. If the partition
definition file is local, pRemoteDDBFileName must specify the full path, including the file
name with extension. If the partition definition file is remote, pRemoteDDBFileName must
specify the file name without extension (the extension is assumed to be .DDB).
l The server uses the following rule to find the partition definition file on the system:
m If pSelectVerify->pszFileName = DbName, the server looks for DbName.DDN.
m If pSelectVerify->pszFileName != DbName, the server looks for pSelectVerify-
>pszFileName.DDB.
Return Value
Access
Example
ESS_STS_T ESS_PartitionValidateDefinition(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STS_T sts = 0;
ESS_PARTSLCT_VALIDATE_T SelectVerify;
ESS_PARTDEF_INVALID_T *pInvalidComponent;
ESS_ULONG_T ulInvalidComponentCount = 0;
ESS_STR_T pRemoteDDBFileName = "src";
/* assume, logged into target database */
memset(&SelectVerify, 0, sizeof(ESS_PARTSLCT_VALIDATE_T));
SelectVerify.usLoc = ESS_FILE_SERVER;
570
SelectVerify.pszFileName = "trg";
SelectVerify.Part.usType = ESS_PARTITION_OP_REPLICATED;
SelectVerify.Part.usDirection = ESS_PARTITION_DATA_TARGET;
SelectVerify.Part.HostDatabase.pszHostName = "Local"
SelectVerify.Part.HostDatabase.pszAppName = "PartSrc";
SelectVerify.Part.HostDatabase.pszDbName = "Src";
sts = EssPartitionValidateDefinition (hCtx, &SelectVerify,

&ulInvalidComponentCount, &pInvalidComponent, pRemoteDDBFileName);
if (ulInvalidComponentCount > 0)
printf("Validation resulted in warnings and errors.\n");
else
printf ("Partition is valid.\n");
if (pInvalidComponent)
EssFree(hInst, pInvalidComponent);
return(sts);
}
See Also
EssPartitionValidateLocal
Verifies all partition definitions associated with the database specified by ESS_HCTX_T.
Syntax
ESS_FUNC_M EssPartitionValidateLocal (hCtx, pusValidateResult);
571
pusValidateResult ESS_PUSHORT_T Result of partition validation.
Notes
pusValidateResult can be one of these values:
l ESS_DDB_VERIFY_ERROR (validation resulted in errors)
l ESS_DDB_VERIFY_FAIL (validation failed)
l ESS_DDB_VERIFY_NOERR (all partitions are valid)
l ESS_DDB_VERIFY_WARNING (validation resulted in warnings)
Return Value
Returns zero if the function completes successfully; error code if the function completes
unsuccessfully. Returns zero if the function operates on a database with no partition definition.
Access
Example
ESS_FUNC_M ESS_PartitionValidateLocal(ESS_HCTX_T hCtx)
{
ESS_USHORT_T usValidateRes = (ESS_USHORT_T)ESS_DDB_VERIFY_NOERR;
sts = EssPartitionValidateLocal(hCtx, &usValidateRes);
if (!sts)
{
switch (usValidateRes)
{
case ESS_DDB_VERIFY_WARNING:
printf("Validation resulted in warning(s) - see server log for details\n");
break;
case ESS_DDB_VERIFY_ERROR:
printf("Validation resulted in error(s) - see server log for details\n");
break;
default:
printf("\nPartition(s) validated\n");
break;
}
}
else
{
printf("Call to EssPartitionValidateLocal() failed.\n");
}
return (sts);
}
572
See Also
EssPartitionWriteDefFile
Writes the current memory version of the shared-partition definition file to disk.
Syntax
ESS_FUNC_M EssPartitionWriteDefFile (hCtx, iFileHandle, TpDdbCtx);
iFileHandle ESS_INT_T Handle to shared partition definition file.
pDdbCtx “ESS_PART_T” on page 146 Values to be written out.
Notes
3. Use this function to write, or EssPartitionReadDefFile to read, a definition file.
573
Return Value
Example
For an example, see EssPartitionNewDefFile.
See Also
EssPerformAllocationASO
Performs or verifies an allocation on an aggregate storage database.
Syntax
ESS_FUNC_M EssPerformAllocationASO (hCtx, verifyOnly, errorList, allocStruct);
verifyOnly ESS_BOOL_T Flag to indicate validation of allocation parameters without

performing allocation. If it is set to ESS_TRUE, the allocation
parameters are validated only. If it is ESS_FALSE, the allocation
is verified and executed.
errorList “ESS_PERF_ALLOC_ERROR_T” on A pointer to the linked list of error structures that will be allocated
page 167** and returned by the API function. This is so the client has more
information about warning and error messages. This argument
cannot be 0. The linked list must be freed by the client.
574
allocStruct “ESS_PERF_ALLOC_T” on page 167* Structure specifying the allocation parameters.
Return Value
Example
void HandleErrors(ESS_HINST_T hInst, ESS_PERF_ALLOC_ERROR_T **pErrorList)
{
if (pErrorList)
{
ESS_PERF_ALLOC_ERROR_T *errorList = *pErrorList;
ESS_PERF_ALLOC_ERROR_T *nextError;
while (errorList)
{
printf("Error number %ld occurred\n", errorList->messageNumber);
if (errorList->argument != ESS_PERF_ALLOC_ARG_NA)
printf(" in argument %d\n", errorList->argument);
if (errorList->lineNumber)
printf(" on line %ld\n", errorList->lineNumber);
if (errorList->token[0] != '\0')
printf(" on token %s\n", errorList->token);
nextError = errorList->nextError;
ESS_STS_T sts = EssFree (hInst, errorList);
printf("\nEssFree sts for errorList %ld\n",sts);
errorList = nextError;
}
*pErrorList = NULL;
}
}
void ESS_GLAllocation()
{
ESS_BOOL_T verifyOnly;
ESS_PERF_ALLOC_ERROR_T *errorList = ESS_NULL;
ESS_PERF_ALLOC_T *allocStruct;
sts = EssAlloc (hInst, sizeof(ESS_PERF_ALLOC_T), (ESS_PPVOID_T)&allocStruct);

printf("EssAlloc sts for allocStruct: %ld\n", sts);
verifyOnly = ESS_FALSE;
errorList = ESS_NULL;
allocStruct->pov = "[[Account]]@[1100]]].Children";
allocStruct->amount = "100";
allocStruct->amountContext = "";
allocStruct->amountTimeSpan = "";
allocStruct->target = "([Allocated], [041509GR PL2], [11], [[All Department Values]].
[000]]], [0000], [Base], [USD], [Total])";
allocStruct->targetTimeSpan = "{[Feb-08]}";
allocStruct->targetTimeSpanOption = ESS_ASO_ALLOCATION_TIMESPAN_DIVIDEAMT;
575
allocStruct->offset = "([Mar-08], [041509GR PL2], [11], [[All Department Values]].
[000]]], [0000], [Base], [USD], [Total], [291], [Allocated])";
allocStruct->debitMember = "[Beginning Balance Dr]";
allocStruct->creditMember = "[Beginning Balance Cr]";
allocStruct->range = "DESCENDANTS([Accessories], [Product].Levels(0))";
allocStruct->excludedRange = "";
allocStruct->basis = "([041509GR PL2], [11], [[All Department Values]].[000]]],
[0000], [Base], [USD], [Total], [Beginning Balance Cr], [4140], [Actual])";
allocStruct->basisTimeSpan = "{[Feb-08]}";
allocStruct->basisTimeSpanOption = ESS_ASO_ALLOCATION_TIMESPAN_COMBINEBASIS;
allocStruct->allocationMethod = ESS_ASO_ALLOCATION_METHOD_SHARE;
allocStruct->spreadSkipOption = 0;
allocStruct->zeroAmountOption = ESS_ASO_ALLOCATION_ZEROAMT_DEFAULT;
allocStruct->zeroBasisOption = ESS_ASO_ALLOCATION_ZEROBASIS_NEXTAMT;
allocStruct->negativeBasisOption = ESS_ASO_ALLOCATION_NEGBASIS_DEFAULT;
allocStruct->roundMethod = ESS_ASO_ALLOCATION_ROUND_NONE;
allocStruct->roundDigits = "";
allocStruct->roundToLocation = "";
allocStruct->groupID = 0;
allocStruct->ruleID = 0;
sts = EssPerformAllocationAso(hCtx, verifyOnly, &errorList, allocStruct);

printf("EssPerformAllocationAso sts: %ld\n",sts);
HandleErrors(hInst, &errorList);
if(allocStruct)
{
sts = EssFree (hInst, allocStruct);
printf("EssFree sts for allocStruct %ld\n",sts);
}
}
EssPerformCustomCalcASO
Performs or verifies a custom calculation on an aggregate storage database.
Syntax
ESS_FUNC_M EssPerformCustomCalcASO (hCtx, verifyOnly, errorList, calcStruct);
verifyOnly ESS_BOOL_T Flag to indicate whether the calculation will be validated without
executing it. If it is set to ESS_TRUE, the calculation is validated
only. If it is ESS_FALSE, the calculation is validated and executed.
errorList “ESS_PERF_ALLOC_ERROR_T” on A pointer to the linked list of error structures that will be
page 167** populated and returned by the API containing error information
about the custom calculation. This argument cannot be 0. The
linked list must be freed by the client.
calcStruct “ESS_PERF_CUSTCALC_T” on page Pointer to a client-allocated custom calculation structure and

171* parameters.
576
Return Value
Example
void HandleErrors(ESS_HINST_T hInst, ESS_PERF_ALLOC_ERROR_T **pErrorList)
{
if (pErrorList)
{
ESS_PERF_ALLOC_ERROR_T *errorList = *pErrorList;
ESS_PERF_ALLOC_ERROR_T *nextError;
while (errorList)
{
printf("Error number %ld occurred\n", errorList->messageNumber);
if (errorList->argument != ESS_PERF_ALLOC_ARG_NA)
printf(" in argument %d\n", errorList->argument);
if (errorList->lineNumber)
printf(" on line %ld\n", errorList->lineNumber);
if (errorList->token[0] != '\0')
printf(" on token %s\n", errorList->token);
nextError = errorList->nextError;
ESS_STS_T sts = EssFree (hInst, errorList);
printf("\nEssFree sts for errorList %ld\n",sts);
errorList = nextError;
}
*pErrorList = NULL;
}
}
void ESS_GLCustomCalc()
{
ESS_BOOL_T verifyOnly;
ESS_PERF_ALLOC_ERROR_T *errorList = ESS_NULL;
ESS_PERF_CUSTCALC_T *calcStruct;
sts = EssAlloc (hInst, sizeof(ESS_PERF_CUSTCALC_T), (ESS_PPVOID_T)&calcStruct);

printf("EssAlloc sts for calcStruct: %ld\n", sts);
sts = EssAlloc (hInst, sizeof(ESS_PERF_CUSTCALC_T), (ESS_PPVOID_T)&calcStruct);

printf("EssAlloc sts: %ld\n", sts);
verifyOnly = ESS_FALSE;
errorList = ESS_NULL;
calcStruct->pov = "{[1120], [1130]}";
calcStruct->script = "[Jan-96] := ([Feb-08], [041509GR PL2], [00], [[All Department
Values]].[000]]], [0000], [[All Product Values]].[000]]], [Actual], [Beginning Balance
Dr], [BASE], [USD], [Total]);";
calcStruct->target = "([041509GR PL2], [00], [[All Department Values]].[000]]],
[0000], [[All Product Values]].[000]]], [Actual], [BASE], [USD], [Total])";
calcStruct->debitMember = "[Beginning Balance Dr]";
calcStruct->creditMember = "[Beginning Balance Cr]";
calcStruct->offset = "";
calcStruct->sourceRegion = "{([Feb-08], [041509GR PL2], [00], [[All Department
577
Values]].[000]]], [0000], [[All Product Values]].[000]]], [Actual], [Beginning Balance
Dr], [BASE], [USD], [Total])}";
calcStruct->groupID = 0;
calcStruct->ruleID = 0;
sts = EssPerformCustomCalcAso(hCtx, verifyOnly, &errorList, calcStruct);

printf("EssPerformCustomCalcAso sts: %ld\n",sts);
HandleErrors(hInst, &errorList);
if(calcStruct)
{
sts = EssFree (hInst, calcStruct);
printf("EssFree sts for allocStruct %ld\n",sts);
}
}
EssPutObject
Copies an object from a local file to the server or client object system, and optionally unlocks it.
Syntax
ESS_FUNC_M EssPutObject (hCtx, ObjType, AppName, DbName, ObjName, LocalName, Unlock);
ObjName ESS_STR_T Name of object to put.
LocalName ESS_STR_T Full path name of local source file on client.
Unlock ESS_BOOL_T Flag to control object unlocking. If TRUE, the server object is unlocked to allow updates
by other users.
Notes
In order to put an object which already exists on the server, it must have previously been locked
by the caller. If the object does not already exist on the server, it will be created.
Return Value
If successful, the object is copied to the server from the local file specified by LocalName.
Access
and/or database to contain the object (depending on the object type). To unlock the object
578
(unlock flag is TRUE), the caller must have Application or Database Design privilege
Example
ESS_FUNC_M
ESS_PutObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T ObjName;
ESS_BOOL_T UnLock;
AppName = "Sample";
DbName = "Basic";
ObjName = "Basic1";
LocalName = "C:\\Hyperion\\products\\Essbase\\EssbaseClient\\Test.otl";
UnLock = ESS_TRUE;
sts = EssPutObject (hCtx, ObjType, AppName,

DbName, ObjName, LocalName, UnLock);
return (sts);
}
See Also
l EssGetObject
l EssLockObject
l EssUnlockObject
EssQueryDatabaseMembers
Performs a report-style query to list a selection of database member information.
Syntax
ESS_FUNC_M EssQueryDatabaseMembers (hCtx, mbrQuery);
mbrQuery ESS_STR_T Member query string. A query string is a command similar to a report specification. For
valid query strings see the Notes.
Notes
l The member information returned by this query must be read by calling EssGetString
until a NULL string is returned.
l This function supports an attribute member long name.
579
l See the Oracle Essbase Technical Reference for descriptions of report specifications.
l This function can return information on member stored as a relational partition if the
Boolean bSpanRelPart has been set by EssSetSpanRelationalPartition. This function
supports sorting of members based on member names, aliases (which are the same as
member names for relational members) and dimension/generation numbers. For other
options, the relational members are treated identically and displayed at the end of the list of
members.
Not all member selection strings are supported in the relational store. This function can
return relational information on the following member selection strings:
m ALLINSAMEDIM
m DIMTOP
m CHILDRENOF
m DESCENDANTSOF
m PARENTOF
m ANCESTORSOF
m ALLSIBILINGSOF
l The member query string consists of a selection string and an optional sorting command
followed by an optional output command. The form is:
mbrQuery ==: <selectionstring> [<sortcommand> [<outputcommand>] ]
l The valid values for member <selectionstring> are:
<CHILDRENOF -- returns ICHILDRENOF
<ALLINSAMEDIM
<DIMTOP
<OFSAMEGENERATION
<ONSAMELEVELAS
<ANCESTORSOF -- returns IANCESTORSOF
<PARENTOF
<DESCENDANTSOF -- returns IDESCENDANTSOF
<ALLSIBLINGSOF
<LSIBLINGOF
l Valid values for <sortcommand> are:
<SORTASCENDING
<SORTDESCENDING
<SORTNONE
<SORTMBRNAMES
<SORTALTNAMES
<SORTMBRNUMBERS
<SORTDIMNUMBERS
<SORTLEVELNUMBERS
<SORTGENERATION
l The form for <outputcommand> is:
<outputcommand> ==: Item [separator] | FORMAT {<item> <separator> }
m To obtain a one-item list of information on a member, use the following output

commands:
580
<outputcommand> ==: <MBRNAMES |
<ALTNAMES |
<MBRNUMBERS |
<DIMNUMBERS |
<LEVELNUMBERS |
<GENERATIONS |
<CALCSTRINGS |
<UCALCS |
<TABSEPARATED |
<SPACESEPARATED |
<COMMASEPARATED |
<NEWLINESEPARATED |
<ATTRIBUTES
m To obtain a list of two or more items of information on a member, use a format
specification clause. Specify the items you want listed, their order, and what character
to use to separate them. The syntax for a format specification clause is:
<FORMAT <item> [<separator>] {<item> [<separator>]}
The valid values for <item> are:

MBRNAMES
ALTNAMES
MBRNUMBERS
DIMNUMBERS
LEVELNUMBERS
GENERATIONS
CALCSTRINGS
UCALCS
ATTRIBUTES
ATTRIBUTES are listed as the number of attributes followed by a tab-separated list of

attribute names.
The valid values for <separator> are:
TABSEPARATED
SPACESEPARATED
COMMASEPARATED
NEWLINESEPARATED
If you do not specify a separator, the default is TABSEPARATED.

l Here is a sample script:
login "local" "user1" "password" "" ""
select "attr" "attr"
GetMembers "<NEWLINESEPARATED
<FORMAT {
MBRNAMES SPACESEPARATED ALTNAMES TABSEPARATED
MBRNUMBERS SPACESEPARATED DIMNUMBERS TABSEPARATED
LEVELNUMBERS SPACESEPARATED GENERATIONS TABSEPARATED
CALCSTRINGS SPACESEPARATED UCALCS TABSEPARATED
DIMTYPES SPACESEPARATED STATUSES TABSEPARATED
ATTRIBUTES
}
<DESCENDANTS Product "
581
Return Value
None.
Access
Example
ESS_STS_T
ESS_GetMembers (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STR_T mString = NULL;
sts = EssQueryDatabaseMembers (hCtx,

"<ALLINSAMEDIM Year");
if (!sts)
sts = EssGetString (hCtx, &mString);
while ((!sts) && (mString != NULL))

{
printf ("%s\r\n", mString);
EssFree (hInst, mString);
sts = EssGetString (hCtx, &mString);

}
return(sts);
}
See Also
l EssCheckMemberName
l EssGetMemberInfo
l EssSetActive
EssRealloc
Reallocates a previously-allocated block of memory to a different size, using the defined memory
allocation scheme.
Syntax
ESS_FUNC_M EssRealloc (hInstance, Size, ppBlock);
Size ESS_SIZE_T New size of memory block to reallocate.
582
ppBlock ESS_PPVOID_T Address of pointer to previously allocated memory block, to be updated to point to
reallocated memory block.
Notes
l This function reallocates previously-allocated memory using the user-supplied memory
management function passed to EssInit. If no such functions are supplied, the default
memory reallocation function (dependent on the platform) will be used.
l Only memory allocated with EssAlloc should be reallocated using this call. Also, memory
reallocated using this function should always be freed using EssFree.
l It is generally not advisable to reallocate a block of zero size, as the effects of such a
reallocation are platform- and compiler-dependent.
Return Value
If successful, returns a pointer to the reallocated memory block in ppBlock.
Access
Example
ESS_VOID_T
ESS_Realloc (ESS_HINST_T hInst)
{
ESS_SIZE_T Size;
ESS_PVOID_T pBlock = NULL;
/* Allocate memory */
Size = 10;
sts = EssAlloc(hInst, Size, &pBlock);
if(sts)
printf("Cannot allocate memory\r\n");
/* Reallocate memory */
Size = 20;
if(!sts)
{
sts = EssRealloc(hInst, Size, &pBlock);
if(sts)
printf("Cannot reallocate memory\r\n");
}
if(pBlock)
EssFree(hInst, pBlock);
}
See Also
l EssAlloc
l EssFree
l EssInit
583
EssRemoveAlias
Permanently removes an alias table from the active database.
Syntax
ESS_FUNC_M EssRemoveAlias (hCtx, AliasName);
AliasName ESS_STR_T Name of alias table to remove.
Notes
l This function cannot remove the active or default alias table.
l Make sure that no one is using the database from which you plan to remove an alias table,
by calling EssListConnections.
Return Value
None.
Access
and to have selected it as the active database using EssSetActive.
Example
ESS_FUNC_M
ESS_RemoveAlias (ESS_HCTX_T hCtx)
{
AliasName = "NewAlias";
sts = EssRemoveAlias(hCtx, AliasName);
if(!sts)
printf("The %s is removed.\r\n",AliasName);
return (sts);
}
See Also
l EssClearAliases
l EssListAliases
l EssSetActive
EssRemoveLocks
Removes all data block locks on a database which are currently held by a user.
584
Syntax
ESS_FUNC_M EssRemoveLocks (hCtx, AppName, DbName, LoginId);
LoginId ESS_LOGINID_T Id of user login whose locks are to be removed.
Notes
l The required LoginId can be obtained from the user lock info structure returned by the
EssListLocks function.
l This function terminates the connection of the user specified by LoginId if that user is
currently logged in.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_RemoveLocks (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_USHORT_T Count;
ESS_PLOCKINFO_T plockinfo = NULL;
ESS_PLOCKINFO_T plinfo;
ESS_USHORT_T ind;
ESS_SHORT_T Item;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
{
plinfo = plockinfo + ind;
printf ("%-2d %-15s %-12ld %-5d %ld\r\n",
ind, plinfo->UserName, plinfo->LoginId,
plinfo->nLocks, plinfo->Time);
}
printf ("\r\n");
/***********************************
* Chooser Lock List Item to Remove *
585
************************************/
Item = 1;
}
else
{
printf ("\r\nExclusive Lock List on %s:%s is empty\r\n\r\n",
AppName, DbName);
goto exit;
}
if (!sts)
{
if ((Item >= 0) && (Item < Count))
{
plinfo = plockinfo + Item;
sts = EssRemoveLocks (hCtx, AppName,
DbName, plinfo->LoginId);
}
}
exit:
if (plockinfo)
EssFree (hInst, plockinfo);
return (sts);
}
See Also
l EssListLocks
EssReplayTransactions
Executes (replays) the specified transactions.
l By default, this function replays everything since the last restored backup time or last
replayed request time—whichever is the latest.
l This function does not replay requests made after the restore, because the recommended
way to use restore command is to replay transactions and then open up for new transactions.
l You can use the pSeqIds option to force replays.
Syntax
ESS_FUNC_M EssReplayTransactions(hCtx, AppName,
DbName, ReplayDat, pSeqIds);
hCtx ESS_HCTX_T Login context.
ReplayDat ESS_TRANSACTION_REPLAY_INP_T Replay input parameters.
pSeqIds ESS_PSEQID_T Array of sequence ID ranges if input type is sequence ID
586
Return Value
l 0—If successful. pSeqIds contains a range of sequence IDs.
l Error number—If unsuccessful.
Access
The caller must have Administrator access to the database.
Example
void ListAndReplayTransactions()
{
ESS_USHORT_T TimeSrc;
ESS_TIME32_T timestamp = 0;
ESS_USHORT_T listOption;
ESS_STR_T FileName = ESS_NULL;
ESS_PTRANSACTION_ENTRY_T pResults;
ESS_CHAR_T listTime[ESS_TIMESIZE];
ESS_TRANSACTION_REPLAY_INP_T ReplayDat;
ESS_PSEQID_T pSeqIds = ESS_NULL;
ESS_OBJDEF_T Data;
ESS_STR_T Script;
/* Load data from server */

Data.hCtx = hCtx;
Data.FileName = "Calcdat";
sts = EssImport (hCtx, ESS_NULL, &Data,
&pMbrErr, NULL, isAbortOnError);
/* List and replay with a specified time */

TimeSrc = 1;
strcpy(listTime, "09/18/2007:00:00:00");
/* mm/dd/yyyy:hh:mm:ss */
timestamp = adtGenericGetTime(listTime);
listOption = ESS_LIST_TRANSACTIONS_TOCLIENT;
memset(&ReplayDat, 0, sizeof
ReplayDat.InpType = ESS_REPLAY_BASED_GIVENTIME;
587
ReplayDat.value.InpTime = timestamp;
sts = EssReplayTransactions (hCtx, AppName, DbName,
ReplayDat, pSeqIds);
printf("\n\n");
/* Run a calc*/
if (!sts)
{
while (!sts && (pState.State != ESS_STATE_DONE))
}
/* List and replay with last replay time */

TimeSrc = 2;
timestamp = 0;
memset(&ReplayDat, 0, sizeof
ReplayDat.InpType = ESS_REPLAY_BASED_LASTREPLAYTIME;
sts = EssReplayTransactions (hCtx, AppName,
DbName, ReplayDat, pSeqIds);
if(pSeqIds)
EssFree(hInst, pSeqIds);
if(pResults)
EssFree(hInst, pResults);
if(pMbrErr)
EssFree(hInst, pMbrErr);
}
Using SeqIds
When you replay using the sequence id array, specify a range of sequence ids.
l Enter the range count in num_seq_id_range.
l Follow num_seq_id_range with an array of ESS_SEQID_T, and the type data structure
and the number of elements in the array should be num_seq_id_range.
l The seq_id_upper_start and seq_id_upper_end fields are reserved, and should be
filled with zeros.
l The seq_id_start and seq_id_end fields should be filled in with start and end values of
the range.
588
l If you only have one sequence id, specify that id as the start and end value.
Example 1: To replay the ranges 1-5, 8-10 and 12-16 while skipping 6,7, and 11:
num_seq_id_range = 3
seqid_array[0].seq_id_start = 1
seqid_array[0].seq_id_end = 5
seqid_array[0].seq_id_start_upper = 0
seqid_array[0].seq_id_end_upper = 0
Example 2: To replay one range 3-7, num_seq_id_range = 1:

Example 3: To replay only transaction id 5:

num_seq_id_range = 1
See Also
l “ESS_SEQID_T” on page 180
l “ESS_DISKVOLUME_REPLACE_T” on page 131
l “ESS_TRANSACTION_ENTRY_T” on page 181
l “ESS_TRANSACTION_REPLAY_INP_T” on page 182
l “ESS_TRANSACTION_REQSPECIFIC_T” on page 182
l EssListTransactions
EssRenameApplication
Renames an existing application, either on the client or the server. If the application is running
on the server, it is first stopped.
Syntax
ESS_FUNC_M EssRenameApplication (hCtx, OldName, NewName);
OldName ESS_STR_T Name of existing application to rename.
589
NewName ESS_STR_T New name of application. See “Application Name Limits” on page 1255.
Notes
Renaming a client application renames the local application directory.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_RenameApp (ESS_HCTX_T hCtx)
{
ESS_STR_T OldName;
ESS_STR_T NewName;
OldName = "Sample";
NewName = "Sample2";
sts = EssRenameApplication(hCtx, OldName,
NewName);
return (sts);
}
See Also
l EssRenameDatabase
l EssRenameObject
EssRenameDatabase
Renames an existing database within an application, either on the client or the server. If the
database is running on the server, it is first stopped.
Syntax
ESS_FUNC_M EssRenameDatabase (hCtx, AppName, OldName, NewName);
OldName ESS_STR_T Name of existing database to rename.
590
NewName ESS_STR_T New name of database. See “Database Name Limits” on page 1256.
Notes
Renaming a client database renames the local database directory.
Return Value
None.
Access
For a server database, the caller must have Database Create/Delete/Edit privilege
Example
ESS_FUNC_M
ESS_RenameDatabase (ESS_HCTX_T hCtx)
{
ESS_FUNC_M sts;
ESS_STR_T AppName;
ESS_STR_T OldName;
ESS_STR_T NewName;
AppName = "Sample";
OldName = "Basic";
NewName = "Basic2";
sts = EssRenameDatabase(hCtx, AppName, OldName,

NewName);
return(sts);
}
See Also
l EssRenameApplication
l EssRenameObject
EssRenameFilter
Renames an existing filter.
Syntax
ESS_FUNC_M EssRenameFilter (hCtx, AppName, DbName, OldName, NewName);
591
OldName ESS_STR_T Old name of existing filter to be renamed.
NewName ESS_STR_T New name for the filter. See “Filter Name Limits” on page 1256.
Notes
The old filter name must already exist, and the destination filter name must not exist.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_RenameFilter (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T OldName;
ESS_STR_T NewName;
AppName = "Sample";
DbName = "Basic";
OldName = "Test";
NewName = "NewTest";
sts = EssRenameFilter(hCtx, AppName, DbName,

OldName, NewName);
return (sts);
}
See Also
l EssCopyFilter
l EssDeleteFilter
l EssListFilters
EssRenameGroup
Renames an existing group.
Syntax
ESS_FUNC_M EssRenameGroup (hCtx, OldName, NewName);
592
OldName ESS_STR_T Old name of existing group to rename.
NewName ESS_STR_T New name for the group. See “Group Name Limits” on page 1256.
Notes
The specified new group name must not already exist.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_RenameGroup (ESS_HCTX_T hCtx)
{
ESS_STR_T OldName;
ESS_STR_T NewName;
OldName = "PowerUsers";
NewName = "PowerGroup";
sts = EssRenameGroup (hCtx, OldName, NewName);

return (sts);
}
See Also
l EssCreateGroup
l EssDeleteGroup
l EssListGroups
EssRenameObject
Renames an existing object on the server or client object system.
Syntax
ESS_FUNC_M EssRenameObject (hCtx, ObjType, AppName, DbName,
OldName, NewName);
593
OldName ESS_STR_T Old name of object to rename.
NewName ESS_STR_T New name for the object. See “Object Name Limits” on page 1256.
Notes
l To rename an object, the object must not be locked, and the new object must not already
exist.
l Outline objects and LRO objects cannot be renamed.
l Use EssRenameDatabase to rename a database, including its associated outline.
l Objects cannot be renamed across different applications or databases. Use
EssCopyObject to copy an object to another application or database.
Return Value
None.
Access
Example
ESS_STS_T
ESS_RenameObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T OldName;
ESS_STR_T NewName;
AppName = "Sample";
DbName = "Basic";
OldName = "Test";
NewName = "NewTest";
sts = EssRenameObject(hCtx, ObjType, AppName,

DbName, OldName, NewName);
if(!sts)
printf("The Object is renamed.\r\n");
594
return (sts);
}
See Also
l EssCopyObject
l EssCreateObject
l EssDeleteObject
l EssListObjects
EssRenameUser
Renames an existing user.
Syntax
ESS_FUNC_M EssRenameUser (hCtx, OldName, NewName);
OldName ESS_STR_T Old name of existing user to rename.
NewName ESS_STR_T New name for the user. See “User Name Limits” on page 1256.
Notes
The specified new user name must not already exist.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_RenameUser (ESS_HCTX_T hCtx)
{
ESS_STR_T OldName;
ESS_STR_T NewName;
OldName = "Jim Smith";

NewName = "Tom Smith";
sts = EssRenameUser (hCtx, OldName, NewName);
return (sts);
}
595
See Also
l EssCreateUser
l EssDeleteUser
l EssListUsers
EssReport
Sends a report specification to the active database as a single string. This function is equivalent
to making a call to EssBeginReport, followed by calls to EssSendString and finally
EssEndReport. The report data can either be output, or the report specification can just be
verified and any errors returned. Also, the corresponding data blocks in the database can
optionally be locked by this call (lock for update).
Syntax
ESS_FUNC_M EssReport (hCtx, Output, Lock, RptSpec);
RptSpec ESS_STR_T The report specification, as a single string (must be less than 64 KB)..
Notes
l The report specification string must be less than 64 KB long.
l If this function causes data to be output (Output flag is TRUE), the returned data must be
read by calling EssGetString until a NULL is returned.
Return Value
None.
Access
members in the active database. Any members that the caller does not have access to will be
returned as missing.
596
Example
ESS_FUNC_M
ESS_ReportLine (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_STR_T rString;
sts = EssReport (hCtx, ESS_TRUE, ESS_FALSE,

"<Desc Year !");
/******************
* Get the report *
******************/
if (!sts)
{
}
printf ("\r\n");
return (sts);
}
See Also
l EssBeginReport
l EssEndReport
l EssGetString
l EssReportFile
l EssUpdate
EssReportFile
Sends a report specification to the active database from a file. The report data can either be
output, or the report specification can just be verified and any errors returned. Also, the
corresponding data blocks in the database can optionally be locked by this call (lock for update).
Syntax
ESS_FUNC_M EssReportFile (hDestCtx, hSrcCtx, AppName, DbName, FileName, Output, Lock);
hDestCtx ESS_HCTX_T API context handle of target database on the server.
hSrcCtx ESS_HCTX_T API context handle for report file location. The report file can reside on the client or on the
same server as the target database. If the report file is on the client (local), the local context
must be created with EssCreateLocalContext.
597
AppName ESS_STR_T Application name for report file location.
DbName ESS_STR_T Database name for report file location.
FileName ESS_STR_T Name of report specification file. It is not necessary to specify the file extension; the extension
is understood to be .rep.
Notes
l If this function causes data to be output (Output flag is TRUE), the returned data can be
read by calling EssGetString.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_ReportFile (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T rString;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
hSrcCtx = hCtx;
AppName = "Sample";
DbName = "Basic";
FileName = "Test";
sts = EssReportFile (hCtx, hSrcCtx, AppName,

DbName, FileName, ESS_TRUE, ESS_FALSE);
/* Get the report */
if (!sts)
598
{
sts = EssGetString (hCtx,&rString);
}
return(sts);
}
See Also
l EssBeginReport
l EssGetString
l EssReport
l EssUpdateFile
EssReRegisterApplication
Re-establishes one or all Essbase applications as Shared Services applications.
Syntax
ESS_FUNC_M EssReRegisterApplication (hCtx, AppName, AllApps);
AppName ESS_STR_T Name of application to reregister.
AllApps ESS_BOOL_T If ESS_TRUE, all applications are reregistered; otherwise, only the named application is
reregistered.
Return Value
Access
This function requires the caller to be an Administrator, Application Manager, or Database
Manager. For any applications for which the caller does not have sufficient permissions, the re-
registration will be skipped with a warning.
Example
ESS_FUNC_M ESS_SS_ReRegisterApplication(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_BOOL_T allApps;
ESS_STR_T appName = ESS_NULL;
sts = EssAlloc(hInst, sizeof(ESS_APPNAME_T), &appName);

if(sts)
return (sts);
memset(appName, 0, sizeof(ESS_APPNAME_T));
599
strcpy( appName, "Sample");
/* Do you want All applications re-registered?

* Enter ESS_TRUE for Yes
* ESS_FALSE for No
**/
allApps = ESS_FALSE; /* Re-registering only 1 application */
sts = EssReRegisterApplication(hCtx, appName, allApps);
if (sts)
printf("Failed to Re-register Application %s.\n", appName);
if (appName)
EssFree(hInst, appName);
return (sts);
}
EssResetDatabase
Clears all loaded data and resets the outline to be empty in the active database.
Syntax
ESS_FUNC_M EssResetDatabase (hCtx);
Notes
l Data deleted and outlines reset using this function cannot be restored. Use it with care!
l This function call is asynchronous. Call EssGetProcessState after making this call until
it returns a status indicating that the reset database operation is complete.
Return Value
None.
Access
This function requires that the caller have Write privilege (ESS_PRIV_WRITE) for the database,
and to select it as the active database using EssSetActive.
Example
ESS_FUNC_M
ESS_ResetDb (ESS_HCTX_T hCtx)
{
sts = EssResetDatabase(hCtx);
600
if (!sts)
{
while(!sts && (pState.State != ESS_STATE_DONE))
}
return (sts);
}
See Also
l EssResetPerfStats
l EssDumpPerfStats
EssResetPerfStats
Resets values in the performance statistics tables to zero.
Syntax
persistence; ESS_ULONG_T One of the following values indicating the persistence of the set of tables to be reset:
l 0: Reset short term tables only
l 1: Reset short and medium term tables
l 2: Reset short, medium and long term tables
l 3: Disable performance statistics gathering
l 4: Enable performance statistics gathering
scope; ESS_ULONG_T One of the following values indicating the scope of the set of tables to be reset:
l 1: Reset thread-based tables only
l 2: Reset database-based tables only
l 4: Reset server-based tables only
l 7: Reset all tables
Notes
l Enabling statistics gathering (persistence 4) or disabling statistics gathering (persistence 3)

does not reset any statistics.
l For more information on performance statistics tables, see the topic “Performance Statistics
in MaxL”, in the Oracle Essbase Technical Reference.
Return Value
If successful, returns 0.
601
Access
Example
/* This function resets all short term tables */
ESS_STS_T ESSResetPerfStats(ESS_HCTX_T *context)

{
ESS_ULONG_T persistence = 0;
ESS_ULONG_T scope = 7;
sts = EssResetPerfStats(context, persistence, scope);
return sts;
}
See Also
l EssDumpPerfStats
l EssGetStatBufSize
EssResetUser
Resets the user's security structure to its initial state.
Syntax
ESS_FUNC_M EssResetUser() (hCtx, UserName);
UserName; ESS_STR_T User name.
Notes
The following user security parameters are reset to their initial state:
l LockedOut
l PwdChgNow
l Failcount
l LastLogin
l LastPwdChg
l Expiration
Return Value
Returns zero (0) if successful.
602
Access
Example
ESS_FUNC_M
ESS_ResetUser (ESS_HCTX_T hCtx)
{
ESS_STR_T UserName = "William";
sts = EssResetUser (hCtx, UserName);

return (sts);
}
See Also
l EssInit
l EssLogin
l EssLogout
EssRestore
No longer in use.
This function is retained for compatibility with earlier releases of Essbase only. For current
Essbase archiving, see EssArchiveBegin and EssArchiveEnd. This function now returns the
error message ESS_STS_OBSOLETE.
See Also
EssArchiveBegin
EssArchiveEnd
EssArchive
EssSetActive
EssRestoreDatabase
Restores a database from a backup archive file that you specify.
Syntax
ESS_FUNC_M EssRestoreDatabase (hCtx, AppName, DbName, BackupFileName, bForceDiffName,
Count, ReplaceVol);
hCtx ESS_HCTX_T Login context.
603
Note: Works only at the database level. The AppName

parameter specifies an application in order to access
the database residing within.
BackupFileName ESS_STR_T Full path to the backup file from which to read archive data.
Specify the full path, for example:
c:\hyperion\Test.arc
bForceDiffName ESS_BOOL_T Use a different application and database names for the restore.
l ESS_TRUE—force a different application and/or
database name for the restore.
If you use ESS_TRUE and the application and database
name is same as the backup, the result is the same as
ESS_FALSE
l ESS_FALSE—use application and database names stored
in the backup file. Verifies that the names in backup file
are same the ones to which you are restoring to.
Count ESS_USHORT_T Optional.

Number of disk volume replacement structures that are being
restored.
ReplaceVol ESS_PDISKVOLUME_REPLACE_T Optional.

Disk volume replacement input structures.
Return Value
Returns:
l 0—If successful
Access
The caller must have Administrator access to the database.
Example
void RestoreDB()
{
ESS_STR_T AppName = "Backup";
ESS_STR_T BackupFileName =
"F:\\testArea\\ArchiveAndRestore\\TempBackup.arc";
ESS_STR_T optionsFileName = "";
ESS_BOOL_T bOverWrite;
ESS_BOOL_T bForceDiffName;
ESS_USHORT_T count;
604
ESS_PDISKVOLUME_REPLACE_T replaceVol;
printf("\nArchive DB:\n");
bOverWrite = ESS_TRUE;
sts = EssArchiveDatabase(hCtx, AppName, DbName,
BackupFileName, optionsFileName,
bOverWrite)
printf("EssArchiveDatabase sts: %ld\r\n",sts);

printf("\nCase with no volume replacement:\n");

count = 0;
replaceVol = ESS_NULL;
count, replaceVol);
printf("\nCase with a replacement volume (index and page files to a different

volume):\n");
count = 1;
if (count)
{
sts = EssAlloc(hInst, count * sizeof(ESS_DISKVOLUME_REPLACE_T),
(ESS_PPVOID_T)&replaceVol);
memset(replaceVol, 0, count * sizeof(ESS_DISKVOLUME_REPLACE_T));
}
strcpy(replaceVol->szPartition_Src, "C");
strcpy(replaceVol->szPartition_Dest, "F");


count, replaceVol);
if (replaceVol)
EssFree(hInst, replaceVol);
}
See Also
l EssArchiveDatabase
EssSendString
Sends a string of data to the active database. This function should be called after
EssBeginReport, EssBeginUpdate, or EssBeginCalc.
605
Syntax
ESS_FUNC_M EssSendString (hCtx, String);
String ESS_STR_T Data string.
Notes
l Calling this function without first successfully executing a begin report, update or calculate
function will generate an error.
l When you are using this function with EssBeginUpdate, you must end the update string
with a carriage return or line feed character.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_HINST_T hInst
)
{
if (!sts)
if (!sts)
/**************
* Get report *
**************/
if (!sts)
{
}
printf ("\r\n");
return(sts);
}
606
applications must use this function to send the UTF-8 encoded Unicode byte order mark (BOM)
in the text stream. For an example, see “Specifying the Byte Order Encoding” on page 69.
See Also
l EssBeginCalc
l EssBeginReport
l EssBeginUpdate
l EssGetString
EssSetActive
Sets the caller's active application and database.
Syntax
ESS_FUNC_M EssSetActive (hCtx, AppName, DbName, pAccess);
pAccess ESS_PACCESS_T Address of variable to receive the user's access level to the selected database. See “Bitmask
Data Types (C)” on page 90 for a list of possible values for this field.
Notes
l If the application and database have not been loaded, this function will load them.
l On Windows, the EssAutoLogin function can also be used to allow a user to login and set
the active application and database.
Return Value
If successful, returns the user's access level to the selected application and database in pAccess.
Access
Example
ESS_FUNC_M
ESS_SetActive (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
607
sts = EssSetActive (hCtx, AppName, DbName,
&Access);
return (sts);
}
See Also
l EssClearActive
l EssGetActive
l EssListDatabases
l EssLogin
EssSetAlias
Sets the active alias table in the active database for a user.
Syntax
ESS_FUNC_M EssSetAlias (hCtx, AliasName);
AliasName ESS_STR_T Name of alias table to set active.
Return Value
None.
Example
ESS_FUNC_M
ESS_SetAlias (ESS_HCTX_T hCtx)
{
AliasName = "TestAlias";
sts = EssSetAlias (hCtx, AliasName);
return (sts);
}
See Also
l EssGetAlias
l EssListAliases
EssSetApplicationAccess
Sets a list of user application access structures, which contain information about user access to
applications.
608
Syntax
ESS_FUNC_M EssSetApplicationAccess (hCtx, Count, pUserApp);
Count ESS_USHORT_T Count of user application structures.
pUserApp “ESS_USERAPP_T, ESS_GROUPAPP_T” on page 183 Pointer to an array of user application structures.
Notes
The Access field of the user application structure is used to set the user's granted access to the
application. For this call the MaxAccess field is ignored.
Return Value
None.
Access
This function requires the caller to have application Design privilege (ESS_PRIV_APPDESIGN)
for the specified application.
Example
ESS_FUNC_M
ESS_SetApplicationAccess (ESS_HCTX_T hCtx)
{
ESS_USHORT_T Count;
ESS_USERAPP_T UserApp;
strcpy(UserApp.UserName,"Jim Smith");
strcpy(UserApp.AppName,"Sample");
UserApp.Access = ESS_PRIV_APPDESIGN;
UserApp.MaxAccess = ESS_PRIV_APPDESIGN;
sts = EssSetApplicationAccess(hCtx, Count,
&UserApp);
return (sts);
}
See Also
l EssListUsers
l EssSetDatabaseAccess
l EssSetUser
EssSetApplicationAccessEx
Sets a list of user application access structures, which contain information about user access to
applications. Similar to EssSetApplicationAccess, but the input structure can include user
609
Syntax
ESS_FUNC_M EssSetApplicationAccessEx (hCtx, Count, pUserApp);
Count ESS_USHORT_T Count of user application structures (input).
pUserApp ESS_PUSERAPPEX_T Pointer to an array of user application structures (input).
Notes
The Access field of the user application structure is used to set the user's granted access to the
application. For this call the MaxAccess field is ignored.
Return Value
None.
Access
This function requires the caller to have application Design privilege (ESS_PRIV_APPDESIGN)
for the specified application.
Example
void DisplayUserAppInfo(ESS_PUSERAPPEX_T userApp, ESS_USHORT_T count)

{
ESS_USHORT_T ind;

{
printf("\tUser: %s\n", userApp[ind].UserName);
printf("\tProvider Name: %s\n", userApp[ind].ProviderName);
printf("\tConnection Param: %s\n", userApp[ind].connparam);
printf("\tAppName: %s\n", userApp[ind].AppName);
switch(userApp[ind].Access)
{
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userApp[ind].Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userApp[ind].Access);
break;
case ESS_PRIV_CALC:
printf("\tAccess: %d - ESS_PRIV_CALC\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_METAREAD\n", userApp[ind].Access);
610
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_METAREAD\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPCREATE\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_FILTER\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", userApp[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userApp[ind].Access);
break;
611
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userApp[ind].Access);
break;
default:
}
switch(userApp[ind].MaxAccess)
{
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userApp[ind].MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userApp[ind].MaxAccess);
break;
case ESS_PRIV_CALC:
printf("\tMax Access: %d - ESS_PRIV_CALC\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_METAREAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_METAREAD\n", userApp[ind].MaxAccess);
break;
612
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPCREATE\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_FILTER\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userApp[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userApp[ind].MaxAccess);
break;
default:
}
printf("\n");
}
}
ESS_FUNC_M ESS_SetApplicationAccessEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T userId;
ESS_USHORT_T type;
ESS_STR_T AppName;
ESS_USHORT_T count;
ESS_USERAPPEX_T userApp[2];
ESS_PUSERAPPEX_T pUserApp = ESS_NULL;
memset(&userApp, '\0', sizeof(userApp));
userId = "IDUser1";
AppName = "";
count = 1;
strcpy(userApp[0].UserName, "IDUser1");
strcpy(userApp[0].ProviderName, "LDAP");
strcpy(userApp[0].connparam, "");
userApp[0].type = ESS_TYPE_USER;
strcpy(userApp[0].AppName, AppName);
613
userApp[0].Access = ESS_PRIV_APPMANAGE;
userApp[0].MaxAccess = ESS_PRIV_APPMANAGE;
sts = EssSetApplicationAccessEx(hCtx, count, &userApp);
printf("EssSetApplicationAccessEx sts: %ld\n", sts);
if(!sts)
{
userId = userApp[0].UserName;
type = userApp[0].type;
sts = EssGetApplicationAccessEx(hCtx, userId, bIsIdentity, type, AppName, &count,
&pUserApp);
printf("EssGetApplicationAccessEx sts: %ld\n", sts);
if(!sts)
{
if(count && pUserApp)
{
DisplayUserAppInfo(pUserApp, count);
sts = EssFree (hInst, pUserApp);
}
else
}
}
return (sts);
}
See Also
EssSetApplicationState
Sets user-configurable parameters for the application using the application's state structure.
Syntax
ESS_FUNC_M EssSetApplicationState (hCtx, AppName, pAppState);
pAppState “ESS_APPSTATE_T” on page 111 Pointer to application state structure.
Notes
l When changing parameter values, it is advisable to call EssGetApplicationState first to
get the correct values of any parameters you do not wish to change.
l The following parameters do not apply to aggregate storage databases: LockTimeout and
lroSizeLimit.
614
Return Value
None.
Access
This function requires the caller to have application designer privilege
(ESS_PRIV_APPDESIGN) for the specified application.
Example
ESS_FUNC_M
ESS_SetAppState (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PAPPSTATE_T AppState;
ESS_STR_T AppName;
AppName = "Sample";
sts = EssGetApplicationState (hCtx, AppName,

&AppState);
if (!sts)
{
if (AppState)
{
/*****************************
* Update AppState structure *
*****************************/
sts = EssSetApplicationState (hCtx,
AppName, AppState);
EssFree (hInst, AppState);
}
return (sts);
}
See Also
l EssSetDatabaseState
EssSetCalcList
Sets the list of calculation script objects which are accessible to a user.
Syntax
ESS_FUNC_M EssSetCalcList (hCtx, UserName, AppName, DbName, AllCalcs, Count,
pCalcList);
615
DbName ESS_STR_T Database name. If NULL, uses Application subdirectory.
AllCalcs ESS_BOOL_T Allow all calcs flag. If TRUE, the user can access all calc scripts, otherwise, they can
only access those specified in the CalcList argument.
Count ESS_USHORT_T Count of the number of accessible calc script objects.
pCalcList ESS_POBJNAME_T Pointer to an array of calc script object names.
Notes
l If the AllCalcs flag is set to TRUE, the Count and pCalcList arguments will be ignored.
l In order to access any calc script objects, the user must have at least calculate access to the
appropriate database.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetCalcList (ESS_HCTX_T hCtx)
{
ESS_STR_T UserName;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_USHORT_T Count;
ESS_OBJNAME_T pCalcList[3];
UserName = "Newuser";
AppName = "Sample";
DbName = "Basic";
AllCalcs = ESS_FALSE ;
Count = 3;
strcpy(pCalcList[0],"test1");
sts = EssSetCalcList(hCtx, UserName, AppName,

DbName, AllCalcs, Count, pCalcList);
return (sts);
}
616
See Also
l EssSetCalcListEx
l EssGetCalcList
l EssListObjects
l EssListUsers
EssSetCalcListEx
Sets the calculation list accessible to the specified user or group. Similar to EssSetCalcList,
but includes users and groups hosted in a user directory.
Syntax
ESS_FUNC_M EssSetCalcListEx (hCtx, UserId, bIsIdentity, entityType, AppName, DbName,
AllCalc, count, pCalcList);
UserID ESS_STR_T Input. User or group for which to set the calculation list. Can be specified as
name@provider or as a unique identity attribute.
bIsIdentity ESS_BOOL_T Input. Indicates whether UserID is a name or an identity. If TRUE, UserID is an
identity.
entityType ESS_USHORT_T Input. Type of entity contained in UserID. Can be one of the following:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
AllCalc ESS_BOOL_T Allow all calcs flag (input). If TRUE, the user or group can access all calculation
scripts; otherwise, only those specified in CalcList are accessible.
Count ESS_USHORT_T Count of the number of accessible calculation script objects (input).
pCalcList ESS_POBJNAME_T Pointer to an array of accessible calculation script object names (input).
Notes
l If the AllCalcs flag is set to TRUE, the Count and pCalcList arguments will be ignored.
l In order to access any calculation script objects, the user must have at least calculate access
to the appropriate database.
Return Value
None.
617
Access
Example
void GetCalcList(ESS_STR_T userName)

{
ESS_BOOL_T AllCalcs = ESS_FALSE;
ESS_POBJNAME_T pCalcList = NULL;
sts = EssGetCalcList(hCtx, userName, AppName, DbName, &AllCalcs, &Count, &pCalcList);

printf("EssGetCalcList sts: %ld\n", sts);
//sts = EssGetCalcListEx(hCtx, userName, AppName, DbName, &AllCalcs, &Count,
&pCalcList);
//printf("EssGetCalcListEx sts: %ld\n", sts);
if(AllCalcs)
printf("\tThis user has access to all script on %s %s\n", AppName, DbName);
else
{
if(!sts && pCalcList)
{
printf("-------- Get Calc List -----------\r\n");
for (ind = 0; ind < Count; ind ++)
printf(" %s\n",pCalcList[ind]);
EssFree(hInst, pCalcList);
}
}
}
ESS_FUNC_M ESS_SetCalcListEx (ESS_HCTX_T hCtx)
{
ESS_STR_T calcUser;
ESS_USHORT_T count;
ESS_OBJNAME_T CalcList[2];
ESS_PUSERINFO_T pUserInfo;
ESS_USHORT_T type;
AllCalcs = ESS_FALSE;
count = 2;
strcpy(CalcList[0],"calc1");
strcpy(CalcList[1],"calc2");
618
sts = EssSetCalcListEx(hCtx, calcUser, bIsIdentity, type, AppName, DbName, AllCalcs,
count, CalcList);
printf("EssSetCalcListEx sts: %ld\n", sts);
if(!sts)
GetCalcList(calcUser);
return (sts);
}
See Also
l EssGetCalcList
l EssListObjects
EssSetDatabaseAccess
Sets a list of user database access structures, which contain information about user access to
databases.
Syntax
ESS_FUNC_M EssSetDatabaseAccess (hCtx, Count, pUserDb);
Count ESS_USHORT_T Count of user database structures.
pUserDb “ESS_USERDB_T, ESS_GROUPDB_T” on page 184 Pointer to an array of user database structures.
Notes
The Access field of the user database structure is used to set the user's granted access to the
database. For this call the MaxAccess and FilterName fields are ignored.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetDatabaseAccess (ESS_HCTX_T hCtx)
{
ESS_USHORT_T Count;
ESS_USERDB_T UserDb[2];
Count = 2;
619
/* Initialize user database structure for user1 */
strcpy(UserDb[0].UserName,"Newuser");
strcpy(UserDb[0].AppName,"Sample");
strcpy(UserDb[0].DbName,"Basic");
UserDb[0].Access = ESS_PRIV_WRITE;
/* Initialize user database structure for user2 */

strcpy(UserDb[1].UserName,"Newuser2");
strcpy(UserDb[1].AppName,"Sample");
strcpy(UserDb[1].DbName,"Basic");
UserDb[1].Access = ESS_PRIV_READ;
sts = EssSetDatabaseAccess(hCtx, Count, UserDb);
return (sts);
}
See Also
l EssGetDatabaseAccess
l EssListUsers
l EssSetUser
EssSetDatabaseAccessEx
Sets a list of user database access structures, which contain information about user access to
databases. Similar to EssSetDatabaseAccess, but the input structure can include user
Syntax
ESS_FUNC_M EssSetDatabaseAccessEx (hCtx, Count, pUserDb);
Count ESS_USHORT_T Count of user database structures (input).
pUserDb ESS_PUSERDBEX_T Pointer to an array of user database structures (input).
Notes
The Access field of the user database structure is used to set the user's granted access to the
database. For this call the MaxAccess and FilterName fields are ignored.
Return Value
None.
Access
620
Example
void DisplayUserDbInfo(ESS_PUSERDBEX_T userDb, ESS_USHORT_T count)

{
ESS_USHORT_T ind;
printf ("\n------Database Access List----\n\n");

{
printf("\tUser: %s\n", userDb[ind].UserName);
printf("\tProvider Name: %s\n", userDb[ind].ProviderName);
printf("\tConnection Param: %s\n", userDb[ind].connparam);
printf("\tApp Name: %s\n", userDb[ind].AppName);
printf("\tDb Name: %s\n", userDb[ind].DbName);
switch(userDb[ind].Access)
{
case ESS_PRIV_NONE:
printf("\tAccess: %d - ESS_PRIV_NONE\n", userDb[ind].Access);
break;
case ESS_PRIV_READ:
printf("\tAccess: %d - ESS_PRIV_READ\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_WRITE\n", userDb[ind].Access);
break;
case ESS_PRIV_CALC:
printf("\tAccess: %d - ESS_PRIV_CALC\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_METAREAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBLOAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_DBCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPLOAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_APPCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_PRIV_USERCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_READ\n", userDb[ind].Access);
621
break;
printf("\tAccess: %d - ESS_ACCESS_WRITE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_CALC\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_METAREAD\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPMANAGE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPCREATE\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_FILTER\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_DBALL\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_APPALL\n", userDb[ind].Access);
break;
printf("\tAccess: %d - ESS_ACCESS_ADMIN\n", userDb[ind].Access);
break;
default:
}
switch(userDb[ind].MaxAccess)
{
case ESS_PRIV_NONE:
printf("\tMax Access: %d - ESS_PRIV_NONE\n", userDb[ind].MaxAccess);
break;
case ESS_PRIV_READ:
printf("\tMax Access: %d - ESS_PRIV_READ\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_WRITE\n", userDb[ind].MaxAccess);
break;
case ESS_PRIV_CALC:
printf("\tMax Access: %d - ESS_PRIV_CALC\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_METAREAD\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBLOAD\n", userDb[ind].MaxAccess);
622
break;
printf("\tMax Access: %d - ESS_PRIV_DBMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_DBCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPLOAD\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_APPCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_PRIV_USERCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_READ\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_WRITE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_CALC\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_METAREAD\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPMANAGE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPCREATE\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_FILTER\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_DBALL\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_APPALL\n", userDb[ind].MaxAccess);
break;
printf("\tMax Access: %d - ESS_ACCESS_ADMIN\n", userDb[ind].MaxAccess);
break;
default:
623
}
printf("\tFilter Name: %s\n", userDb[ind].FilterName);

printf("\n");
}
}
ESS_FUNC_M ESS_SetDatabaseAccessEx (ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T userId;
ESS_USHORT_T type;
ESS_USHORT_T count;
memset(&userDb, '\0', sizeof(userDb));
count = 1;
strcpy(userDb[0].UserName, "IDUser1");
userDb[0].Access = ESS_PRIV_READ;
userDb[0].MaxAccess = ESS_PRIV_READ;
sts = EssSetDatabaseAccessEx(hCtx, count, &userDb);
printf("EssSetDatabaseAccessEx sts: %ld\n\n", sts);
if(!sts)
{
sts = EssGetDatabaseAccessEx(hCtx, userId, bIsIdentity, type, AppName, DbName,
&count, &pUserDb);
printf("EssGetDatabaseAccessEx sts: %ld\n", sts);
if(!sts)
{
if(count && pUserDb)
{
DisplayUserDbInfo(pUserDb, count);
sts = EssFree (hInst, pUserDb);
}
else
}
}
return (sts);
}
See Also
624
EssSetDatabaseNote
Sets a database's note-of-the-day message. This message may be used to display useful
information about the database (whether data has been loaded, when it was last calculated, etc.)
to users before they connect to the database.
Syntax
ESS_FUNC_M EssSetDatabaseNote (hCtx, AppName, DbName, DbNote);
DbNote ESS_STR_T Pointer to database note string.
Notes
The database note string must be less than 64 KB in length.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetDatabaseNote (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T DbNote;
AppName = "Sample";
DbName = "Basic";
DbNote = "This is a test";
sts = EssSetDatabaseNote(hCtx, AppName, DbName,

DbNote);
return (sts);
}
625
See Also
l EssGetDatabaseNote
EssSetDatabaseState
Sets user-configurable parameters for the database using the database's state structure.
Syntax
ESS_FUNC_M EssSetDatabaseState (hCtx, AppName, DbName, pDbState);
pDbState “ESS_DBSTATE_T” on page 121 Pointer to database state structure.
Notes
l EssGetDatabaseState should be called to initialize the ESS_DBSTATE_T structure
before this function is called.
l This function can only set user-configurable parameters for server databases.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetDbState (ESS_HCTX_T hCtx,
ESS_HINST_T hInst
)
{
ESS_PDBSTATE_T DbState;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssGetDatabaseState (hCtx, AppName,

DbName, &DbState);
if (!sts)
{
if (DbState)
626
{
/****************************
* Update DbState structure *
****************************/
sts = EssSetDatabaseState (hCtx, AppName,
DbName, DbState);
EssFree (hInst, DbState);
}
}
return (sts);
}
See Also
l EssSetApplicationState
EssSetDefaultCalc
Sets the default calculation script for the active database.
Syntax
ESS_FUNC_M EssSetDefaultCalc (hCtx, CalcScript);
CalcScript ESS_STR_T Default calculation script string.
Notes
The calculation script string must not be greater than 64 KB long.
Return Value
None.
Access
database.
Example
ESS_FUNC_M
ESS_SetDefaultCalc (ESS_HCTX_T hCtx)
{
sts = EssSetDefaultCalc (hCtx, "CALC ALL;");
return (sts);
}
627
See Also
l EssDefaultCalc
l EssGetDefaultCalc
l EssSetActive
EssSetDefaultCalcFile
Sets the default calculation script for the active database from a calculation script file.
Syntax
ESS_FUNC_M EssSetDefaultCalcFile (hDestCtx, hSrcCtx, AppName, DbName, FileName);
hSrcCtx ESS_HCTX_T API context handle for calculation script file location. The calculation script file can reside
on the client or on the same server as the target database.
AppName ESS_STR_T Application name for calculation script file location.
DbName ESS_STR_T Database name for calculation script file location.
FileName ESS_STR_T Name of default calculation script file.
Notes
l The default calculation script must not be greater than 64 KB long.
l The server makes a copy of the text in the calculation script file when this function is called.
Subsequent changes to the calculation script file have no effect on the default calculation
unless this function is called again to update it.
Return Value
None.
Access
database.
Example
ESS_FUNC_M
ESS_SetDefaultCalcFile (ESS_HCTX_T hCtx)
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
AppName = "Sample";
DbName = "Basic";
628
FileName = "DefTest";
hSrcCtx = hCtx;
sts = EssSetDefaultCalcFile (hCtx, hSrcCtx,
AppName, DbName, FileName);
return(sts);
}
See Also
l EssDefaultCalc
l EssGetDefaultCalc
l EssSetDefaultCalc
EssSetEasLocation
Set or change the Essbase Administration Server location that will be registered with Shared
Services upon application creation or migration.
Syntax
ESS_FUNC_M EssSetEasLocation (hCtx, EasLocation);
EasLocation ESS_STR_T The name (or IP address) and port number of the computer on which Essbase
Administration Server runs. Examples:
Aspen:10080
127.0.0.1:10080
Notes
After changing the Essbase Administration Server location, you must use
EssReRegisterApplication to re-register any existing applications with Shared Services.
Return Value
Access
This function requires the caller to be an Administrator.
Example
ESS_FUNC_M ESS_SS_SetEasLocation(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T easLoc = ESS_NULL;
/* Eas Location */
sts = EssAlloc(hInst, sizeof(ESS_PATHLEN), &easLoc);
if(sts)
return (sts);
memset(easLoc, 0, sizeof(ESS_PATHLEN));
629
strcpy( easLoc, "localhost:10080");
sts = EssSetEasLocation(hCtx, easLoc);
if (sts)
printf("Failed to set EAS Location.\n");
if (easLoc)
EssFree(hInst, easLoc);
return (sts);
}
See Also
l EssReRegisterApplication
EssSetExtUser
Sets user information for externally authenticated users.
Syntax
ESS_FUNC_M EssSetExtUser (hCtx, type, UserName, Password, Protocol, ConnParam);
type ESS_USHORT_T Type of user (external).
Password ESS_STR_T User's password.
Protocol ESS_STR_T External authentication protocol: CSS, for Shared Services mode.
ConnParam ESS_STR_T External authentication connection parameters. Null, for CSS protocol.
Access
(ESS_PRIV_USERCREATE) for the logged in server, unless they are setting their own user
information.
EssSetFilter
Creates or replaces a filter, and starts setting the contents of the filter.
Syntax
ESS_FUNC_M EssSetFilter (hCtx, AppName, DbName, FilterName, Active, Access);
630
FilterName ESS_STR_T Filter name. See “Filter Name Limits” on page 1256.
Active ESS_BOOL_T Filter active flag. If TRUE, the filter is set active, otherwise it is set inactive.
Access ESS_ACCESS_T The default filter access level.
Notes
l If the filter does not already exist, it will first be created by this call.
l This call must be followed by successive calls to EssSetFilterRow to set all the rows for
the filter.
l To avoid overwriting a filter that already exists, use EssCreateFilter. EssCreateFilter
creates only a uniquely named filter for a particular database, but will not overwrite an
existing filter of the same name on the same database.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetFilter (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_BOOL_T Active;
ESS_ACCESS_T Access, AccessAry[3];
ESS_USHORT_T ind;
AppName = "Sample";
DbName = "Basic";
Active = ESS_TRUE;
/***** Set Filter *****/

sts = EssSetFilter(hCtx, AppName, DbName,
FilterName, Active, Access);
if(!sts)
{
631
AccessAry[0] = ESS_ACCESS_READ;
AccessAry[1] = ESS_ACCESS_NONE;
AccessAry[2] = ESS_ACCESS_WRITE;
/***** Set Filter Rows *****/
for(ind = 0; ind < 3; ind++)

{
sts = EssSetFilterRow(hCtx, RowString[ind],
AccessAry[ind]);
if(sts)
printf("Cannot set Filter row %s\r\n",
RowString[ind]);
}
sts = EssSetFilterRow(hCtx,
"",ESS_ACCESS_NONE);
}
return (sts);
}
See Also
l EssCreateFilter
l EssGetFilter
l EssListFilters
l EssSetFilterRow
EssSetFilterList
Sets the list of groups or users that are assigned to a filter. The count parameter controls the
number of groups or users assigned to the filter. A count of zero will remove all the groups or
Syntax
ESS_FUNC_M EssSetFilterList (hCtx, AppName, DbName, FilterName, Count, pUserList);
Count ESS_USHORT_T Count of groups or users assigned this filter.
pUserList ESS_PUSERNAME_T Pointer to array of user names.
632
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetFilterList (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_USERNAME_T UserList[2];
AppName = "Sample";
DbName = "Basic";
strcpy(UserList[0],"Jim Smith");
strcpy(UserList[1],"Newuser");
Count = 2;
sts = EssSetFilterList(hCtx, AppName, DbName,

FilterName, Count, UserList);
return (sts);
}
See Also
l EssSetFilterListEx
l EssGetFilterList
l EssListFilters
l EssSetFilter
EssSetFilterListEx
Sets the list of groups or users that are assigned to a filter. The count parameter controls the
number of groups or users assigned to the filter. A count of zero will remove all the groups or
Similar to EssSetFilterList, but includes users and groups hosted in a user directory.
Syntax
ESS_FUNC_M EssSetFilterListEx (hCtx, AppName, DbName, FilterName, bIsIdentity,
entityType, Count, UserList);
633
FilterName ESS_STR_T Filter name (input).
bIsIdentity ESS_BOOL_T Input. Indicates whether userList contains names or identities. If TRUE, userList
contains identities.
The list can contain names or identities, but not both.
entityType ESS_USHORT_T Type of entity contained in userList (input). Can be one of the following:
l ESS_TYPE_USER
l ESS_TYPE_GROUP
The list can contain users or groups, but not both.
Count ESS_USHORT_T Count of entities contained in userList (input).
UserList ESS_PSTR_T Array of user or group names or identities (input).
Return Value
None.
Access
Example
void GetFilterList()
{
ESS_USHORT_T ind;
FilterName = "Filter1";
sts = EssGetFilterList(hCtx, AppName, DbName, FilterName, &Count, &UserList);

printf("EssGetFilterList sts: %ld\n", sts);
if(!sts)
{
printf("--------%s User List---------\n", FilterName);
if(Count && UserList)
{
printf("%s\n",UserList[ind]);
EssFree(hInst, UserList);
}
else
634
printf("none.");
printf("\n");
}
ESS_FUNC_M ESS_SetFilterListEx (ESS_HCTX_T hCtx)
{
//ESS_USERNAME_T UserList[2];
ESS_STR_T UserList[2];
ESS_USHORT_T type;
FilterName = "Filter1";
UserList[0] = "IDUser9@ldap";
UserList[1] = "IDUser10@ldap";
Count = 2;
sts = EssSetFilterListEx(hCtx, AppName, DbName, FilterName, bIsIdentity, type, Count,

UserList);
printf("EssSetFilterListEx sts: %ld\n", sts);
if(!sts)
GetFilterList();
return (sts);
}
See Also
l EssGetFilterList
l EssListFilters
l EssSetFilter
EssSetFilterRow
Sets the next row of a filter.
Syntax
ESS_FUNC_M EssSetFilterRow (hCtx, RowString, Access);
RowString ESS_STR_T Pointer to the next row of the filter.
Access ESS_ACCESS_T Access level for the filter row.
635
Notes
This function should be called repeatedly after calling EssSetFilter, once for each row of the
filter, terminating the row list with a NULL row string pointer.
Return Value
None.
Access
Example
See the example of EssSetFilter.
See Also
l EssListFilters
l EssSetFilter
EssSetGlobalState
Sets the server global state structure which contains parameters for system administration.
Syntax
ESS_FUNC_M EssSetGlobalState (hCtx, pGlobal);
pGlobal “ESS_GLOBAL_T” on page 134 Pointer to global state structure.
Notes
When changing parameter values, it is advisable to call EssGetGlobalState first to get the
correct values of any parameters you do not wish to change.
Return Value
None.
Access
This function requires the caller to be an administrator.
Example
ESS_FUNC_M
ESS_SetGlobalState (ESS_HCTX_T hCtx)
{
ESS_GLOBAL_T Global;
636
/* Initialize Global State */
Global.Security = 1;
Global.Logins = 1;
Global.Access = ESS_ACCESS_NONE;
Global.Validity = 200;
Global.Currency = 1;
Global.PwMin = 8;
Global.InactivityTime = 3600;
Global.InactivityCheck = 300;
sts = EssSetGlobalState(hCtx, &Global);

return (sts);
}
See Also
l EssGetGlobalState
EssSetGroup
Sets a group information structure, which contains security information for the group.
Syntax
ESS_FUNC_M EssSetGroup (hCtx, pGroupInfo);
pGroupInfo “ESS_USERINFO_T, ESS_GROUPINFO_T” on page 186 Pointer to group info structure.
Notes
l The name of the group to set is a field in the group info structure, which must always be
specified.
l The only field in the group info structure which may be changed using this function is the
Access field (the other fields are used for users of for information only). See the description
of the ESS_GROUPINFO_T structure for more information.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetGroup (ESS_HCTX_T hCtx)
{
637
ESS_USERINFO_T Group;
strcpy(Group.Name,"PowerUsers");
strcpy(Group.AppName,"Sample");
strcpy(Group.DbName,"Basic");
Group.Access = ESS_ACCESS_SUPER;
sts = EssSetGroup(hCtx, &Group);

return (sts);
}
See Also
l EssGetGroup
l EssListGroups
EssSetGroupList
Sets the list of users who are members of a group.
Syntax
ESS_FUNC_M EssSetGroupList (hCtx, GroupName, Count, pUserList);
GroupName ESS_STR_T Group name or user name.
Count ESS_USHORT_T Count of user names.
pUserList ESS_PUSERNAME_T Pointer to an array of user name strings.
Notes
This function can also be used to set the list of groups to which a user belongs by using a user
name as the GroupName argument and passing a list of groups as the pUserList argument.
An administrator that is not an Essbase administrator, in order to administer privileges on users
and groups, must have higher privileges than those users and groups on the applications on
which they are administering access. To bypass this restriction, use MaxL for adding users to
groups.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_SetGroupList (ESS_HCTX_T hCtx)
638
{
ESS_USERNAME_T UserList[3];
ESS_USHORT_T Count;
GroupName = "Powerusers";
strcpy(UserList[0],"App Designer");
strcpy(UserList[1],"Db Designer");
strcpy(UserList[2],"User Creator");
Count = 3;
sts = EssSetGroupList (hCtx, GroupName, Count,

UserList);
return (sts);
}
See Also
l EssSetGroupListEx
l EssAddToGroup
l EssListGroups
EssSetGroupListEx
Sets the list of users who are members of a group. Similar to EssSetGroupList, but can accept
a user directory specification or unique identity attribute for EntityId.
Syntax
ESS_FUNC_M EssSetGroupListEx (hCtx, EntityId, bIsIdentity, entityType, Count, pIdList,
bUsingIdentity);
EntityId ESS_STR_T User or group name (input). Can be specified as name@provider or as a unique
identity attribute.
bIsIdentity ESS_BOOL_T Input. Indicates if EntityId is a name or an identity. If TRUE, EntityId is an identity.
entityType ESS_USHORT_T Input. Indicates if EntityId is a group or a user. If specified as user, then the list can
consist of only groups. In EPM System security mode, the list can consist of both
users and groups.
Count ESS_USHORT_T Count of identities (input).
pIdList ESS_PSTR_T Pointer to an array of identities (input).
bUsingIdentity ESS_BOOL_T Input. Indicates if EntityId is a name or an identity. If TRUE, EntityId is an identity.
Notes
This function can also be used to set the list of groups to which a user belongs by using a user
name as the EntityID argument and passing a list of groups as the pUserIDList argument.
639
An administrator that is not an Essbase administrator, in order to administer privileges on users
and groups, must have higher privileges than those users and groups on the applications on
which they are administering access.
Return Value
None.
Access
Example
See Also
l EssAddToGroupEx
EssSetGroupToSS
Migrates a group to EPM System security mode. This might be useful if the group migration
failed using EssSetSSSecurityMode.
Syntax
ESS_FUNC_M EssSetGroupToSS (hCtx, GroupName);
GroupName ESS_STR_T Name of the group to convert to Shared Services (input).
Return Value
Access
Example
ESS_FUNC_M ESS_SS_SetGroupToSS(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T groupName = ESS_NULL;
sts = EssAlloc(hInst, sizeof(ESS_USERNAME_T), &groupName);

if(sts)
return (sts);
memset(groupName, 0, sizeof(ESS_USERNAME_T));
strcpy( groupName, "essgrp");
640
sts = EssSetGroupToSS(hCtx, groupName);
if(sts)
printf("Failed to migrate Group %s to Shared Services mode.\n", groupName);
if (groupName)
EssFree(hInst, groupName);
return (sts);
}
EssSetGroupsToSS
Migrates all groups to EPM System security mode. This might be useful if the group migration
failed using EssSetSSSecurityMode.
Syntax
ESS_FUNC_M EssSetGroupsToSS (hCtx);
Return Value
Access
Example
ESS_FUNC_M ESS_SS_SetGroupsToSS(ESS_HCTX_T hCtx)
{
sts = EssSetGroupsToSS(hCtx);
if(sts)
printf("Failed to migrate Groups to Shared Services mode.\n");
return (sts);
}
EssSetPassword
Sets a user's password, erasing the existing password.
641
Syntax
ESS_FUNC_M EssSetPassword (hCtx, UserName, Password);
Password ESS_STR_T New password for user.
Notes
l To change a password, the caller must either have supervisor access, or be changing their
own password.
l The new password will take effect the next time the user logs in.
Return Value
None.
Access
This function requires callers to have Create/Delete User privilege (ESS_PRIV_USERCREATE)
for the logged in server, unless they are setting their own password.
Example
ESS_FUNC_M
ESS_SetPassword (ESS_HCTX_T hCtx)
{
ESS_STR_T UserName;
ESS_STR_T Password;

Password = "newpwd";
sts = EssSetPassword (hCtx,UserName, Password);
return (sts);
}
See Also
l EssListUsers
l EssSetUser
EssSetPath
Sets the ESSBASEPATH environment variable for the runtime process.
Syntax
ESS_FUNC_M EssSetPath (pszPath);
642
pszPath; ESS_STR_T Pointer to the string describing the ESSBASEPATH environment variable
Notes
l Call EssSetPath() before calling EssInit().
l pszPath cannot exceed 120 characters, as defined in ESS_PATHLEN.
l pszPath applies only to the current process.
l Essbase DLLs must be accessible from the system path. EssSetPath() does not resolve the
path for the Essbase DLLs.
Return Value
l If successful, returns ESS_STS_NOERR.
l If pszPath is too long, returns API_NAME_TOO_LONG (1030009).
Example
ESS_STS_T
ESS_SetPath()
{
ESS_STS_T sts;
ESS_STR_T pszPath = "C:\Hyperion\products\Essbase";
sts = EssSetPath (pszPath);
return sts;
}
EssSetServerMode
Sets the mode of Essbase Server to be Unicode or non-Unicode. Only when it is in Unicode
mode does Essbase Server allow creation of Unicode mode applications or migration of non-
Unicode mode applications to Unicode mode. Setting a Unicode mode server to non-Unicode
does not affect the existing Unicode-related mode of existing applications.
Syntax
ESS_FUNC_M EssSetServerMode(hCtx, bUnicode);
hCtx ESS_HCTX_T API context handle (logged in)
bUnicode ESS_BOOL_T The pass-in parameter, bUnicode, where bUnicode can be one of the following values:
l ESS_TRUE—Sets the server mode to Unicode.Essbase Server allows creation of
Unicode mode applications or migration of non-Unicode mode applications to
Unicode mode.
l ESS_FALSE—Sets the server mode to non-Unicode. Essbase Server does not allow
creation of Unicode mode applications or migration of non-Unicode mode
applications to Unicode mode.
643
Return Value
None.
Access
This function requires the caller to have (AD_ACCESS_SUPER) privilege for the logged in
server.
See Also
l EssGetServerMode
EssSetSpanRelationalPartition
Sets the Boolean bSpanRelPart field informing Essbase that pertinent data exists in an attached
relational store. Some other API functions, such as EssQueryDatabaseMembers, read
bSpanRelPart and access the relational store if bSpanRelPart is set.
Syntax
ESS_FUNC_M EssSetSpanRelationalPartition (hCtx);
Notes
Several API functions have been enhanced to retrieve information from relational stores.
l EssQueryDatabaseMembers - returns member names from the relational store.
l EssGetMemberInfo - returns information on members in the relational store.
l EssCheckMemberName - checks in the relational store for valid member names.
l EssGetMemberCalc - recognizes a relational member passed as input and returns a null
string for all relational members.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_HINST_T hInst
)
{
644
if (!sts)
if (!sts)
sts = EssSetSpanRelationalPartition (hCtx);
/**************
* Get report *
**************/
if (!sts)
{
}
printf ("\r\n");
return(sts);
}
See Also
l EssClrSpanRelationalSource
EssSetSSSecurityMode
Migrates Essbase Server and any existing users and groups to EPM System security mode.
Syntax
ESS_FUNC_M EssSetSSSecurityMode (hCtx, option, NewPassword, FileName, flag);
option ESS_USHORT_T Integer representing the desired password creation method for migrated users.
l 0—Use an administrator-specified password.
l 1—Create passwords that are the same as user names for users being migrated
to Shared Services.
Note: The passwords are created as lower-case, even if there are upper-case
letters in the user name.
l 2—Automatically generate new passwords for the users being migrated to
Shared Services.
NewPassword ESS_STR_T Password string (if option 2 is used).
FileName ESS_STR_T Name of file to contain saved passwords. If not provided, the default file is
$ARBORPATH/bin/MigratedUsersPassword.txt.
645
flag ESS_USHORT_T Whether the passwords file, if already existing, should be overwritten.
l ESS_FILE_OVERWRITE—Overwrite
l ESS_FILE_NOOVERWRITE—Do not overwrite; return an error.
Return Value
Access
Example
ESS_FUNC_M ESS_SS_SetSSSecurityMode(ESS_HCTX_T hCtx)
{
ESS_STR_T newpassword = ESS_NULL;
ESS_USHORT_T option;
ESS_STR_T fName = ESS_NULL;
ESS_USHORT_T flag = 0;
/* New Shared Services Native User Password Option:

*
* 0 to use user provided password
* 1 to use the user name as password
* 2 to automatically generate a password
**/
option = 1; /* Using user name as password */
sts = EssSetSSSecurityMode(hCtx, option, newpassword, fName, flag);
if(sts)
printf("Failed to migrate Essbase Server to Shared Services mode.\n");
return (sts);
}
See Also
l EssSetUserToSS
l EssSetGroupToSS
EssSetUserToSS
Migrates a user to EPM System security mode. This might be useful if the user migration failed
using EssSetSSSecurityMode.
Syntax
ESS_FUNC_M EssSetUserToSS (hCtx, UserName, option, NewPassword, FileName, flag);
646
UserName ESS_STR_T Name of the user to convert to Shared Services (input).
to Shared Services.
Shared Services.
FileName ESS_STR_T Name of file to contain saved passwords. If not provided, the default file is
$ARBORPATH/bin/MigratedUsersPassword.txt.
Return Value
Access
Example
ESS_FUNC_M ESS_SS_SetUserToSS(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T userName = ESS_NULL;
ESS_STR_T fName = ESS_NULL;
ESS_USHORT_T flag = ESS_FILE_OVERWRITE;
sts = EssAlloc(hInst, sizeof(ESS_USERNAME_T), &userName);

if(sts)
return (sts);
memset(userName, 0, sizeof(ESS_USERNAME_T));
strcpy( userName, "essexer");

*
**/
647
option = 2; /* Generate password */
sts = EssSetUserToSS(hCtx, userName, option, newpassword, fName, flag);
if(sts)
printf("Failed to migrate User %s to Shared Services mode.\n", userName);
if (userName)
EssFree(hInst, userName);
return (sts);
}
See Also
l EssSetUsersToSS
l EssSetGroupToSS
l EssSetSSSecurityMode
EssSetUser
Sets a user information structure, which contains security information for the user.
Syntax
ESS_FUNC_M EssSetUser (hCtx, pUserInfo);
pUserInfo “ESS_USERINFO_T, ESS_GROUPINFO_T” on page 186 Pointer to user info structure.
Notes
l The name of the user to set is a field in the user info structure, which must always be specified.
l The only fields in the user info structure which may be changed using this function are the
Access, Expiration, and PwdChgNow fields (the other fields are for information only). See
the description of the ESS_USERINFO_T structure for more information.
l The caller cannot give the specified user any access privileges that they themselves do not
already have.
l The new user settings will take effect the next time the user logs in.
Return Value
Access
648
Example
ESS_FUNC_M
ESS_SetUser (ESS_HCTX_T hCtx)
{
ESS_USERINFO_T User;
strcpy(User.Name,"Jim Smith");
strcpy(User.AppName,"Sample");
strcpy(User.DbName,"Basic");
User.Access = ESS_ACCESS_SUPER;
sts = EssSetUser (hCtx,&User);

return (sts);
}
See Also
l EssGetUser
l EssListUsers
l EssSetPassword
EssSetUserEx
Sets a user information structure, which contains security information for the user.
Syntax
ESS_FUNC_M EssSetUser (hCtx, pUserInfo);
pUserInfoEx “ESS_USERINFOEX_T” on page 189 Pointer to info structure of externally authenticated user.
Notes
l The name of the user to set is a field in the user info structure, which must always be specified.
l The only fields in the user info structure which may be changed using this function are the
Access, Expiration, and PwdChgNow fields (the other fields are for information only). See
the description of theESS_USERINFO_T structure for more information.
l The caller cannot give the specified user any access privileges that they themselves do not
already have.
l The new user settings will take effect the next time the user logs in.
Return Value
649
Access
Example
ESS_FUNC_M
ESS_SetUser (ESS_HCTX_T hCtx)
{
ESS_USERINFO_T User;
strcpy(User.Name,"Jim Smith");
strcpy(User.AppName,"Sample");
strcpy(User.DbName,"Basic");
User.Access = ESS_ACCESS_SUPER;
sts = EssSetUserEx (hCtx,&User);

return (sts);
}
See Also
l EssGetUser
l EssListUsers
l EssCreateExtUser
l EssGetUserEx
l EssSetPassword
EssSetUsersToSS
Migrates all users to Oracle Enterprise Performance Management System security mode. This
might be useful if the user migration failed using EssSetSSSecurityMode.
Syntax
ESS_FUNC_M EssSetUsersToSS (hCtx, option, NewPassword, FileName, flag);
650
to Shared Services.
Oracle Hyperion Shared Services.
FileName ESS_STR_T Name of file to contain saved passwords. If null, the default file is $ARBORPATH/
bin/MigratedUsersPassword.txt.
Return Value
Access
Example
ESS_FUNC_M ESS_SS_SetUsersToSS(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T fName = "PasswordList.txt";

*
**/
option = 2; /* Generate a password */
sts = EssSetUsersToSS(hCtx, option, newpassword, fName, ESS_FILE_OVERWRITE);
651
if(sts)
printf("Failed to migrate Users to Shared Services mode.\n");
return (sts);
See Also
l EssSetUserToSS
l EssSetGroupToSS
l EssSetSSSecurityMode
EssSetUserType
Enables you to define the application access type for a user. You can add, remove, or replace
different application access types for a user name.
The application access type is a user property. If a user is created inOracle Hyperion Planning,
it automatically has an application access type of planning; if a user is created in Administration
Services, it automatically has an application access type of Essbase. Once a user is created, the
application access type can be modified in the corresponding application using EssSetUserType.
Syntax
ESS_FUNC_M EssSetUserType (hCtx, UserName, UserType, Cmd)
UserType ESS_USER_TYPE_T ESS_USER_ESSBASE is the application access type, if no application access

type is specified. This user will be enabled with all functionality.
Cmd ESS_USERTYPE_CMD_T Whether to add/remove/replace the type specified. Only the Essbase type,
ESS_USER_ESSBASE, can be added or removed.
l ESS_USERTYPE_CMD_ADD—Adds the new type specified to the
existing application access type.
l ESS_USERTYPE_CMD_REMOVE—Removes the types specified from
the existing application access type.
Return Value
Returns the status of the API.
Example
ESS_FUNC_M
ESS_SetUserType (ESS_HCTX_T hCtx)
{
652
ESS_STR_T UserName="jsmith";
ESS_USER_TYPE_T UserType = ESS_USER_ESSBASE;
ESS_USERTYPE_CMD_T cmd = ESS_USERTYPE_CMD_ADD;
sts = EssSetUserType (hCtx, UserName, UserType, Cmd);
return (sts);
}
See Also
l EssGetUserType
EssShutdownServer
Stops the Essbase Agent. This function sends a request to the Agent (ESSBASE.EXE) to shut
itself down. The Agent then goes through its normal shutdown procedure, including committing
data, stopping all applications and databases, and logging users off before stopping.
Only users with Supervisor privilege can shut down the Agent.
This function can be called at any time, however, it is normally called to shut down an Agent
process which was started in the background. See the Oracle Essbase Database Administrator's
Guide for details.
Syntax
ESS_FUNC_M EssShutdownServer (hInstance, Server, UserName, Password);
Server ESS_STR_T Network server name string. Specifies the name of the server to shut down.
UserName ESS_STR_T User name string. Specifies the user who is requesting the shutdown.
Password ESS_STR_T Password string. Specifies the password of the user requesting the shutdown.
Return Value
Possible error conditions resulting from this function include:
l Insufficient privilege for this operation, AD_AMSG_IPO
l Incorrect password, AD_AMSG_IPW
l User does not exist, AD_AMSG_UNE
l Cannot shutdown application, AD_MSGAR_NOSHUTDOWN
l Network Error: Unable To Locate In Hosts File, NET_TCP_HOSTS
l Network error: Cannot locate server, NET_NP_NOSERVER
Access
This function requires Supervisor privilege.
653
Example
ESS_FUNC_M
ESS_ShutdownServer (ESS_HINST_T hInst)
{
ESS_STR_T Server;
ESS_STR_T UserName;
ESS_STR_T Password;
Server = "Rainbow";
UserName = "Admin";
Password = "password";
sts = EssShutdownServer(hInst, Server,
UserName, Password);
return (sts);
}
See Also
l EssSetPassword
l EssUnloadApplication
l EssUnloadDatabase
EssTerm
Terminates the API and releases all system resources used by the API. This function should
normally be called after all other API calls have been completed, immediately prior to
terminating your program.
Syntax
ESS_FUNC_M EssTerm (hInstance);
Notes
Because this function terminates use of the Essbase API, any API functions (other than
EssInit) called after this function has been executed will return an error.
Return Value
None.
Access
This function requires no special access.
Example
/* Terminate the Essbase API */
if ((sts = EssTerm (hInstance)) != ESS_STS_NOERR)
{
654
exit ((ESS_USHORT_T) sts);
}
See Also
l EssInit
EssUnloadApplication
Stops an application on the server.
Syntax
ESS_FUNC_M EssUnloadApplication (hCtx, AppName);
AppName ESS_STR_T Name of application to load.
Notes
To unload an application, the connected user must have load access to the application. An
application cannot be unloaded if Essbase is restructuring a database associated with the
application.
Return Value
None.
Access
This function requires the caller to have Application Load/Unload privilege
(ESS_PRIV_APPLOAD) for the specified application.
Example
ESS_FUNC_M
ESS_UnloadApplication (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
AppName = "Sample";
return (sts);
}
See Also
l EssUnloadDatabase
655
EssUnloadDatabase
Stops a database within an application on the server.
Syntax
ESS_FUNC_M EssUnloadDatabase (hCtx, AppName, DbName);
DbName ESS_STR_T Name of database to unload.
Return Value
None.
Access
This function requires the caller to have database load/unload privilege
(ESS_PRIV_APPLOAD).
Example
ESS_FUNC_M
ESS_UnloadDb (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
/*
* IF the current active is the same as the
* unload db, ClearActive first
*/
/*
* ELSE
*/
sts = EssUnloadDatabase(hCtx, AppName,
DbName);
return (sts);
}
See Also
l EssLoadDatabase
l EssUnloadDatabase
EssUnlockObject
Unlocks a locked object on the server or client object system.
656
Syntax
ESS_FUNC_M EssUnlockObject (hCtx, ObjType, AppName, DbName, ObjName);
AppName ESS_STR_T Application name
ObjName ESS_STR_T Name of object to unlock.
Notes
To unlock an object, the object must already exist and be locked by the caller.
Return Value
None.
Access
Example
ESS_FUNC_M
ESS_UnlockObject (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T ObjName;
AppName = "Sample";
DbName = "Basic";
ObjName = "Basic";
sts = EssUnlockObject(hCtx, ObjType, AppName,

DbName, ObjName);
if(!sts)
printf("The Object is unlocked\r\n");
return (sts);
}
See Also
l EssGetObject
l EssGetObjectInfo
657
l EssListObjects
l EssLockObject
l EssPutObject
EssUpdate
Sends an update specification to the active database as a single string.
Syntax
ESS_FUNC_M EssUpdate (hCtx, Store, Unlock, UpdtSpec);
UpdtSpec ESS_STR_T The update specification, as a single string.
Notes
l This function is equivalent to making a call to EssBeginUpdate, followed by calls to
EssSendString and finally EssEndUpdate. The update data can either be stored in the
database, or just verified and any errors returned. Also, any data blocks locked for update
can be unlocked by this call.
l If this function causes data to be stored (Store flag is TRUE), the relevant data blocks must
previously have been locked for update (for example, by calling EssReport with the Lock
flag set to TRUE).
l If the caller attempts to write data to a member it does not have permission to write to, a
warning is generated, and the member is not updated.
Return Value
None.
Access
database. If the caller attempts to write information.
Example
ESS_FUNC_M
ESS_Update (ESS_HCTX_T hCtx)
{
658
sts = EssUpdate (hCtx, ESS_TRUE, ESS_FALSE,
"Year Market Scenario Measures Product 100");
return(sts);
}
See Also
l EssBeginUpdate
l EssEndUpdate
l EssReport
l EssSendString
l EssUpdateFile
EssUpdateBakFile
Compares the security backup file essbase_timestamp.bak to the security file
essbase.sec and overwrites the backup file with the security file if the two files do not match.
Syntax
ESS_FUNC_M EssUpdateBakFile (hCtx);
Notes
Essbase compares the security file and the backup file every time the server starts. The MaxL
statement alter system sync security_backup can be used to automatically compare the security
backup file to the security file at specified intervals or on demand. When Essbase compares the
files, it updates the backup file to match the security file.
Return Value
Access
Example
ESS_FUNC_M
ESS_UpdateBakFile (ESS_HCTX_T hCtx)
{
sts = EssUpdateBakFile(hCtx);
return sts;
}
659
EssUpdateDrillThruURL
Updates a drill-through URL, with the given name, within the active database outline.
Syntax
ESS_FUNC_M EssUpdateDrillThruURL (hCtx, ESS_PDURLINFO_T pUrl);
bMerge ESS_BOOL_T l If True, add drill-through region definitions in pUrl to the existing list of drill-
through regions in the named URL definition
l If False, replace the existing list of drill-through region definitions with the list
in pUrl
Return Value
l If successful, updates the named drill-through URL in the active database by replacing the
URL XML and either updating or replacing the drill-through region list with the
corresponding fields in pUrl.
l If there is no URL with the given name, returns an error code.
Access
l Caller must have database design privilege (ESS_PRIV_DBDESIGN) for the specified
database.
EssSetActive.
Example
/* Sample Code for EssUpdateDrillThruURL */

ESS_DURLINFO_T url;
ESS_STR_T fileName = "";
ESS_CHAR_T xmlString[XML_CHAR_MAX];
ESS_BOOL_T bMerge;
ESS_USHORT_T i;
memset(&url, '\0', sizeof(ESS_DURLINFO_T));

fileName = "F:\\testarea\\mainapi\\sample1.xml";
GetFileContent(fileName, xmlString);
/* Update URL*/
url.bIsLevel0 = ESS_TRUE;
url.cpURLName = "Drill Through to EPMI";
url.cpURLXml = xmlString;
url.iURLXmlSize = (ESS_SHORT_T) strlen(xmlString)+1;
660
url.iCountOfDrillRegions = 1;
sts = EssAlloc (hInst, sizeof(ESS_STR_T) * url.iCountOfDrillRegions,
&(url.cppDrillRegions));
/* With bMerge = ESS_FALSE, update Drill Regions */
bMerge = ESS_FALSE; // replace

url.cppDrillRegions[0] = "Mar";
sts = EssUpdateDrillThruURL(hCtx, &url, bMerge);
printf("EssUpdateDrillThruURL sts: %ld\n",sts);
EssUpdateEx
Sends an update specification to the active database as a single string, capturing any data load
errors in ppMbrError.
Syntax
ESS_FUNC_M EssUpdateEx (hCtx, Store, Unlock, UpdtSpec, ppMbrError);
Store ESS_BOOL_T Controls storage of data. If TRUE, data is stored in the server; if FALSE, no data is
stored.
Unlock ESS_BOOL_T Controls unlocking of data blocks. If TRUE, all relevant blocks which are locked
will be unlocked (after data is stored, if necessary). If FALSE, no blocks are unlocked.
ppMbrError ESS_PPMBRERR_T Linked list of ESS_MBRERR_T structures representing the data load errors. Possible
errors are:
l AD_MSGDL_ERRORLOAD—Unable to do dataload at Item/Record
[number].
l ESS_MBRERR_BADDATA—Invalid member [membername] in data column.
l ESS_MBRERR_DBACCESS—You have insufficient access privilege to
perform a lock on this database.
l ESS_MBRERR_DUPLICATE—Duplicate members from the same dimension
on data record, [number] records completed.
l ESS_MBRERR_UNKNOWN—Unknown member [membername] in
dataload, [number] records returned.
Notes
l The update data can either be stored in the database, or just verified and any errors returned.
Also, any data blocks locked for update can be unlocked by this call.
661
Return Value
Returns zero if successful; otherwise, returns an error code and the records that caused the error.
Access
database.
Example
void TestUpdateEx()
{
ESS_PMBRERR_T pMbrError;
ESS_STR_T updtSpec = "";
sts = EssUpdateEx(hCtx, ESS_TRUE, ESS_FALSE, "'Jan' 'New York' 'Actual' 'Sales'

'100-10' 123 \n '100-20' 345 \n '100-30' 678", &pMbrError);
printf("EssUpdateEx sts: %ld\n",sts);
if(!sts)
{
printf("\nVerify data:\n");
VerifyDataload("'Jan' 'New York' 'Actual' 'Sales' <IDESC '100'!");
printf("\nMember Error Info:\n");

if(pMbrError)
DisplayError(pMbrError);
else
printf("\tError structure is empty.\n");
}
if(pMbrError)
EssFreeMbrErr(ESS_HCTX_T hCtx), pMbrError);
}
See Also
l EssUpdateFileASO
l EssUpdateFileASOEx
l EssUpdateFileEx
l EssUpdateFileUTF8ASOEx
l EssUpdateFileUtf8Ex
l EssUpdateUtf8Ex
EssUpdateFile
Sends an update specification to the active database from a file. The update data can either be
stored in the database, or just verified and any errors returned. Also, any data blocks locked for
update can be unlocked by this call.
662
Syntax
ESS_FUNC_M EssUpdateFile (hDestCtx, hSrcCtx, AppName, DbName, FileName, Store, Unlock);
hSrcCtx ESS_HCTX_T API context handle for report file location. The report file can reside on the client or on the
same server as the target database.
AppName ESS_STR_T Application name for update file location.
DbName ESS_STR_T Database name for update file location.
FileName ESS_STR_T Name of update specification file.
Notes
l If this function causes data to be stored (Store flag is TRUE), the relevant data blocks must
previously have been locked for update (e.g. by calling EssReport with the Lock flag set to
TRUE).
Return Value
None.
Access
database.
Example
ESS_FUNC_M
ESS_UpdateFile (ESS_HCTX_T hCtx)
{
ESS_HCTX_T hSrcCtx;
ESS_BOOL_T isStore;
ESS_BOOL_T isUnlock;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
AppName = "Sample";
DbName = "Basic";
hSrcCtx = hCtx;
isStore = ESS_TRUE;
isUnlock = ESS_FALSE;
sts = EssUpdateFile (hCtx, hSrcCtx, AppName,
663
DbName, FileName, isStore, isUnlock);
return(sts);
}
See Also
l EssBeginUpdate
l EssReportFile
l EssUpdate
EssUpdateFileASO
Sends an update specification to the active aggregate storage database from a file.
Syntax
ESS_FUNC_M EssUpdateFileASO (hDestCtx, hSrcCtx, AppName, DbName,
FileName, Store, Unlock, ulBufferId);
hDestCtx ESS_HCTX_T API context handle of target database on the server
hSrcCtx ESS_HCTX_T API context handle for update file location. The update file can reside on the client or on
the same server as the target database.
Unlock ESS_BOOL_T Not supported for aggregate storage databases. You must always pass ESS_FALSE for this
parameter.
ulBufferId ESS_ULONG_T ID number for the data load buffer.
Notes
If the Store flag is set to FALSE, the database performs only a syntax check of the update
specification.
Return Value
Access
database.
Example
void TestUpdateFileASO(ESS_HCTX_T hCtx, ESS_STR_T AppName, ESS_STR_T DbName)
{
664
ESS_HCTX_T hSrcCtx;
ESS_BOOL_T isStore;
ESS_STR_T FileName;
ESS_ULONG_T ulSize;
ulSize = 100;
ulBufferId = 101;
/* Update from server*/

hSrcCtx = hCtx;
isStore = ESS_TRUE;
FileName = "data1.txt";
sts = EssUpdateFileASO (hCtx, hSrcCtx, AppName, DbName, FileName, isStore,

isUnlock, ulBufferId);
printf("EssUpdateFileASO sts: %ld\n",sts);
/* Commit and delete the buffer */

ulBufferCnt = 1;
printf("\nLoad data to main slice and destroy buffer:\n");
ulCommitType,
}
See Also
l EssUpdateEx
l EssUpdateFileEx
l EssUpdateUtf8Ex
665
EssUpdateFileASOEx
Sends an update specification to the active aggregate storage database from a file, capturing any
data load errors in ppMbrError.
Syntax
ESS_FUNC_M EssUpdateFileASOEx (hDestCtx, hSrcCtx, AppName, DbName, FileName, Store,
Unlock, ulBufferId, ppMbrError);
hSrcCtx ESS_HCTX_T API context handle for update file location. The update file can reside on the client
or on the same server as the target database.
stored.
Unlock ESS_BOOL_T Not supported for aggregate storage databases. You must always pass ESS_FALSE
for this parameter.
errors are:
[number].
Notes
specification.
Return Value
666
Access
database.
Example
void TestUpdateFileASOEx()
{
ESS_HCTX_T hSrcCtx;
ESS_BOOL_T isStore;
ESS_STR_T FileName;
ESS_ULONG_T ulSize;
ulSize = 1;
ulBufferId = 101;
/* Update from server*/

hSrcCtx = hCtx;
isStore = ESS_TRUE;
FileName = "apgeaso1.txt";
sts = EssUpdateFileASOEx (hCtx, hSrcCtx, AppName, DbName, FileName, isStore,

isUnlock, ulBufferId, &pMbrError);
printf("EssUpdateFileASOEx sts: %ld\n",sts);
if(!sts)
{
if(pMbrError)
else
}
ulBufferCnt = 1;
printf("\nIncrement to main slice and destroy buffer:\n");
667
ulCommitType,
if(!sts)
{
VerifyDataload("'Mar' 'Sale' 'Curr Year' 'Original Price' '017589' '13668'
'Cash' 'No Promotion' '1 to 13 Years' 'Under 20,000' 'Digital Cameras' 10\n 'Camcorders'
20\n 'Photo Printers' 30 !");
}
if(pMbrError)
}
See Also
l EssUpdateEx
l EssUpdateFileEx
l EssUpdateFileASO
l EssUpdateUtf8Ex
EssUpdateFileEx
Sends an update specification to the active database from a file, capturing any data load errors
in ppMbrError.
Syntax
ESS_FUNC_M EssUpdateFileEx (hDestCtx, hSrcCtx, AppName, DbName, FileName, Store, Unlock,
ppMbrError);
hDestCtx ESS_HCTX_T API context handle of the target database on the server.
stored.
668
errors are:
[number].
Notes
Return Value
Access
database.
Example
void TestUpdateFileEx()
{
ESS_HCTX_T hSrcCtx;
ESS_BOOL_T isStore;
ESS_STR_T FileName;
hSrcCtx = hCtx;
FileName = "apgebso1.txt";
isStore = ESS_TRUE;
sts = EssUpdateFileEx (hCtx, hSrcCtx, AppName, DbName, FileName, isStore, isUnlock,

&pMbrError);
printf("EssUpdateFileEx sts: %ld\n",sts);
669
if(!sts)
{
printf("\nVerify data:\n");
VerifyDataload("'Jan' 'New York' 'Actual' 'Sales' <IDESC '100'!");

if(pMbrError)
else
}
if(pMbrError)
}
See Also
l EssUpdateEx
l EssUpdateFileASO
l EssUpdateUtf8Ex
EssUpdateFileUTF8ASO
Sends an update specification to the active aggregate storage database from a UTF-8-encoded
file.
Syntax
ESS_FUNC_M EssUpdateFileUTF8ASO (hDestCtx, hSrcCtx, AppName, DbName,
FileName, Store, Unlock, ulBufferId);
hSrcCtx ESS_HCTX_T API context handle for update file location. The update file can reside on the client or on
the same server as the target database.
Unlock ESS_BOOL_T Not supported for aggregate storage databases. You must always pass ESS_FALSE for this
parameter.
670
Notes
If the Store flag is set to FALSE, the database performs only a syntax check of the update
specification.
Return Value
Access
database.
Example
See example for EssUpdateFileAso.
See Also
l EssUpdateFileASO
l EssUpdateFileASO
l EssUpdateFileEx
l EssUpdateUtf8Ex
EssUpdateFileUTF8ASOEx
Sends an update specification to the active aggregate storage database from a UTF-8-encoded
file, capturing any data load errors in ppMbrError.
Syntax
ESS_FUNC_M EssUpdateFileUTF8ASOEx (hDestCtx, hSrcCtx, AppName, DbName,
FileName, Store, Unlock, ulBufferId, ppMbrError);
stored.
Unlock ESS_BOOL_T Not supported for aggregate storage databases. You must always pass ESS_FALSE
for this parameter.
671
errors are:
[number].
Notes
specification.
Return Value
Access
database.
Example
See example for EssUpdateFileAso.
See Also
l EssUpdateEx
l EssUpdateFileEx
l EssUpdateFileASO
l EssUpdateUtf8Ex
EssUpdateFileUtf8Ex
Sends an update specification to the active database from a UTF-8-encoded file, capturing any
data load errors in ppMbrError.
672
Syntax
ESS_FUNC_M EssUpdateFileUtf8Ex (hDestCtx, hSrcCtx, AppName, DbName, FileName, Store,
Unlock, ppMbrError);
hDestCtx ESS_HCTX_T API context handle of the target databae on the server.
stored.
errors are:
l ESS_MBRERR_ERRORLOAD—Unable to do dataload at Item/Record
[number].
Notes
Return Value
Access
database.
673
See Also
l EssUpdateEx
l EssUpdateFileASO
l EssUpdateFileEx
l EssUpdateUtf8Ex
EssUpdateUtf8Ex
Sends an update specification to the active database as a single UTF-8-encoded string.
Syntax
ESS_FUNC_M EssUpdateUtf8Ex (hCtx, Store, Unlock, UpdtSpec, ppMbrError);
stored.
errors are:
l ESS_MBRERR_ERRORLOAD—Unable to do dataload at Item/Record
[number].
Notes
674
Return Value
Access
database.
See Also
l EssUpdateEx
l EssUpdateFileASO
l EssUpdateFileEx
EssValidateDB
Checks the database for data integrity.
Syntax
ESS_FUNC_M EssValidateDB (hCtx, DbName, FileName);
DbName ESS_STR_T Database name. Required, cannot be NULL.
FileName ESS_STR_T Error log file name, to be placed in the app\db directory on the server. Required.
Notes
l This function runs the validation checks to ensure the integrity of the database.
l Precede this call with a call to EssSetActive.
l This function is asynchronous, so you must continue to call EssGetProcessState until
the validation process is finished.
l This function validates the current database. You must select a database before calling this
function.
l This function checks for data integrity in each block. Reading from top to bottom, the
validation process goes through the entire database and checks blocks, sections, block type,
and block length, and checks for validity in floating point numbers.
l This function writes blocks and information about bad blocks to the log file.
l If this function finds integrity errors, it writes validation process error messages to a text-
format log file. The default location for the file is in the application\database directory; for
example: %ARBORPATH%\APP\DB\VALIDATE.LST
675
l The Essbase index contains an index for every data block. For every Read operation, this
function automatically compares the index key in the index page with the index key in the
corresponding data block and checks other header information in the block. If it encounters
a mismatch, this function displays an error message and continues processing until it has
checked the entire database.
Return Value
None.
Access
Example
ESS_VOID_T
ESS_ValidateDB (ESS_HCTX_T hCtx)
{
ESS_STR_T DbName;
ESS_STR_T FileName;
DbName = "Basic";
FileName =
"D:\\AnalyticServices\\app\\sample\\basic\\Validate.lst";
sts = EssValidateDB (hCtx, DbName, FileName);
if (!sts)
{
ESS_STATE_DONE))
}
}
See Also
l EssSetActive
EssValidateHCtx
Validates a specific API context handle (hCtx).
Syntax
ESS_FUNC_M EssValidateHCtx (hCtx);
676
hCtx ESS_HCTX_T The API context handle to validate.
Notes
This function can be used after any extended wait period to ensure the program's context handle
is still recognized by the server.
Return Value
This function returns 0 if the context handle is valid, otherwise it returns an error code to indicate
the invalid context handle. Possible reasons for an invalid context handle include the login might
have timed out or the user was explicitly logged out by the supervisor.
Access
This function requires no special access.
Example
#include <essapi.h>
char sApplication[] = "accept";

char sDbName[] = "basic";
char sFilename[] = "basic";
char SvrName[] = "local";
char User[] = "test";
char Password[] = "testing";
ESS_HINST_T hInst;
ESS_HCTX_T hCtx;
FILE *fpOutfile;
void ESS_Init()
{
ESS_STS_T sts;
ESS_INIT_T InitStruct = { ESS_API_VERSION, /* This should be set to ESS_API_VERSION
*/
NULL, /* void pointer to user's message
context */
0L, /* max number of context handles
required */
255, /* max size of buffer that can be
allocated*/
NULL, /* local path to use for file operations
*/
NULL, /* full path name of message database
file */
NULL, /* user-defined memory allocation
function */
NULL, /* user-defined memory reallocation
function*/
NULL, /* user-defined memory free function */
NULL, /* user-defined message callback
function */
NULL, /* user-defined help file path */
677
0L /* reserved for internal use */
};

{ fprintf(stdout, "EssInit failure: %ld\n", sts);
exit ((int) sts);
}
fprintf(stdout, "EssInit sts: %ld\n", sts);
}
void ESS_Login ()
{
ESS_USHORT_T Items;
sts = EssLogin (hInst, SvrName, User, Password, &Items, &pAppsDbs, &hCtx);

printf("EssLogin sts: %ld\r\n", sts);
}
void ESS_Term()
{
{
exit((ESS_USHORT_T) sts);
}
fprintf(stdout, "EssTerm sts: %ld\r\n", sts);
}
void ESS_Logout()
{
fprintf(stdout, "\n\nEssLogout sts: %ld\n",sts);
}
void ESS_SetActive()
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = sApplication;
DbName = sDbName;
fprintf(stdout, "EssSetActive sts: %ld\r\n",sts);
}
/*****************************************************/
/*************** MAIN FUNCTION ***********************/
void main(int argc, char ** argv)
{
ESS_STS_T sts;
ESS_Init();
ESS_Login();
ESS_SetActive();
678
/* Do something else, not related to Essbase*/
sts = EssValidateHCtx (hCtx);
if (sts) {
ESS_Login() ;
ESS_SetActive();
}
/* Do the actual processing now */
EssClearActive(hCtx);
ESS_Logout();
ESS_Term();
}
See Also
l EssLogin
l EssAutoLogin
l EssTerm
EssVerifyFilter
Verifies the syntax of a series of filter row strings against a specified database.
Syntax
ESS_FUNC_M EssVerifyFilter (hCtx, AppName, DbName);
Notes
Follow this call with successive calls to EssVerifyFilterRow to verify all rows for the filter.
Return Value
None.
Access
Example
ESS_VOID_T
ESS_VerifyFilter (ESS_HCTX_T hCtx)
{
ESS_STR_T AppName;
ESS_STR_T DbName;
679
ESS_USHORT_T ind;
AppName = "Sample";
DbName = "Basic";
/* Initialize Filter Row */
RowString[3] = "";
/* Verify Filter */
sts = EssVerifyFilter(hCtx, AppName, DbName);
/* Verify Count Filter Rows */
if(!sts)
{
sts = EssVerifyFilterRow(hCtx,
RowString[ind]);
}
}
See Also
l EssGetFilter
l EssVerifyFilterRow
EssVerifyFilterRow
Verifies the syntax of a single filter row strings against a specified database.
Syntax
ESS_FUNC_M EssVerifyFilterRow (hCtx, RowString);
RowString ESS_STR_T Filter row string.
Notes
This function should be called repeatedly after calling EssVerifyFilter, once for each row of
the filter, terminating the row list with a NULL row string pointer.
Return Value
None.
680
Access
Example
See the example of EssVerifyFilter.
See Also
l EssGetFilter
l EssVerifyFilter
EssVerifyFormula
Verifies the syntax of the specified formula. This function is called by
EssOtlVerifyFormula, which provides more information on returned errors.
Syntax
ESS_FUNC_M EssVerifyFormula (hCtx, FormulaName);
FormulaName ESS_STR_T The name of the formula to verify.
Notes
This function is not meant to be called directly. Instead, use the corresponding Outline API
function EssOtlVerifyFormula.
Return Value
This function returns zero if successful, otherwise it returns an error number.
See Also
l EssOtlVerifyOutline
l EssOtlVerifyOutlineEx
l EssOtlVerifyFormula
EssVerifyRulesFile
Verifies the syntax of the specified rules file.
Syntax
ESS_FUNC_M EssVerifyRulesFile (hCtx, ruleFileName, pNmColumns, ppColumnErrors);
681
ruleFileName ESS_STR_T The name of the rules file to verify.
pNmColumns ESS_PULONG_T Pointer to the number of columns in the rules file.
ppColumnErrors ESS_ULONG_T Pointer to the array of errors found.
Notes
l This function requires that a specific database be active; that is, EssSetActive() is required.
l This function is intended to be used after the rules file has been put on the server.
l There is one value in the array ppColumnErrors for each column in the rules file. The nth
value in the array corresponds to errors found for the nth column in the rules file. Each error
value may be zero or more of the following error codes combined with logical OR.
Error code Meaning
DAT_VERIFY_INVALIDMBR There is an unknown member (or no member) in the field name.
DAT_VERIFY_INVALIDHDR There is an unknown member in the header.
DAT_VERIFY_SAMENAME This field has the same field name as another field.
DAT_VERIFY_DIMUSED The dimension name is used in another field name or in the header.
DAT_VERIFY_MBRUSED A member name used as part of a combination in this field is used as a single member name in
the field name.
DAT_VERIFY_DIMINCROSSDIM A dimension name is used in a cross-dimensional reference in the field name.
DAT_VERIFY_DATAFIELD Only one field can have the Data Field attribute.
DAT_VERIFY_SIGNFLIPDIM The dimension used for Sign Flip checking is not in the associated outline.
DAT_VERIFY_DUPINHEADER This field name is also defined in the header definition.
DAT_VERIFY_DATEANDDATA A field may be designated a Data Field or Date Field, but not both.
DAT_VERIFY_DATEFIELDNAME The field name of a date field must be the name of a date dimension.
DAT_VERIFY_DATEFORMAT There is an unrecognized date format for this date column.
Return Value
If successful, returns the number of columns in the rules file as pNmColumns and the array of
errors found in ppColumnErrors.
Access
682
Example
{
ESS_ULONG_T numColumns = 0, i;
ESS_PULONG_T pColumnErrors = NULL;
sts = EssVerifyRulesFile(hCtx, "rule_file", &numColumns, &pColumnErrors);

if(!sts)
{
if(numColumns && pColumnErrors)
{
printf("NumColumns: %d\n", numColumns);
for(i=0; i<numColumns; i++)
{
printf("Column[%d]:\n", i+1);
if( pColumnErrors[i] == 0 )
printf(" No error\n");
else
{
if( pColumnErrors[i] & DAT_VERIFY_INVALIDMBR )
printf(" There is an unknown member (or no member) in the field
name.\n");
if( pColumnErrors[i] & DAT_VERIFY_INVALIDHDR )
printf(" There is an unknown member in the header.\n");
if( pColumnErrors[i] & DAT_VERIFY_SAMENAME )
printf(" This field has the same field name as another field.\n");
if( pColumnErrors[i] & DAT_VERIFY_DIMUSED )
printf(" The dimension name is used in another field name or in
the header.\n");
if( pColumnErrors[i] & DAT_VERIFY_MBRUSED )
printf(" A member name used as part of a combination in this field
is used as a single
member name in another field.\n");
if( pColumnErrors[i] & DAT_VERIFY_DIMINCROSSDIM )
printf(" A dimension name is used in a cross-dimensional reference
in the field name.\n");
if( pColumnErrors[i] & DAT_VERIFY_DATAFIELD )
printf(" Only one field can have the Data Field attribute.\n");
if( pColumnErrors[i] & DAT_VERIFY_SIGNFLIPDIM )
printf(" The dimension used for Sign Flip checking is not in the
associated outline.\n");
if( pColumnErrors[i] & DAT_VERIFY_DUPINHEADER )
printf(" This field name is also defined in the header definition.
\n");
if( pColumnErrors[i] & DAT_VERIFY_DATEANDDATA )
printf(" A field may be designated a Data Field or a Date Field,
but not both.\n");
if( pColumnErrors[i] & DAT_VERIFY_DATEFIELDNAME )
printf(" The field name of a date field must be the name of a date
dimension.\n");
if( pColumnErrors[i] & DAT_VERIFY_DATEFORMAT )
printf(" There is an unrecognized date format for this date column.
\n");
}
}
EssFree(hInst, pColumnErrors);
}
683
}
}
See Also
l EssVerifyFormula
EssWriteToLogFile
Writes a message to the Essbase Server log file (essbase.log), or to the application log file
(appname.log).
Syntax
ESS_FUNC_M EssWriteToLogFile (hCtx, AgentLog, Message);
AgentLog ESS_BOOL_T If TRUE, message is written to the Essbase Server log file, essbase.log. If FALSE,
message is written to the application log file, appname.log.
Message ESS_STR_T Message to be logged to the Essbase Server log file (essbase.log), or to the application
log file (appname.log).
Notes
Return Value
Access
The caller must have supervisor privilege (ESS_ACCESS_SUPER) for the specified application.
Example
ESS_FUNC_M ESS_WriteToLogFile (ESS_HCTX_T hCtx)
{
ESS_STR_T Message = NULL;
Message = "Received login request";
/*
* Writes the message (Received login request) to the Agent log file.
*/
sts = EssWriteToLogFile(hCtx, ESS_TRUE, Message);
684
return(sts);
}
See Also
l EssDeleteLogFile
l EssGetLogFile
l EssLogSize
685
686
Part III
C Outline API
In C Outline API:
l Using the C Outline API

l C Outline API Declarations
l C Outline API Functions
l C Outline API Examples
687
688
Using the C Outline API
9
In This Chapter
C Outline API Overview .................................................................................. 689
C Outline API Error Handling ............................................................................ 689
C Outline API Server Outline Queries................................................................... 690
C Outline API Outline Verification....................................................................... 690
C Outline API Memory Allocation ....................................................................... 691
C Outline API Security Requirements................................................................... 691
C Outline API Function Call Sequence ................................................................. 692
Typical C Outline API Task Sequence .................................................................. 692
C Outline API Overview

The Outline API is a set of functions for creating, maintaining, and manipulating Essbase outlines
from within a custom application. With the Outline API, you have the same ability to manipulate
database outlines from within code as you have using the Outline Editor in Administration
Services.
The Outline API is an important part of the Essbase API.
The Outline API is used in conjunction with the Essbase API and requires a server connection.
C Outline API Error Handling

Outline API functions return 0 when they succeed; if they fail, they return an error status value
as defined in esserror.h.
Functions of the main API use the error message callback routine and pass an error number to
the message handler. The handler uses the essbase.mdb message database to determine the
error message and display an error message to the user.
Outline API functions do not ordinarily use the error message callback routine when returning
an error status. The error callback routine is called in the following situations:
l If you call functions that use the network (EssOtlOpenOutline, EssOtlWriteOutline, and
EssOtlRestructure), and they incur errors on non-outline related actions.
l If a NULL is found during routine checking when passed into the Outline API, and
API_NULL_ARG is returned.
689
l If a bad outline handle (HOUTLINE) is passed into any call requiring an outline handle,
and OTLAPI_BAD_HOUTLINE is returned.
C Outline API Server Outline Queries

Several functions support a query interface to the outline API such that the outline does not
need to be downloaded from the server and completely read into memory. These Outline API
functions support only server outlines. Prior to opening the outline, the user must log in to a
server, setting up a valid Essbase login context.
Error handling for these functions is done via the standard API error handling mechanism.
Therefore, any message callback that the caller has specified from EssInit is called on errors.
Here is the process flow:
1. Initialize the API as always by calling EssInit and EssLogin.
2. Call EssOtlOpenOutlineQuery to "open" the outline from the server. Although this
returns an outline handle, it does not open the entire outline.
3. To get information about members, call EssOtlQueryMembers with the appropriate flags
to get an array of member handles back. That call returns all relevant information in the
ESS_HMEMBER_T member handle. You can then call any of the EssOtlGetXxxx calls that
relate to a specific member by passing in one of the returned member handles. In particular,
the EssOtlGetXxxx queries the handle locally; a call to the server is not necessary. See the
comments section in the EssOtlQueryMembers call for more information about which
calls are supported when the outline is opened in "query" mode.
4. When you are finished with the data returned from an EssOtlQueryMembers call, you
should call EssOtlFreeMembers to free the array of members.
5. When complete, call EssOtlCloseOutline to clean up internal data structures.
6. Terminate the API as always by calling EssLogout and EssTerm.
C Outline API Outline Verification

The Outline API is designed to prevent the caller from creating an illegal outline. To check the
outline, use the EssOtlVerifyOutline function to verify it before saving it to the server. The
Outline API calls this function automatically when an outline is written to the server, if it was
not called previously.
Each function call in the Outline API verifies that processing by the caller does not result in an
illegal outline. For example, EssOtlRenameMember checks a new member name to make sure
that it is valid and does not already exist in the outline. Here are a few exceptions to this automatic
validation:
l EssOtlOpenOutline allows the caller to read in a previously created outline that is illegal.
This outline could be illegal because the Outline Editor in Administration Services allows
you to save an invalid outline to a local file. Any existing errors are detected when
690
EssOtlVerifyOutline is called. Also, some individual operations are illegal during
processing if the outline starts out as illegal.
l EssOtlDeleteMember and EssOtlDeleteDimension do not check for any alias
combinations that contain a deleted member. EssOtlVerifyOutline detects this
condition.
l EssOtlSetMemberFormula allows you to enter an illegal formula, and
EssOtlVerifyOutline does not check member formulas. An illegal member formula causes
failure during restructure. EssGetProcessState displays the error message returned from
the server.
C Outline API Memory Allocation

The Essbase API provides a set of memory management functions, EssAlloc, EssRealloc,
and EssFree. These functions, plus all internal API memory allocations, call memory allocation
routines pointed to by the AllocFunc, ReallocFunc, and FreeFunc fields of the
ESS_INIT_T initialization structure.
If you are using your own custom memory allocation functions, make sure your memory
allocation scheme can handle allocating many small memory buffers.
C Outline API Security Requirements

Because you can use the Outline API to create, edit, and delete outlines, you must be aware of
some security issues when creating an application that uses the Outline API. These issues impact
only programs that create, edit, or save outlines during a session.
To manipulate outlines through the Outline Editor in Administration Services, you must have
Application Manager or higher privileges. You also need these privileges to use a program that
uses the Outline API during execution. If you do not have these privileges, Outline API calls that
read or write outlines from the server do not work. See the Oracle Essbase Database
Administrator's Guide for more detailed information on security and privilege levels.
For example, you are writing a new EIS end-user application that allows your users to explore
a number of "what-if" situations during a session. To do this, the program dynamically creates
a number of Essbase databases during a session. These databases (and their outlines) are
temporary and are not saved after the session terminates. You can approach this situation in
several ways:
l If you want the user to be able to create an application and multiple databases during a
session, give the user the Create/Delete Application privilege. This privilege must be assigned
by an Essbase administrator prior to running the program. This is a relatively high privilege
level in Essbase, but if the user does not have access to other programs, there is little impact
on the overall system security.
l If you do not need multiple databases available at the same time, you can have the Essbase
administrator create a temporary application and database during the installation of your
691
program. The program itself manipulates the temporary database without having to create
a new database for each "what-if" situation.
With the second approach, a user requires only the lower and more restricted Database Manager
privilege. You could have the Essbase administrator set up a special group with Database
Manager privilege only for your temporary application and database. Users can be assigned to
that group. The users would revert to ordinary user privilege for any other access to the system.
This approach offers less security exposure, but does require more set up prior to running your
program.
C Outline API Function Call Sequence

When you use the Outline API, your program must call some API functions before others. Follow
this basic call sequence:
1. Call EssInit before any other API function.
The API returns an instance handle.
2. Call EssLogin, EssLoginAs, EssLoginEx, EssLoginExAs, or EssAutoLogin to log on
to the server.
The API returns a context handle.
3. Call EssOtlOpenOutline, EssOtlOpenOutlineEx, or EssOtlNewOutline to open or
create an outline.
The API returns an outline handle.
4. Call EssOtlWriteOutline or EssOtlWriteOutlineEx to write the current outline to
the server.EssOtlVerifyOutline is called automatically by the API before the outline is
saved, unless you call it before this.
5. Call EssOtlRestructure to restructure the database based on the changes made to the
outline.
6. Call EssUnlockObject to unlock the outline artifact if it is locked when the outline is
opened.
7. Call EssOtlCloseOutline to free resources associated with the outline.
8. Call EssLogout to log off the server.
This invalidates the context handle.
9. Call EssTerm to end the session.
This invalidates the instance handle.
Typical C Outline API Task Sequence

This is a typical order of operations for a simple Outline API application.
1. Create and initialize an ESS_INIT_T structure.
692
2. Initialize the Outline API by calling EssInit.
3. Allocate any local static or global structures.
4. Log on to the required server by calling EssLogin, EssLoginAs, EssLoginEx,
EssLoginExAs, or EssAutoLogin.
5. Create and initialize an ESS_OUTLINEINFO_T structure (only for a new outline).
6. Open an existing outline or create a new outline by calling EssOtlOpenOutline,
EssOtlOpenOutlineEx, or EssOtlNewOutline.
7. Work on the outline.
8. Verify the outline by calling EssOtlVerifyOutline or EssOtlVerifyOutlineEx.
9. Write the verified outline to the server by calling EssOtlWriteOutline or
EssOtlWriteOutlineEx.
The outline is saved with an .OTN extension.

10. Restructure the database by calling EssOtlRestructure.
The .OTN file is changed to an .OTL file. This is an asynchronous function call; therefore,
you should call EssGetProcessState until the process is complete.
11. Unlock the outline (if it was locked on opening) by calling EssUnlockObject.
12. Free all information associated with the outline by calling EssOtlCloseOutline.
13. Log off the server by calling EssLogout.
14. Free any local static or global structures.
15. Terminate the API by calling EssTerm.
693
694
C Outline API Declarations
10
In This Chapter
C Outline API Error Return Values ...................................................................... 695
C Outline API DTS Member Structures ................................................................. 701
C Outline API Symbolic Constant Definitions.......................................................... 702
ESS_ATTRIBUTEQUERY_T................................................................................ 707
ESS_GENLEVELNAME_T................................................................................. 708
ESS_GENLEVELNAMEEX_T .............................................................................. 708
ESS_MBRCOUNTS_T .................................................................................... 709
ESS_MBRINFO_T ........................................................................................ 709
ESS_OTLQUERYERRORLIST_T........................................................................... 713
ESS_OUTERROR_T....................................................................................... 713
ESS_OUTLINEINFO_T .................................................................................... 716
ESS_OUTLINEINFOEX_T ................................................................................. 717
ESS_PERSPECTIVE_T .................................................................................... 718
ESS_PREDICATE_T....................................................................................... 719
ESS_SVROTLINFO_T ..................................................................................... 720
ESS_VALIDITYSET_T ..................................................................................... 720
C Outline API Error Return Values

Table 7 describes the error status constants returned when an Outline API call fails. These values
are defined in the Outline API C language header file esserror.h.
For a more complete list, see esserror.h.
Table 7 C Outline API Error Return Values
Value Description
OTLAPI_BAD_ALIASTABLE Illegal alias table
OTLAPI_BAD_CONSOL Invalid consolidation type (+,-,etc.)
OTLAPI_BAD_GENLEVELNAME Invalid generation or level name
OTLAPI_BAD_HOUTLINE Invalid outline handle passed to EssOtl... function
OTLAPI_BAD_MBRNAME Invalid member name
695
Value Description
OTLAPI_BAD_MEMBER Invalid member handle
OTLAPI_BAD_MOVE Illegal move of member. Can't move member to its descendant.
OTLAPI_BAD_OBJTYPE Illegal object type
OTLAPI_BAD_OUTLINETYPE Invalid outline type
OTLAPI_BAD_PERSPECTIVE2 Invalid perspective
OTLAPI_BAD_RENAMESHARE A shared member cannot be renamed
OTLAPI_BAD_RESTRUCTTYPE Invalid restructure type
OTLAPI_BAD_SCA_VALIDITYSET_TYPE Perspectives/validity sets do not support this validity set type
OTLAPI_BAD_SMARTLISTNAME Invalid text list name
OTLAPI_BAD_SORT COMPAREFUNC Invalid sorting compare function
OTLAPI_BAD_SORTTYPE Invalid sort type
OTLAPI_BAD_TRANSTYPE Unknown transaction type when creating a transaction (internal error)
OTLAPI_BAD_USERATTR Invalid user attribute
OTLAPI_CUR_NOACCOUNTS There is no Accounts dimension. You need an Accounts dimension to create

a currency database.
OTLAPI_CUR_NOCOUNTRY There is no Country dimension. You need a Country dimension to create a

currency database.
OTLAPI_CUR_NOTIME There is no Time dimension. You need a Time dimension to create a currency
database.
OTLAPI_ERR_ADDDELETEDIMDYNAMICCALC Member in which to store data is type Dynamic Calc
OTLAPI_ERR_ADDNAMEUSED Member name already used (add operation)
OTLAPI_ERR_ALIASTABLEEXISTS Alias table already exists
OTLAPI_ERR_ALIASLANGUAGE_UNAVAILABLE Alias table languages are unavailable for outline versions before 11.1.2.0.
00.
OTLAPI_ERR_ALIASTABLENAME Illegal alias table name
OTLAPI_ERR_ALREADY CURRENCY The outline is a currency outline. You are trying to create a currency outline,
and the initial outline is already a currency outline.
OUTAPI_ERR_ASO_COMPRESSIONMUSTBEDYNAMIC Aggregate storage outlines require compression dimension to be a single

dynamic hierarchy
OUTAPI_ERR_ASO_DIFFERENTNUMBEROFSHARES This prototype should have same number of shared members as its previous
sibling
696
Value Description
OUTAPI_ERR_ASO_SHAREDMEMBERSNOTINSAMEORDER This prototype must have each of its shared members as next sibling to its
previous sibling's shared members
OTLAPI_ERR_ATTR_ATTACHED_WRONGLEVEL This attribute is attached at wrong level at least once
OTLAPI_ERR_ATTRMBR_ALREADYASSOCIATED Base member already associated with an attribute member from the same
dimension
OTLAPI_ERR_BADDIM Invalid dimension argument
OTLAPI_ERR_BADHIER Invalid hierarchy type
OTLAPI_ERR_BADHIER_TOP Invalid hierarchy member designation - Member must be at generation 1 or

2
OTLAPI_ERR_BADSHARE Illegal share value
OTLAPI_ERR_BADSKIP Illegal time balance skip value
OTLAPI_ERR_BADSTORAGE Illegal dimension storage value
OTLAPI_ERR_BADSTORAGECATEGORY Illegal storage category
OTLAPI_ERR_BADTIMEBAL Illegal time balance value
OTLAPI_ERR_BSO_SOLVEORDER Block storage outlines that have not been enabled for member types cannot
have a solve order
OTLAPI_ERR_CANTIDENTIFYMBR_DUPLICATEDNAME Cannot uniquely identify a member because the name is duplicated
OTLAPI_ERR_CNTS_INDEP_LAST Independent dimension list must be ordered with continuous independent

dimensions last
OTLAPI_ERR_CONFIGTOOMANYDIMS Too many dimensions to configure automatically
OTLAPI_ERR_COPYALIASTABLE Source and destination tables are the same
OTLAPI_ERR_CREATETEMP Cannot create temporary file name. You are probably trying to create it on a
read-only drive. We create a temporary file on the client every time you open
or write an outline from/to the server.
OTLAPI_ERR_CURTOOMANYDIMS Too many dimensions in a currency outline. A currency outline is limited to

four dimensions.
OTLAPI_ERR_DELETEDEFALIAS Cannot delete the default alias table
OTLAPI_ERR_DISCRETE_DIFFERENT An independent range must have the same discrete start and end members
OTLAPI_ERR_DISCRETE_OR_CNTS Independent dimension types must be either discrete or continuous
OTLAPI_ERR_DUP_LANGCODE The language code is assigned to another alias table within the same
database
OTLAPI_ERR_DUPLICATEALIAS Duplicate alias
OTLAPI_ERR_DUPLICATENAME Duplicate member name
697
Value Description
OTLAPI_ERR_DUPGENLEVNAME Cannot add, rename, or set a member name or alias that duplicates a
generation or level name
OTLAPI_ERR_EXPORT_INCORRECT_FLAGS There are invalid export flags. Export cannot be enabled to limit extraction to
the tree and alias table
OTLAPI_ERR_EXPORT_INVALID_ALIASTABLE An invalid alias table is specified in the export options
OTLAPI_ERR_EXPORT_INVALID_DIMLIST The number of dimensions or the dimension list specified in the export options
is invalid
OTLAPI_ERR_EXPORT_INVALIDDIM_DIMLIST The dimension name specified in the export options dimension list is invalid
OTLAPI_ERR_EXPORT_INVALID_VERSION This export version is invalid. Enter a valid export version
OTLAPI_ERR_EXPORT_UNABLE_FILE Cannot open the file to export the outline
OTLAPI_ERR_EXPORT_UNABLE_PROCESS Cannot process the outline because of unsupported outline type
OTLAPI_ERR_FAILED_GET_ALIASNAMES Failed to get all alias names due to failed alias identifier lookup
OTLAPI_ERR_FEATURE_UNAVAILABLE The feature is unavailable in this outline version; please migrate outline first
OTLAPI_ERR_FILEIO Could not read from or write to file
OTLAPI_ERR_FILEOPEN Could not open file
OTLAPI_ERR_FORMATSTRING_MISMATCH Implied share or label-only member has a different format string than the
original member; original member's format string will be applied
OTLAPI_ERR_FORMATSTRING_NOT_MEMBTYPE_ENABLED The use of format strings require the outline to be member-type enabled. This
outline is not member type enabled
OTLAPI_ERR_FORMATSTRINGTOOLONG Format String too long for single locale configuration
OTLAPI_ERR_FUNCTION_OBSOLETE Function is obsolete
OTLAPI_ERR_GENLEVELEXISTS Generation or level already has a name
OTLAPI_ERR_GENLEVELNAMEEXISTS Generation or level name already exists
OTLAPI_ERR_GENLEVELVALUE Illegal generation or level value
OTLAPI_ERR_GENLEVNAMEMBR Cannot add a generation or level name that duplicates a member name or
alias
OTLAPI_ERR_ILLEGALALIAS STRING Illegal member combinational for alias
OTLAPI_ERR_ILLEGALCOMBOALIAS Illegal combinational alias name
OTLAPI_ERR_ILLEGALCURRENCY Illegal currency member
OTLAPI_ERR_ILLEGALDEFALIAS Illegal default alias name
OTLAPI_ERR_ILLEGALNAME Illegal member name
698
Value Description
OTLAPI_ERR_ILLEGALTAG Illegal dimension tag (category)
OTLAPI_ERR_ILLEGALOPTION Occurs when the user passes in an invalid option to EssOtlGetGenNames or

EssOtlGetLevelNames
OTLAPI_ERR_IMPLIED_SHARE_OLD_VERSION The outline version is too old to set Implied Share
OTLAPI_ERR_INCORRECT_MEMBERTYPE Member type can be only set to numeric or date types
OTLAPI_ERR_INVALID_SMARTLIST_HANDLE Invalid text list handle
OTLAPI_ERR_INVALID_SMARTLIST_IMPORTFILE Input file for importing text lists is invalid
OTLAPI_ERR_INVALIDID_SMARTLIST_IMPORTFILE Invalid or duplicate ID in text list import file
OTLAPI_ERR_LANGCODE_TOOLONG Alias table language code exceeds the maximum length
OTLAPI_ERR_LEAFLABEL Leaf member defined as a label member
OTLAPI_ERR_MAXALIASTABLES Maximum number of alias tables has been reached
OTLAPI_ERR_MEMBERCALC Illegal member formula
OTLAPI_ERR_MEMBERTYPE_OFF Cannot turn off the member type enabled setting of an outline
OTLAPI_ERR_MBRCOMMENTEXLEN Extended member comment is too long
OTLAPI_ERR_MISSINGTEXT_SMARTLIST_IMPORTFILE Missing text for ID in text list import file
OTLAPI_ERR_MULT_DATE_DIMS An outline can have at most one dimension with date types on static members
OTLAPI_ERR_MULTIHIER_NOT_ENABLED Cannot set hierarchy type; multiple hierarchies not enabled for dimension
OTLAPI_ERR_MULT_SMARTLIST_DIMS An outline can have at most one dimension with smartlists on static members
OTLAPI_ERR_MUSTSAVE_BEFORE_EDIT The outline must be saved and re-opened before it can be edited
OTLAPI_ERR_NOALIAS No alias for this member
OTLAPI_ERR_NOALIASCODE Get/Set alias table language code is not yet implemented
OTLAPI_ERR_NOALIASCOMBO No alias combination
OTLAPI_ERR_NOATTRONCOMPRESSEDDIM Attributes are not allowed on the compressed dimension
OTLAPI_ERR_NOFORMULA No formula for this member
OUTAPI_ERR_NOMEMBTYPE This outline version does not support typed members
OTLAPI_ERR_NOSHAREPROTO Shared member with no actual member
OUTAPI_ERR_NOSMARTLISTS This outline version does not support text lists
OTLAPI_ERR_NOTADIM Dimension name expected
OTLAPI_ERR_NOT_A_TIME_MBR Invalid argument passed. Not a date-time dimension member
699
Value Description
OTLAPI_ERR_NOT_LINKEDATTRIBUTEDIM Not a linked attribute dimension handle
OTLAPI_ERR_NOT_MEMBTYPE_ENABLED This outline is not member type enabled
OTLAPI_ERR_NOTIMEDIM No time dimension defined (can't do time balance operations without a time
dimension)
OTLAPI_ERR_NOTVERIFIED Outline has errors (when saving to the server)
OTLAPI_ERR_OBJ_NOTFOUND Object not found
OTLAPI_ERR_OBJTYPE_NOTSUPPORTED Function not supported in server side edit mode
OTLAPI_ERR_OPENMODE File was opened in the wrong mode to make this call. If you call
EssOtlOpenOutlineQueryto open the outline, not all of the calls
will work.
OTLAPI_ERR_OTLDATEFORMAT Invalid outline property: date format
OTLAPI_ERR_OTLSHARED_FORMAT Outline member's format string cannot be set for shared members
OTLAPI_ERR_OTLSHARED_TYPE Outline member's type cannot be set for shared members
OTLAPI_ERR_QUERYHINT_INVALIDARRAYSIZE Invalid query hint array size
OTLAPI_ERR_RENAMEDEFALIAS Cannot rename the default alias table
OTLAPI_ERR_RENAMENAMEUSED Member name already used (rename operation)
OTLAPI_ERR_SCA_NOT_ENABLED This outline is not enabled for varying attributes
OTLAPI_ERR_SCA_UNAVAILABLE Varying attributes feature is unavailable in this version
OTLAPI_ERR_SHAREDMEMBERFORMULA Shared member cannot have a formula
OTLAPI_ERR_SHARENOTLEVEL0 Shared member not at level 0 (a shared member cannot be a parent of

another member)
OTLAPI_ERR_SHAREUDA Cannot set a user attribute for a shared member
OTLAPI_ERR_SMARTLISTNAMEUSED Cannot add text list; text list name already used
OTLAPI_ERR_SMARTLIST_MAPMAXREACHED Cannot add more than n text list texts to id mappings
OTLAPI_ERR_SMARTLISTMAXREACHED Cannot add text list; n maximum text lists supported
OTLAPI_ERR_SMARTLIST_MISSING Missing text list association for text-typed member
OTLAPI_ERR_TBTAGS_WITH_DYN_HIERARCHY This member has a TB-Tag. That requires TIME dimension to only have STORED
hierarchies
OTLAPI_ERR_TIMESPARSE Accounts dimension is dense and time dimension sparse-is not used
OTLAPI_ERR_TYPED_ATTR_LEVEL0 Attribute members and non level-0 aggregate storage members cannot be
set to Date or Text type
700
Value Description
OTLAPI_ERR_TYPED_DIMS Text typed members, date typed members, and stored members with format
strings should be specified along the same dimension
OTLAPI_ERR_UNKNOWNDTSMBR Unknown DTS member
OTLAPI_ERR_VALIDITYSET_MATCH The validity set must match an existing set in the outline
OTLAPI_ERR_VIRTLEV0NOFORMULA Dynamic Calc members must have formulas or children, or else they cannot
be calculated
OTLAPI_ERR_VIRTBADPARENT When a single child member is Dynamic Calc or Dynamic Calc and Store, the
parent must also be Dynamic Calc or Dynamic Calc and Store
OTLAPI_ERR_VIRTTOOMANYCHILDREN Dynamic Calc member has more than 100 children
OTLAPI_FAILED_ASSIGN_DEFAULTGENNAMES Failed to set time related generation names for the date-time dimension
created
OTLAPI_ILLEGAL_SCA_TYPE_2 Varying attribute outlines do not allow duplicate names, and cannot be a
currency outline
OTLAPI_INVALID_ARG Invalid argument passed to ESSOTL function
OTLAPI_INVALID_QUERYID Invalid query id argument passed
OTLAPI_INVALID_QUERY_OPTIONS Invalid query options passed. Will be ignored
OTLAPI_NO_GENLEVELNAME Cannot find generation or level name
OTLAPI_NO_USERATTR Cannot find user attribute
OTLAPI_NULL_ARG NULL argument passed to EssOtl... function
OTLAPI_OUTLINE_TOO_NEW Outline is of a newer version than this program can understand
OTLAPI_SORT_TOOMANY Too many members to sort (64K / 4 members is the maximum sorting
capacity)
OTLAPI_SMARTLIST_ASSOC_EXISTS Cannot delete a text list with existing associations
OTLAPI_SMARTLIST_DUP_IDORNAME Duplicate text list element ID or name
OTLAPI_SMARTLIST_INVALID_TEXT Invalid text list text
OTLAPI_WRONG_INDEPDIM_NM The number of independent dimensions given in perspective does not match
the outline
C Outline API DTS Member Structures

These structures contain information about Dynamic Time Series (DTS) members.
/*
ESS_DTSMBRNAME_T, ESS_PDTSMBRNAME_T
DTS member name structure
701
*/
ESS_TSA_ARRAY_API_typedef(char, ESS_DTSMBRNAME_T, ESS_MBRNAMELEN);
ESS_TSA_API_typedef (ESS_DTSMBRNAME_T *, ESS_PDTSMBRNAME_T);
ESS_TSA_API_typedef (ESS_PDTSMBRNAME_T *, ESS_PPDTSMBRNAME_T);
ESS_DTSMBRNAME_T szDTSMember The name of the DTS member.
ESS_MBRNAMELEN szName The length of the DTS member name.
/*
ESS_DTSMBRINFO_T, ESS_PDTSMBRINFO_T
DTS member info structure
*/
ESS_TSA_API_typedef_struct(ess_dtsmbrinfo_t)
{
ESS_TSA_ELEMENT(ESS_DTSMBRNAME_T, szDTSMember);
ESS_TSA_ELEMENT(ESS_USHORT_T, usGen);
} ESS_TSA_END(ESS_DTSMBRINFO_T);
ESS_TSA_API_typedef(ESS_DTSMBRINFO_T *, ESS_PDTSMBRINFO_T);
ESS_TSA_API_typedef(ESS_DTSMBRINFO_T **, ESS_PPDTSMBRINFO_T);
ESS_DTSMBRNAME_T szDTSMember The name of the DTS member.
ESS_USHORT_T usGen The generation number of the DTS member.
C Outline API Symbolic Constant Definitions

This section describes the symbolic constants used by the Outline API. These constants are
defined in the Essbase Outline API C language header file essotl.h:
l “Account Member Currency Conversion Category Values” on page 703
l “Account Member Time Balance Skip Values” on page 703
l “Account Member Time Balance Values” on page 703
l “Dimension Categories” on page 703
l “Dimension Categories (Tags)” on page 704
l “Generation and Level Options” on page 705
l “Query Types” on page 705
l “Query Options” on page 705
l “Restructure Values” on page 706
l “Share Constants” on page 706
l “Sorting Options” on page 707
702
Account Member Currency Conversion Category Values
Value Description
ESS_CONV_NONE Default conversion category. Member inherits category from parent.
ESS_CONV_CATEGORY Define a Currency Conversion category for this member
ESS_CONV_NOCONV No conversion for this member
Account Member Time Balance Skip Values

Only valid if time balance is not ESS_TIMEBAL_NONE.
Value Description
ESS_SKIP_NONE Don't skip anything
ESS_SKIP_MISSING Skip the value if the data is #missing
ESS_SKIP_ZEROS Skip the value if the data is 0
ESS_SKIP_BOTH Skip the value if the data is #missing or 0
Account Member Time Balance Values

Value Description
ESS_TIMEBAL_NONE No time balance
ESS_TIMEBAL_FIRST First time balance member
ESS_TIMEBAL_LAST Last time balance member
ESS_TIMEBAL_AVG Average time balance member
Dimension Categories
Used for optimizing storage when using storage auto-configure
Value Description
ESS_STORECAT_ACCOUNTS Accounts storage category
ESS_STORECAT_ATTRCALC Attribute calculation (aggregation) storage category
ESS_STORECAT_ATTRIBUTE Attribute storage category
ESS_STORECAT_BUSUNIT Business Unit storage category
703
Value Description
ESS_STORECAT_CUSTOMER Customer storage category
ESS_STORECAT_DIST Distribution Channel storage category
ESS_STORECAT_GEOG Geographical Location storage category
ESS_STORECAT_MARKET Market storage category
ESS_STORECAT_ORGAN Organization storage category
ESS_STORECAT_OTHER None or don't know storage category
ESS_STORECAT_PRODUCT Product storage category
ESS_STORECAT_SCENARIO Scenario storage category
ESS_STORECAT_TIME Time storage category
ESS_STORECAT_UNITS Units storage category
Dimension Categories (Tags)
Value Description
ESS_CAT_ACCOUNTS Accounts dimension
ESS_CAT_ATTRCALC Attribute calculation dimension or member. Used internally for aggregation.
ESS_CAT_ATTRIBUTE Attribute dimension or member
ESS_CAT_COUNTRY Country dimension
ESS_CAT_CURPARTITION Currency partition dimension. Valid only in non-currency databases.
ESS_CAT_NONE No category
ESS_CAT_TIME Time dimension
ESS_CAT_TYPE Type dimension. Valid only in currency databases.
Member Types
Value Description
ESS_MEMBERTYPE_NONE No type
ESS_MEMBERTYPE_NUMERIC Numeric type
ESS_MEMBERTYPE_SMARTLIST Text List (SmartList) type
704
Value Description
ESS_MEMBERTYPE_DATE Date type
Generation and Level Options

You can use with EssOtlGetGenNames() and EssOtlGetLevelNames()
Value Description
ESS_GENLEV_ALL Returns default and user-defined names
ESS_GENLEV_ACTUAL Returns only names that are user-defined
ESS_GENLEV_DEFAULT Returns all default names, including the default names for generations and levels that also have user-defined
names
ESS_GENLEV_NOACTUAL Returns all default names, excluding the default names for generations and levels that also have user-defined
names
Query Options
You can specify for certain query types in “ESS_PREDICATE_T” on page 719
Value Description
ESS_MEMBERSONLY Valid for ESS_SEARCH, ESS_WILDSEARCH
ESS_ALIASESONLY Valid for ESS_SEARCH, ESS_WILDSEARCH
ESS_MEMBERSANDALIASES Valid for ESS_SEARCH, ESS_WILDSEARCH
ESS_COUNTONLY Valid for any query type. Queries the outline without returning any data. Returns a count of how many
members meet the query type by filling in the ulTotalCount field in “ESS_MBRCOUNTS_T” on page
709.
Query Types
Used for defining the operation to perform in “ESS_PREDICATE_T” on page 719:
l ESS_CHILDREN
l ESS_DESCENDANTS
l ESS_BOTTOMLEVEL
l ESS_SIBLINGS
l ESS_SAMELEVEL
l ESS_SAMEGENERATION
l ESS_PARENT
705
l ESS_DIMENSION
l ESS_NAMEDGENERATION
l ESS_NAMEDLEVEL
l ESS_SEARCH
l ESS_WILDSEARCH
l ESS_USERATTRIBUTE
l ESS_ANCESTORS
l ESS_DTSMEMBERS
l ESS_DIMUSERATTRIBUTES
l ESS_INDEPDIMS
l ESS_SIBLINGS65
l ESS_INDEPDIMS_DISCRETE
l ESS_INDEPDIMS_CONTINUOUS
Restructure Values
Value Description
ESS_DOR_ALLDATA Keep all data
ESS_DOR_NODATA Discard all data
ESS_DOR_LOWDATA Keep only level 0 data
ESS_DOR_INDATA Keep only input data
ESS_DOR_FORCE_ALLDATA Reload all data
Share Constants
Value Description
ESS_SHARE_DYNCALCNOSTORE Shared member. A member tagged as no Dynamic Calc and Store.
ESS_SHARE_DYNCALCSTORE Shared member. A member tagged as Dynamic Calc and Store.
ESS_SHARE_DATA Normal member (default value)
ESS_SHARE_LABEL Label member. Do not store data for this member.
ESS_SHARE_NEVER Never share this member, even if it would normally be an implicit share.
ESS_SHARE_SHARE Shared member. This member cannot have children and must have the actual member with the same
name in the same dimension.
706
Sorting Options
Value Description
ESS_SORT_ASCENDING Sort in ascending order
ESS_SORT_DESCENDING Sort in descending order
ESS_SORT_USERDEFINED User supplies a custom sorting routine
ESS_ATTRIBUTEQUERY_T
Used by EssOtlQueryAttributes for complex queries concerning attributes.
typedef struct ESS_ATTRIBUTEQUERY_T
{
ESS_BOOL_T bInputMemberIsHandle;
union
{
ESS_HMEMBER_T hMember;
ESS_STR_T szMember;
} uInputMember;
ESS_USHORT_T usInputMemberType ;
ESS_USHORT_T usOutputMemberType;
ESS_USHORT_T usOperation;
} ESS_ATTRIBUTEQUERY_T, *ESS_PATTRIBUTEQUERY_T, **ESS_PPATTRIBUTEQUERY_T;
ESS_BOOL_T bInputMemberIsHandle Boolean value:

l TRUE: attribute query by member handle
l FALSE: attribute query by member name string
ESS_HMEMBER_T uInputMember A union variable for the following member reference values:
ESS_STR_T uInputMember.hMember l Member handle
uInputMember.szMember l Member name string
ESS_USHORT_T usInputMemberType A constant identifier indicating the data type of the member queried:
l ESS_BASE_MEMBER
See Table 6, “C API Attributes Terminology,” on page 96.
707
ESS_USHORT_T usOutputMemberType A constant identifier indicating the data type of the member returned:
l ESS_BASE_MEMBER
l ESS_INVALID_MEMBER
“ESS_ATTRIBUTEVALUE_T” on page Attribute A structure defining the attribute value for query input
113
ESS_USHORT_T usOperation A constant identifier indicating the type of query operation:

l ESS_EQ: equal to
l ESS_NEQ: not equal to
l ESS_GT: greater than
l ESS_LT: less than
l ESS_GTE: greater than or equal to
l ESS_LTE: less than or equal to
l ESS_TYPEOF
l ESS_ALL
ESS_GENLEVELNAME_T
Contains information about generation and level names.
typedef struct ESS_GENLEVELNAME_T
{
ESS_USHORT_T usNumber;
ESS_MBRNAME_T szName;
} ESS_GENLEVELNAME_T, *ESS_PGENLEVELNAME_T, **ESS_PPGENLEVELNAME_T;
ESS_USHORT_T usNumber Generation or level number.
ESS_MBRNAME_T szName Generation or level name.
ESS_GENLEVELNAMEEX_T
Contains information about generation and level names.
typedef struct ESS_GENLEVELNAMEEX_T
{
708
ESS_USHORT_T usNumber;
ESS_BOOL_T, bNameUnique
ESS_MBRNAME_T szName;
} ESS_GENLEVELNAMEEX_T, *ESS_PGENLEVELNAMEEX_T, **ESS_PPGENLEVELNAMEEX_T;
ESS_USHORT_T usNumber Generation or level number.
ESS_BOOL_T bNameUnique Generation or level member-name uniqueness.
ESS_MBRNAME_T szName Generation or level name.
ESS_MBRCOUNTS_T
Contains information about member counts for queries.
typedef struct ESS_MBRCOUNTS_T
{
ESS_ULONG_T ulStart;
ESS_ULONG_T ulMaxCount;
ESS_ULONG_T ulTotalCount;
ESS_ULONG_T ulReturnCount;
} ESS_MBRCOUNTS_T, *ESS_PMBRCOUNTS_T, **ESS_PPMBRCOUNTS_T;
ESS_ULONG_T ulStart Starting member for retrieval of information.
ESS_ULONG_T ulMaxCount Maximum number of members to retrieve.
ESS_ULONG_T ulTotalCount Return of the total count of members that exist in the results of the query. This could be more than
ulMaxCount.
ESS_ULONG_T ulReturnCount Return count of returned member handles. This should never be more than ulMaxCount.
ESS_MBRINFO_T
Contains information about an outline member.
typedef struct ESS_MBRINFO_T
{
ESS_MBRNAME_T szMember;
ESS_USHORT_T usLevel;
ESS_USHORT_T usGen;
ESS_USHORT_T usConsolidation;
ESS_BOOL_T fTwoPass;
ESS_BOOL_T fExpense;
ESS_USHORT_T usConversion;
ESS_MBRNAME_T szCurMember;
ESS_USHORT_T usTimeBalance;
ESS_USHORT_T usSkip;
ESS_USHORT_T usShare;
709
ESS_USHORT_T usStorage;
ESS_USHORT_T usCategory;
ESS_USHORT_T usStorageCategory;
ESS_MBRCOMMENT_T szComment;
ESS_ULONG_T ulChildCount;
ESS_MBRNAME_T szDimName;
ESS_BOOL_T fAttributed;
ESS_BOOL_T fHasRelDesc;
ESS_BOOL_T fHasHAEnabled;
ESS_PVOID_T, pLastSibling;
ESS_ULONG_T, ulSiblingCount;
ESS_BOOL_T, fFormula;
ESS_BOOL_T, fUda;
ESS_BOOL_T, fAlias;
ESS_BOOL_T, fIndependentDim;
ESS_UCHAR_T, ucHierarchyType;
ESS_UCHAR_T, ucDimSolveOrder;
ESS_UCHAR_T, ucSolveOrder;
ESS_BOOL_T, fNonUniqueName;
ESS_BOOL_T, fFlow;
} ESS_MBRINFO_T, *ESS_PMBRINFO_T, **ESS_PPMBRINFO_T;
ESS_MBRNAME_T szMember Member name. This field can be set only by the caller when creating the member.
ESS_USHORT_T usLevel Level of the member in the outline. This field cannot be modified.
ESS_USHORT_T usGen Generation of the member in the outline. This field cannot be modified.
ESS_USHORT_T usConsolidation Unary consolidation type. It can be one of the following:

l ESS_UCALC_ADD
l ESS_UCALC_SUB
l ESS_UCALC_MULT
l ESS_UCALC_DIV
l ESS_UCALC_PERCENT
l ESS_UCALC_NOOP
ESS_BOOL_T fTwoPass ESS_TRUE if two-pass calculation member.
ESS_BOOL_T fExpense ESS_TRUE if expense member.
ESS_USHORT_T usConversion Currency Conversion type. This is valid only for members of the Accounts
dimension. It can be one of the following:
l ESS_CONV_NONE
l ESS_CONV_CATEGORY
l ESS_CONV_NOCONV
ESS_MBRNAME_T szCurMember If member is of the Accounts dimension and usConversion is ESS_CONV_

CATEGORY. This field defines the currency category. If member is of the Country
dimension. This field defines the currency name. This field is undefined in all other
situations.
710
ESS_USHORT_T usTimeBalance Time balance option. Valid field only for members of the Accounts dimension. It
can be one of the following:
l ESS_TIMEBAL_NONE
l ESS_TIMEBAL_FIRST
l ESS_TIMEBAL_LAST
l ESS_TIMEBAL_AVG
ESS_USHORT_T usSkip Time balance skip option. Valid field only for members of the Accounts dimension
if usTimeBalance is not equal to ESS_TIMEBAL_NONE. It can be one of the
following:
l ESS_SKIP_NONE
l ESS_SKIP_MISSING
l ESS_SKIP_ZEROS
l ESS_SKIP_BOTH
ESS_USHORT_T usShare Share option. It can be one of the following:

l ESS_SHARE_DATA (default value)
l ESS_SHARE_DYNCALCSTORE
l ESS_SHARE_DYNCALCNOSTORE
l ESS_SHARE_LABEL
l ESS_SHARE_NEVER
l ESS_SHARE_SHARE (Valid for level 0 members only)
ESS_USHORT_T usStorage Dimension storage type. This field is valid only for dimension members and can
be one of the following:
l ESS_DIMTYPE_DENSE
ESS_USHORT_T usCategory Dimension category. This field is valid only for dimensions and attribute members.
It can be one of the following:
l ESS_CAT_ACCOUNTS
l ESS_CAT_ATTRCALC (for internal use only)
l ESS_CAT_ATTRIBUTE
l ESS_CAT_COUNTRY
l ESS_CAT_CURPARTITION (for non-currency databases only)
l ESS_CAT_NONE
l ESS_CAT_TIME
l ESS_CAT_TYPE (for currency databases only)
711
ESS_USHORT_T usStorageCategory Dimension storage category. This field is valid only for dimensions and attribute
members. Optimizes the storage types of dimensions when the outline is
configured for automatic optimization. It can be one of the following:
l ESS_STORECAT_ACCOUNTS
l ESS_STORECAT_ATTRCALC (for internal use only)
l ESS_STORECAT_ATTRIBUTE
l ESS_STORECAT_BUSUNIT
l ESS_STORECAT_CUSTOMER
l ESS_STORECAT_DIST
l ESS_STORECAT_GEOG
l ESS_STORECAT_MARKET
l ESS_STORECAT_ORGAN
l ESS_STORECAT_OTHER
l ESS_STORECAT_PRODUCT
l ESS_STORECAT_SCENARIO
l ESS_STORECAT_TIME
l ESS_STORECAT_UNITS
ESS_MBRCOMMENT_T szComment Member comment array
ESS_ULONG_T ulChildCount This field contains the total number of children of the member specified in ESS_
MBRNAME_T.
ESS_MBRNAME_T szDimName Attribute dimension name
ESS_BOOL_T fAttributed Indicates whether the member has attributes associated with it. Values: ESS_
TRUE and ESS_FALSE.
“ESS_ATTRIBUTEVALUE_T” on Attribute Attribute value

page 113
ESS_BOOL_T fHasRelDesc The member has relational descendants.
ESS_BOOL_T fHasHAEnabled The dimension has relational partitions enabled.

Valid only for Dimension members.
RSS_PVOID_T pLastSibling Last sibling pointer
ESS_ULONG_T uSiblingCount Sibling count
ESS_BOOL_T fFormula Indicates whether has a formula
ESS_BOOL_T fUda Indicates whether has UDA
ESS_BOOL_T fAlias Indicates whether has alias
ESS_BOOL_T fIndependentDim For dimensions on varying attribute outlines; indicates if an independent

dimension
712
ESS_UCHAR_T ucHierarchyType Defines the type of hierarchy based on the generation.

If the member is generation 1, then:
l ESS_STORED_HIERARCHY indicates a single stored hierarchy
l ESS_DYNAMIC_HIERARCHY indicates a single dynamic hierarchy
l ESS_MULTIPLE_HIERARCHY_IS_ENABLED indicates multiple hierarchies
If the member is generation 2, then:

l ESS_STORED_HIERARCHY indicates a sub hierarchy
l ESS_DYNAMIC_HIERARCHY indicates a dynamic sub hierarchy
ESS_UCHAR_T udDimSolveOrder Defines the solve order for the dimension.
ESS_UCHAR_T udSolveOrder Indicates the solve order value. The solve order can be 0-127.
ESS_BOOL_T fNonUniqueName Indicates whether the member name is unique
ESS_BOOL_T fFlow Indicates that member is type Flow
ESS_OTLQUERYERRORLIST_T
Stores a list of errors encountered during an extended member query; that is, while calling
EssOtlQueryMembersEx.
typedef struct ESS_OTLQUERYERRORLIST_T
{
ESS_ULONG_T ulCount;
ESS_OTLQUERYERROR_T* ErrorArray;
} ESS_OTLQUERYERRORLIST_T, *ESS_POTLQUERYERRORLIST_T, **ESS_PPOTLQUERYERRORLIST_T;
ESS_ULONG_T ulCount Number of errors returned during a query
ESS_OTLQUERYERROR_T* ErrorArray Pointer to an array of errors returned during a query
ESS_OUTERROR_T
Returns the errors for each member when verifying an outline. The errors are bit field values
returned in a 32-bit status word. Each error value corresponds to a function call error return
value described in Table 7, “C Outline API Error Return Values,” on page 695.
typedef struct ESS_OUTERROR_T
{
ESS_ULONG_T ulErrors;
} ESS_OUTERROR_T, *ESS_POUTERROR_T, **ESS_PPOUTERROR_T;
713
ESS_HMEMBER_T hMember Handle to member with errors.
ESS_ULONG_T ulErrors Bitmask of errors for the member. See Values for ulErrors.
Values for ulErrors

The following are possible values for ulErrors:
l ESS_OUTERROR_ALIASSHARED
l ESS_OUTERROR3_ASO_BAD_AGGREGATION_OPERATOR
l ESS_OUTERROR3_ASO_BAD_NONLEAFMBR
l ESS_OUTERROR3_ASO_DYNASSOCD
l ESS_OUTERROR3_ASO_EITHERLABELORFORMULA
l ESS_OUTERROR3_ASO_INVALID_AGGLEVELUSAGE
l ESS_OUTERROR3_ASO_INVALIDATTRCALC
l ESS_OUTERROR3_ASO_ISDUPLICATESHAREINHIERARCHY
l ESS_OUTERROR3_ASO_LABEL_SPAN
l ESS_OUTERROR3_ASO_LEVELPRODUCT_TOO_LARGE
l ESS_OUTERROR3_ASO_NOATTRIBUTE_ON_ACCOUNTS
l ESS_OUTERROR3_ASO_NOFORMULA
l ESS_OUTERROR4_ASO_PROTOLEVELZERO
l ESS_OUTERROR3_ASO_SHAREDMBR
l ESS_OUTERROR3_ASO_TWOCHILDRENFORTHISOPER
l ESS_OUTERROR3_ASO_WHOLEACCOUNTSDIMVIRTUAL
l ESS_OUTERROR2_ATTRCALCABSENT
l ESS_OUTERROR2_ATTRDIMNOTASSOCIATED
l ESS_OUTERROR_BADATTRIBUTECODE
l ESS_OUTERROR_BADCATEGORY
l ESS_OUTERROR_BADSHARE
l ESS_OUTERROR_BADSKIP
l ESS_OUTERROR_BADSTORAGE
l ESS_OUTERROR_BADSTORAGECATEGORY
l ESS_OUTERROR_BADTIMEBAL
l ESS_OUTERROR2_BOOLEANNAMESETTING
l ESS_OUTERROR2_CHILDCOUNT
l ESS_OUTERROR_CURTOOMANYDIMS
714
l ESS_OUTERROR2_DATATYPEMISMATCH
l ESS_OUTERROR_DUPGENLEVNAME
l ESS_OUTERROR_DUPLICATEALIAS
l ESS_OUTERROR2_DUPLICATEATTRCALC
l ESS_OUTERROR_DUPLICATENAME
l ESS_OUTERROR4_DUPNAME_INDIMENSION
l ESS_OUTERROR4_DUPNAME_INGENERATION
l ESS_OUTERROR4_DUPNAME_INLEVEL
l ESS_OUTERROR4_FLOWTAGINCOMPLETE
l ESS_OUTERROR_ILLEGALALIASSTRING
l ESS_OUTERROR2_ILLEGALATTRCALC
l ESS_OUTERROR2_ILLEGALATTRCALCSET
l ESS_OUTERROR2_ILLEGALATTRVALUE
l ESS_OUTERROR2_ILLEGALATTRIBUTEPARENT
l ESS_OUTERROR2_ILLEGALATTRSET
l ESS_OUTERROR_ILLEGALCOMBOALIAS
l ESS_OUTERROR_ILLEGALCURRENCY
l ESS_OUTERROR2_ILLEGALDATATYPE
l ESS_OUTERROR_ILLEGALDEFALIAS
l ESS_OUTERROR_ILLEGALNAME
l ESS_OUTERROR2_ILLEGALORDER
l ESS_OUTERROR2_ILLEGALSCAASSOCS
l ESS_OUTERROR_ILLEGALTAG
l ESS_OUTERROR2_ILLEGALUDA
l ESS_OUTERROR2_INDEPMBR_BADORDER
l ESS_OUTERROR2_INDEPMBR_NOTLEVEL0
l ESS_OUTERROR2_INDEPMBR_SHAREORLABEL
l ESS_OUTERROR_LEAFLABEL
l ESS_OUTERROR2_LEVELMISMATCH
l ESS_OUTERROR_MEMBERCALC
l ESS_OUTERROR_NOSHAREPROTO
l ESS_OUTERROR2_NOTATTRIBUTE
l ESS_OUTERROR_NOTIMEDIM
l ESS_OUTERROR2_NOTLEVEL0
l ESS_OUTERROR4_PROTO_NONUNIQUE
715
l ESS_OUTERROR_SHAREDMEMBERFORMULA
l ESS_OUTERROR_SHARENOTLEVEL0
l ESS_OUTERROR_SHAREUDA
l ESS_OUTERROR4_TI_INCORRECT_MBRTIMESPANS
l ESS_OUTERROR4_TI_INVALIDCONSOLIDATION
l ESS_OUTERROR4_TI_LINKATTR_INVALID
l ESS_OUTERROR4_TI_LINKATTR_INVALIDASSOC
l ESS_OUTERROR4_TI_LINKATTR_UNBALANCEDHIER
l ESS_OUTERROR4_TI_ONLYONE_SINGLEHIER
l ESS_OUTERROR_TIMESPARSE
l ESS_OUTERROR2_TWOPASSPARENTNONTWOPASS
l ESS_OUTERROR_VIRTLEV0NOFORMULA
l ESS_OUTERROR_VIRTBADCHILD
l ESS_OUTERROR_VIRTBADPARENT
l ESS_OUTERROR_VIRTWHOLEDIMVIRTUAL
l ESS_OUTERROR4_20DUPNAME_INPATH
ESS_OUTLINEINFO_T
Contains information about the outline.
typedef struct ESS_OUTLINEINFO_T
{
ESS_BOOL_T fCaseSensitive;
ESS_USHORT_T usOutlineType;
ESS_BOOL_T fAutoConfigure;
ESS_USHORT_T usNumAliasTables;
ESS_ALIASNAME_T pAliasTables[1];
ESS_BOOL_T fEnableVaryingAttrs;
ESS_BOOL_T fNonUniqueName;
ESS_UCHAR_T, ucImpliedShareSetting;
ESS_BOOL_T, fEnableMemberType;
} ESS_OUTLINEINFO_T, *ESS_POUTLINEINFO_T, **ESS_PPOUTLINEINFO_T;
ESS_BOOL_T fCaseSensitive Case-sensitive member names flag.
716
ESS_USHORT_T usOutlineType Type of the outline. It can be one of the following:

l ESS_DBTYPE_NORMAL
Normal database
l ESS_DBTYPE_CURRENCY
Currency database
l ESS_DBTYPE_NORMALMDX
Database with MDX type formula
l ESS_DBTYPE_ASO
Aggregate storage database
l ESS_DBTYPE_ROLAP
ROLAP database
l ESS_DBTYPE_ASO71
Aggregate storage database with version 7.1 otl file
ESS_BOOL_T fAutoConfigure ESS_TRUE to automatically configure the dimension storage (dense/sparse) when a block-
storage outline is saved.
ESS_USHORT_T usNumAliasTables Number of alias tables. This is a read-only field and will be ignored in the
EssOtlSetOutlineInfo() call.
ESS_ pAliasTables Array of alias table names existing in the outline. The usNumAliasTables field defines the
ALIASNAME_T number of entries in this array. This is a read-only field and will ignored in the
ESS_BOOL_T fEnableVaryingAttrs ESS_TRUE indicates the outline supports varying attributes.
ESS_BOOL_T fNonUniqueName Indicates whether the outline supports duplicate member names.
ESS_UCHAR_T ucImpliedShareSetting Implied Share setting:

l TRUE (default) means that Implied Share is ON
l FALSE means that Implied Share is OFF
ESS_BOOL_T fEnableMemberType ESS_TRUE indicates member types are enabled.
ESS_OUTLINEINFOEX_T
Contains information about the outline.
typedef struct ESS_OUTLINEINFOEX_T
{
ESS_BOOL_T fCaseSensitive;
ESS_USHORT_T usOutlineType;
ESS_BOOL_T fAutoConfigure;
ESS_USHORT_T usNumAliasTables;
ESS_ALIASNAME_T pAliasTables[1];
ESS_BOOL_T fEnableVaryingAttrs;
717
ESS_UCHAR_T, ucImpliedShareSetting
ESS_BOOL_T, fEnableMemberType;
ESS_CHAR_T, cSMDateFormatValue;
} ESS_OUTLINEINFOEX_T, *ESS_POUTLINEINFOEX_T, **ESS_PPOUTLINEINFOEX_T;
ESS_USHORT_T usOutlineType Type of the outline. It can be one of these:

l ESS_DBTYPE_NORMAL
ESS_BOOL_T fAutoConfigure ESS_TRUE to automatically configure the dimension storage (dense/sparse) when a block-
storage outline is saved.
ESS_USHORT_T usNumAliasTables Number of alias tables. This is a read-only field and is ignored in the
ESS_ pAliasTables Array of alias table names existing in the outline. The usNumAliasTables field defines the
ALIASNAME_T number of entries in this array. This is a read-only field and is ignored in the
EssOtlSetOutlineInfo call.
ESS_BOOL_T fEnableVaryingAttrs ESS_TRUE indicates the outline supports varying attributes.
ESS_UCHAR_T ucImpliedShareSetting Implied share setting for the outline. Possible values:
l ESS_IMPLIEDSHARE_DEFAULT
l ESS_IMPLIEDSHARE_DEFAULT_ON
l ESS_IMPLIEDSHARE_DEFAULT_OFF
l ESS_IMPLIEDSHARE_FORCE_ON
l ESS_IMPLIEDSHARE_FORCE_OFF
ESS_BOOL_T fEnableMemberType Indicates whether the outline has typed measures enabled; for example, enumerated text
or date measures.
ESS_UCHAR_T cSMDateFormatValue In outlines that have typed measures enabled, the string that represents the chosen date
format. For example, mon dd yyyy
ESS_PERSPECTIVE_T
Contains information about perspectives and validity sets.
typedef struct ESS_PERSPECTIVE_T
{
ESS_USHORT_T, usValiditySetType;
ESS_USHORT_T, usFiller;
ESS_STR_T, szValiditySetExpr;
ESS_INT32_T, countOfIndepDims;
ESS_INT32_T, countOfIndepRanges;
ESS_PVOID_T*, pIndepMbrs;
} ESS_PERSPECTIVE_T; *ESS_PPERSPECTIVE_T
718
ESS_USHORT_T usValiditySetType How members are specified. Possible values:

l ESS_VALIDITYSET_TYPE_MBRHDLS
l ESS_VALIDITYSET_TYPE_MBRNAMS
ESS_USHORT_T usFiller Set to zero
ESS_STR_T szValiditySetExpr MDX expression spescified by the MDX type
ESS_INT32_T countOfIndepDims Size of each of the tuples
ESS_INT32_T countOfIndepRanges Number of tuple ranges
ESS_PVOID_T pIndepMbrs Array of member handles (ESS_HMEMBER_T) or member names (ESS_STR_T) depending on
usValiditySetType
Descriptions
The terms perspective and validity set both designate collections of independent members.
l Perspective designates any combination of independent members, and is used when
querying either the client or server for associations.
l Validity set designates the collection of independent members for which an association is
true. The term also applies to the set of independent members used for an association or
disassociation.
Independent members can be designated as:

l ESS_VALIDITYSET_TYPE_MBRHDLS: Independent members are specified as a sequence of
ranges (in the XRange sense i.e. Mar 2003-Feb 2004 consists of 2003 starting with March
and Jan/Feb of 2004) of member handles.
l ESS_VALIDITYSET_TYPE_MBRNAMS: Same as ESS_VALIDITYSET_TYPE_MBRHDLS,
except that the ranges are specified with member names.
ESS_PREDICATE_T
Contains information about a query description.
typedef struct ESS_PREDICATE_T
{
ESS_ULONG_T ulQuery;
ESS_STR_T pszDimension;
ESS_STR_T pszString1;
ESS_STR_T pszString2;
} ESS_PREDICATE_T, *ESS_PPREDICATE_T, **ESS_PPPREDICATE_T;
ESS_ULONG_T ulQuery Type of query. See EssOtlQueryMembers for more information.
719
ESS_ULONG_T ulOptions Options dependent on the query type. See EssOtlQueryMembers for more information.
ESS_STR_T pszDimension Dimension name. See EssOtlQueryMembers for more information.
ESS_STR_T pszString1 Input string value. See EssOtlQueryMembers for more information.
ESS_STR_T pszString2 Input string value. See EssOtlQueryMembers for more information.
ESS_SVROTLINFO_T
Contains information about the outline. This structure can be used by
EssGetSrvOutlineInfo.
typedef struct ESS_SVROTLINFO_T
{
ESS_BOOL_T, fCaseSensitive;
ESS_USHORT_T, usOutlineType;
ESS_USHORT_T, usNumAliasTables;
ESS_ALIASNAME_T, pAliasTables, 10;
} ESS_SVROTLINFO_T, *ESS_PSVROTLINFO_T;
ESS_USHORT_T usOutlineType Type of the outline. It can be one of the following:

l ESS_DBTYPE_NORMAL
ESS_USHORT_T usNumAliasTables Number of alias tables. This is a read-only field and will be ignored in the
ESS_ALIASNAME_ pAliasTables Array of alias table names existing in the outline. The usNumAliasTables field defines the number
T of entries in this array. This is a read-only field and will ignored in the
ESS_VALIDITYSET_T
Contains information about perspectives and validity sets.
typedef struct ESS_VALIDITYSET_T
{
ESS_USHORT_T, usValiditySetType;
ESS_USHORT_T, usFiller;
ESS_STR_T, szValiditySetExpr;
ESS_INT32_T, countOfIndepDims;
720
ESS_INT32_T, countOfIndepRanges;
ESS_PVOID_T*, pIndepMbrs;
} ESS_VALIDITYSET_T; *ESS_PVALIDITYSET_T
ESS_USHORT_T usValiditySetType How members are specified. Possible values:

l ESS_VALIDITYSET_TYPE_MBRHDLS
l ESS_VALIDITYSET_TYPE_MBRNAMS
ESS_USHORT_T usFiller Set to zero
ESS_STR_T szValiditySetExpr MDX expression spescified by the MDX type
ESS_INT32_T countOfIndepDims Size of each of the tuples
ESS_INT32_T countOfIndepRanges Number of tuple ranges
ESS_PVOID_T pIndepMbrs Array of member handles (ESS_HMEMBER_T) or member names (ESS_STR_T) depending on
usValiditySetType
Description
The terms perspective and validity set both designate collections of independent members.
l Perspective designates any combination of independent members, and is used when
querying either the client or server for associations.
l Validity set designates the collection of independent members for which an association is
true. The term also applies to the set of independent members used for an association or
disassociation.
Independent members can be designated as:

l ESS_VALIDITYSET_TYPE_MBRHDLS: Independent members are specified as a sequence of
ranges (in the XRange sense i.e. Mar 2003-Feb 2004 consists of 2003 starting with March
and Jan/Feb of 2004) of member handles.
l ESS_VALIDITYSET_TYPE_MBRNAMS: Same as ESS_VALIDITYSET_TYPE_MBRHDLS,
except that the ranges are specified with member names.
721
722
C Outline API Functions
11
In This Chapter
C Outline API Function Categories...................................................................... 723
C Outline API Function Reference ...................................................................... 731
C Outline API Function Categories

C Outline API functions by category:
l “C Outline API Alias Table Functions” on page 723
l “C Outline API Attributes Functions” on page 724
l “C Outline API Dynamic Time Series Functions” on page 725
l “C Outline API Generation Name Functions ” on page 725
l “C Outline API Level Name Functions” on page 725
l “C Outline API Member Administration Functions” on page 725
l “C Outline API Member Alias Functions” on page 726
l “C Outline API Member Formula Functions” on page 726
l “C Outline API Member Traversal Functions” on page 727
l “C Outline API Outline Administration Functions” on page 727
l “C Outline API Outline Query Functions” on page 728
l “C Outline API Setup and Cleanup Functions” on page 728
l “C Outline API User-Defined Attributes Functions” on page 729
l “C Outline API User-Defined View Selection Functions” on page 729
l “C Outline API Varying Attributes Functions” on page 729
C Outline API Alias Table Functions

These functions perform operations on alias tables.
EssOtlCreateAliasTable() Creates an empty alias table in the outline
723
EssOtlCopyAliasTable Copies an alias table to another alias table
EssOtlRenameAliasTable Renames an existing alias table
EssOtlClearAliasTable Clears all entries from an existing alias table without deleting the alias table
EssOtlDeleteAliasTable Deletes the alias table from the outline and clears all of its entries
EssOtlSetAliasTableLanguage Sets a language code for the alias table. An alias table can have multiple language
codes.
EssOtlGetAliasTableLanguages Gets the set of language codes associated with the alias table.
EssOtlClearAliasTableLanguages Clears the set of language codes from the alias table.
C Outline API Attributes Functions

These C Outline functions are for attributes.
See also “C Outline API Varying Attributes Functions” on page 729.
EssOtlAssociateAttributeDimension Associates an attribute dimension with a base dimension
EssOtlAssociateAttributeMember Associates an attribute member with a base dimension member
EssOtlDisassociateAttributeDimension Disassociates an attribute dimension from a base dimension
EssOtlDisassociateAttributeMember Disassociates an attribute member from a base dimension member
EssOtlFindAttributeMembers Returns all base dimension members that are associated with an attribute
member
EssOtlFreeStructure Frees memory dynamically allocated for string type attribute information
EssOtlGetAssociatedAttributes Returns all attribute dimension members that are associated with a base
dimension member or base dimension
EssOtlGetAttributeInfo Returns attribute information for a given attribute member or dimension
EssOtlGetAttributeSpecifications Retrieves attribute specifications for the outline
EssOtlQueryAttributes Queries the outline for member attribute information
EssOtlQueryAttributesEx
EssOtlSetAttributeSpecifications Sets attribute specifications for the outline
See “C Main API Attributes Functions ” on page 195.
724
C Outline API Dynamic Time Series Functions
These functions enable and work with Dynamic Time Series members and aliases.
EssOtlDeleteDTSMemberAlias Deletes an alias name for a Dynamic Time Series member.
EssOtlEnableDTSMember Enables a new Dynamic Time Series members for the outline.
EssOtlGetEnabledDTSMembers Gets the defined Dynamic Time Series members for the outline.
EssOtlGetDTSMemberAlias Gets an alias name for a Dynamic Time Series member.
EssOtlSetDTSMemberAlias Sets an alias name for a Dynamic Time Series member.
C Outline API Generation Name Functions

These functions perform operations on generation names.
EssOtlGetGenName Gets the generation name for the specified dimension and generation number
EssOtlGetGenNames Retrieves all generation names specified for a particular dimension
EssOtlSetGenName Sets the generation name for the specified dimension and generation number
EssOtlDeleteGenName Deletes the generation name of the specified dimension and level number
C Outline API Level Name Functions

These functions perform operations on level names.
EssOtlGetLevelName Gets the level name of the specified dimension
EssOtlGetLevelNames Retrieves all level names specified for a particular dimension
EssOtlSetLevelName Sets the level name of the specified dimension
EssOtlDeleteLevelName Deletes the level name of the specified dimension
C Outline API Member Administration Functions

These functions assist in managing the members of an outline.
725
EssOtlAddMember Adds a member
EssOtlDeleteMember Deletes a member
EssOtlAddDimension Adds a dimension
EssOtlDeleteDimension Deletes a dimension
EssOtlRenameMember Renames a member
EssOtlMoveMember Moves a member
EssOtlFindMember Finds a member
EssOtlGetMemberCommentEx Gets the extended comment for a specified member
EssOtlGetMemberInfo Gets member information
EssOtlSetMemberCommentEx Sets the extended comment for a specified member
EssOtlSetMemberInfo Sets member information
EssOtlGetMemberSolveOrder Gets member solve order
EssOtlSetMemberSolveOrder Sets member solve order
EssOtlGetDimensionSolveOrder Gets dimension solve order
EssOtlSetDimensionSolveOrder Sets dimension solve order
C Outline API Member Alias Functions

These functions perform operations on member aliases.
EssOtlFindAlias Finds a member with the specified alias name
EssOtlGetMemberAlias Gets the default member alias for a specific member in a specific alias table
EssOtlSetMemberAlias Sets the default member alias for a specific member in a specific alias table
EssOtlDeleteMemberAlias Deletes the default member alias for a specific member in a specific alias table
C Outline API Member Formula Functions

These functions perform operations on member formulas.
726
EssOtlGetMemberFormula Gets the formula of the specified member
EssOtlGetMemberLastFormula Returns the last formula used to calculate the member
EssOtlSetMemberFormula Sets the formula for the specified member
EssOtlDeleteMemberFormula Deletes the formula of the specified member
C Outline API Member Traversal Functions

These functions are used in traversing the outline tree.
EssOtlGetFirstMember Returns a member handle to the first member in the outline; the first dimension defined
in the outline
EssOtlGetChild Returns a member handle to the child of a member
EssOtlGetParent Returns a member handle to the parent of a member
EssOtlGetNextSibling Returns a member handle to the next sibling of a member
EssOtlGetPrevSibling Returns a member handle to the previous sibling of a member
EssOtlGetNextSharedMember Returns a member handle to the next shared member of a real member
EssOtlQueryGetFirstDimension Returns the dimension handle of the first dimension in the outline
EssOtlQueryGetNextDimension() Returns the next dimension handle of the dimension in the outline opened in query mode
C Outline API Outline Administration Functions

These functions assist in managing outlines.
EssOtlGetOutlineInfo Returns information about the outline file
EssOtlGetUpdateTime Returns the timestamp for the specified outline
EssOtlSetOutlineInfo Sets outline information
EssOtlVerifyOutline Verifies that an outline is correct
EssOtlSortChildren Sorts the children of an outline member
EssOtlGenerateCurrencyOutline Generates a currency outline based on the existing outline
EssOtlGetASOCompressionDimension Gets aggregate storage compression dimension
727
EssOtlSetASOCompressionDimension Sets aggregate storage compression dimension
C Outline API Outline Query Functions

These functions assist in making outline queries.
EssOtlGetMemberField Returns data for the specified field of a specified outline member
EssOtlOpenOutlineQuery Opens an existing outline
EssOtlQueryMembers Queries the outline, using a member handle
EssOtlQueryMembersByName Queries the outline, using a member name string
EssOtlQueryMembersEx Queries specific members and member fields, and returns an array of member handles
EssOtlQueryAttributes Queries the outline for attribute information.
EssOtlFreeMembers Frees the member array returned from EssOtlQueryMembers()
C Outline API Setup and Cleanup Functions

These functions start and finish editing operations on an outline.
EssOtlNewOutline Creates a new outline
EssOtlOpenOutline Opens an existing outline
EssOtlOpenOutlineEx Opens an existing outline (for Unicode mode)
EssOtlWriteOutline Writes the outline to the server
EssOtlWriteOutlineEx Writes the outline to the server (for Unicode mode)
EssOtlRestructure Restructures the database based on the newly saved outline
EssOtlCloseOutline Frees resources associated with the outline
C Outline API Unicode Mode Functions

The following functions help you work with the Essbase Server outlines in Unicode mode.
728
EssOtlWriteOutlineEx Writes the outline to the server, specifying whether to save in UTF-8 encoding or in non-Unicode
encoding.
EssOtlOpenOutlineEx Opens the outline of a Unicode-mode application.
C Outline API User-Defined Attributes Functions

These functions perform operations on user-defined attributes (UDAs).
EssOtlGetDimensionUserAttributes Gets the UDAs of the specified dimension
EssOtlGetUserAttributes Gets the UDAs of the specified member
EssOtlSetUserAttribute Sets a UDA for the specified member
EssOtlDeleteUserAttribute Deletes a UDA of the specified member
C Outline API User-Defined View Selection Functions

These functions define view selection criteria for aggregation of aggregate storage databases.
EssOtlSetAggLevelUsage Applies view selection properties to stored hierarchies
EssOtlGetAggLevelUsage Returns the applied view selection properties on stored hierarchies
EssOtlAddQueryHint Adds a query hint to the outline to aid in view selection
EssOtlGetQueryHint Returns specified query hint defined on an outline
EssOtlSetQueryHint Sets a query hint
EssOtlGetNumQueryHints Returns the number of query hints
EssOtlGetQueryHintSize Returns the size (in number of members) of query hints
EssOtlDeleteQueryHint Deletes specified query hint and decreases the number of hints by one
C Outline API Varying Attributes Functions

These C Outline functions are for varying attributes.
EssOtlQueryVaryingAttributes Queries the outline for member varying attribute information
729
EssOtlDetailQueryVaryingAttributes Similar to EssOtlQueryVaryingAttributes.
EssOtlVaryingAssociateAttribute Associates a varying attribute member with a base dimension

member
EssOtlVaryingAssociateAttributeDimension Associates a varying attribute dimension with a base dimension
EssOtlVaryingDisassociateAttribute Disassociates a varying attribute dimension from a base dimension
EssOtlVaryingGetAssociatedAttributes Returns all varying attribute members that are associated with a
base dimension member or base dimension
EssOtlVaryingGetAttributeIndepDims Returns the independent dimensions, if any, for the dimension

containing the specified varying attribute member
These APIs may not be fully compatible with future implementations.

See “C Main API Attributes Functions ” on page 195.
About Varying Attributes

Attribute associations can depend on outside factors. For example
l Over time a client can have different sales representatives assigned to it.
l Over time or based on market territory, packaging for a product can be different.
The varying attributes feature enables you to keep track of values for each factor. For example,
consider the situation where the sales representative attribute association for Customer A gets
changed in May. Customer sales totals and sales representative assignments over the first six
months look like this:
Jan Feb Mar Apr May Jun
5540 2190 1580 300 2455 3255
Jones Jones Jones Jones Smith Smith
Using the varying attributes feature, retrievals can reflect that Jones sold Customer A $9610 (sum
of Jan, Feb, and Mar) and Smith sold $5680 (sum of May and Jun). Without this feature, the
only known representative is the current representative, Smith, and all sales ($15290) get
attributed to him.
Varying Attribute Terminology
Term Definition
independent The dimension upon which varying attributes depend; in the above example, the Year dimension.
dimensions
perspective A combination of independent dimension members that is used when querying for associations. Defined in
“ESS_PERSPECTIVE_T” on page 718.
validity set The collection of independent dimension members for which an association is true. Defined in
“ESS_VALIDITYSET_T” on page 720.
730
Outline Construction
Varying attributes are constructed in the API with the following flow:
Item Outline API Call
1. Set the outline type to accept varying EssOtlSetOutlineInfo, where pOutlineinfo->fEnableVaryingAttrs = ESS_TRUE.
attributes
2. Identify the independent dimension EssOtlSetMemberInfo, where pMemberInfo->fIndependentDim = ESS_TRUE
3. Associate the attribute dimension to the EssOtlVaryingAssociateAttributeDimension

base dimension and identify independent
dimensions
4. Associate attribute dimension members EssOtlVaryingAssociateAttribute

independent dimension members with base
dimension members
5. Save and restructure the outline. The same as when making other outline changes.
Maintenance Tasks
Item Outline API Call
Add a new association to EssOtlVaryingAssociateAttribute

independent members.
Remove independent member EssOtlVaryingDisassociateAttribute

associations
View existing independent EssOtlQueryVaryingAttributes or

dimension member EssOtlVaryingGetAssociatedAttributes
associations
Disassociate attribute EssOtlDisassociateAttributeDimension (disassociates all attribute dimensions).

dimensions from base
dimensions
C Outline API Function Reference

Consult the Contents page for the list of C Outline API functions, which are prefaced with EssOtl
EssOtlAddDimension
Adds a dimension to the outline and sets the member's attributes. The call also specifies a member
of the new dimension to associate data with when the outline is restructured.
Syntax
ESS_FUNC_M EssOtlAddDimension (hOutline, pMemberInfo, hPrevSibling, pszDataMbr,
phMember);
731
hOutline; ESS_HOUTLINE_T Outline context handle.
pMemberInfo; “ESS_MBRINFO_T” on Member information structure defining the member and its attributes.
page 709
hPrevSibling ESS_HMEMBER_T Handle of previous sibling. If this field is ESS_NULL, the dimension
becomes the first dimension in the outline. Otherwise, the dimension is
placed after the dimension specified in hPrevSibling.
pszDataMbr; ESS_STR_T Member name of a member in the new dimension that will receive the
data values when the outline is restructured. If this field is ESS_NULL,
the dimension member itself is used.
phMember ESS_PHMEMBER_T Handle of new member returned from the API.
Notes
l The ESS_MBRINFO_T structure must be created and filled before calling this function.
l To add an attribute dimension, you must call this function.
l To add a dimension that is not an attribute dimension, you can call this function or
EssOtlAddMember().
m EssOtlAddDimension() gives you the benefit of selecting any member in the added
dimension to be assigned the data values associated with the existing dimensions.
m If EssOtlAddMember() is used, the top member (dimension) of the added dimension
is used.
l In order for the pszDataMbr field to take effect, the outline must have been opened using
EssOtlOpenOutline() with the fKeepTrans flag set to ESS_TRUE.
l The member referred to in the pszDataMbr field is added to the new dimension using
EssOtlAddMember() after the dimension is created. If the referred to member doesn't exist
when restructuring takes place, the dimension member is used instead.
l For an attribute dimension, you must set the fields of ESS_MBRINFO_T as follows:
Field Setting
usConsolidation ESS_UCALC_NOOP
fTwoPass ESS_FALSE
fExpense ESS_FALSE
usConversion ESS_CONV_NONE
usTimeBalance ESS_TIMEBAL_NONE
usSkip ESS_SKIP_NONE
usShare ESS_SHARE_DYNCALCNOSTORE
usStorage ESS_DIMTYPE_SPARSE
732
Field Setting
usCategory ESS_CAT_ATTRIBUTE
usStorageCategory ESS_STORECAT_ATTRIBUTE
Attribute.usDataType One of the following attribute member data types:

m ESS_ATTRMBRDT_BOOL
m ESS_ATTRMBRDT_DATETIME
m ESS_ATTRMBRDT_DOUBLE
m ESS_ATTRMBRDT_STRING
l An attribute dimension must be associated with a base dimension.

l Attribute dimensions must be placed after base dimensions and standard dimensions.
Return Value
Returns 0 if successful; otherwise one of the following:
l OTLAPI_BAD_CONSOL
l OTLAPI_BAD_MBRNAME
l OOTLAPI_ERR_ADDNAMEUSEDTLAPI_ERR_ADDDELETEDIMDYNAMICCALC
l OTLAPI_ERR_BADSHARE
l OTLAPI_ERR_BADSKIP
l OTLAPI_ERR_BADSTORAGE
l OTLAPI_ERR_BADSTORAGECATEGORY
l OTLAPI_ERR_BADTIMEBAL
l OTLAPI_ERR_CURTOOMANYDIMS
l OTLAPI_ERR_ILLEGALBOOLEAN
l OTLAPI_ERR_ILLEGALCURRENCY
l OTLAPI_ERR_ILLEGALDATE
l OTLAPI_ERR_ILLEGALNUMERIC
l OTLAPI_ERR_ILLEGALTAG
l OTLAPI_ERR_LEAFLABEL
l OTLAPI_ERR_NONATTRDIMFOLLOWED
l OTLAPI_ERR_NOSHAREPROTO
l OTLAPI_ERR_NOTIMEDIM
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_OUTLINEINFO_T NewInfo;
733
ESS_HOUTLINE_T hOutline;
ESS_MBRINFO_T MbrInfo;
ESS_HMEMBER_T hDimMeasures;
memset (&NewInfo,'\0', sizeof(NewInfo));

sts = EssOtlNewOutline(hCtx, &NewInfo,
&hOutline);
if (!sts)
{
memset(&MbrInfo, '\0', sizeof(MbrInfo));
strcpy(MbrInfo.szMember, "Measures");
MbrInfo.usStorage = ESS_DIMTYPE_SPARSE;
MbrInfo.usCategory = ESS_CAT_ACCOUNTS;
sts = EssOtlAddDimension(hOutline, &MbrInfo,
ESS_NULL, "Profit",&hDimMeasures);
}
See Also
l EssOtlAddMember
l EssOtlDeleteDimension
l EssOtlDeleteMember
l EssOtlGetMemberInfo
EssOtlAddQueryHint
Adds a query hint to the outline to aid in view selection.
Hints are numbered from 1 to n. The first query hint has a hint number of 1. Each new query
hint is added to the end of the list, with its number increased by 1.
Syntax
ESS_FUNC_M EssOtlAddQueryHint (hOutline, numMembers, pMemberArray);
hOutline ESS_HOUTLINE_T Outline context handle (input).
numMembers ESS_SHORT_T Number of members in the array provided - usually the number of real
dimensions in the outline. (input)
pMemberArray ESS_PHMEMBER_T An array of members for the hint. Usually the array has one member per real
dimension, with NULL used for dimensions that are not part of the hint. This
array needs to be allocated.
Notes
l Level usage constraints override query hints whenever a conflict occurs (see
SetAggLevelUsage).
l Hints may not contain dynamic, label-only, or shared members.
l Hints may become invalid when the outline changes. Invalid hints result in a warning
message.
734
l Query hints enable you to influence normal view selection by informing Essbase about the
profile of common queries.
l This function is applicable only to Release 9.3 or higher aggregate storage databases.
l Query hints are written as MDX tuples, with no more than one member from each
dimension specified.
l Each member used in the query hint is considered a representative member. Essbase Server
interprets representative members as "this member or any member at the similar level of
aggregation." For example, using a query hint of (Qtr1, Sales, 100, East,
Actual) on Sample Basic means that quarterly, actual profit margin measures for level 1
products at level 1 markets is a common type of query.
l For any given dimension, Essbase Server interprets the omission of representative members
to mean that any member from the dimension may be used in a query. For example, using
a query hint of (Sales, 100, East) on Sample Basic means that profit margin measures
for level 1 products at level 1 markets is a common type of query, regardless of Year and
Scenario dimensions, which were omitted. The hint (Sales, 100, East) is treated as
identical to (NULL, Sales, 100, East, NULL).
Return Value
Example
ESS_HOUTLINE_T hOutline = ESS_NULL;
ESS_HMEMBER_T hMember1 = ESS_NULL;
ESS_HMEMBER_T hMember[3];
ESS_SHORT_T nmMembers = 3;
/* code to assign hOutline variable omitted */

/* code to assign hMember1 variable to member "Sales" omitted */
/* code to assign hMember2 variable to member "100" omitted */
/* code to assign hMember3 variable to member "East" omitted */
hMember[0] = hMember1;
if (hOutline)
{
sts = EssOtlAddQueryHint(hOutline, nmMembers, hMember);
if (sts)
printf("Error (%ld) adding QueryHint\n", sts);
}
else
{
if (!hOutline)
printf("Outline not provided\n");
}
735
See Also
l EssOtlSetQueryHint
l EssOtlGetQueryHint
l EssOtlGetNumQueryHints
l EssOtlGetQueryHintSize
l EssOtlDeleteQueryHint
EssOtlAddMember
Adds a member to the outline and sets the member's attributes.
Syntax
ESS_FUNC_M EssOtlAddMember (hOutline, pMemberInfo, hParent, hPrevSibling, phMember);
pMemberInfo; “ESS_MBRINFO_T” on page Member information structure defining the member and its
709 attributes.
hParent; ESS_HMEMBER_T Handle of parent. This field is used only if the hPrevSibling field is
ESS_NULL.
hPrevSibling; ESS_HMEMBER_T Handle of previous sibling.
phMember; ESS_PHMEMBER_T Handle of new member returned from the API.
Notes
l The ESS_MBRINFO_T structure must be created and filled before calling this function.
l The member name must be unique unless you are creating a shared member.
l Position of the added member:
m The new member is inserted following the hPrevSibling member.
m If the hPrevSibling field is ESS_NULL, the new member becomes the first child of the
parent specified by hParent.
m If both hParent and hPrevSibling are ESS_NULL, the new member becomes the first
dimension in the outline.
l To add a shared member:
m The shared member must be a zero-level (leaf node) member. (Shared members cannot
have children.)
m The actual member must already exist in the dimension.
m Set the usShare field of the ESS_MBRINFO_T structure to ESS_SHARE_SHARE.
l To add a LABEL member:
m You must first add the member without the label attribute set.
736
m Next, add its children. (A label member must have children.)
m Then, use EssOtlSetMemberInfo() to set the label tag of the label member.
l To add an attribute member, set the fields of ESS_MBRINFO_T as follows:
Field Setting
usConsolidation ESS_UCALC_NOOP
fTwoPass ESS_FALSE
fExpense ESS_FALSE
usConversion ESS_CONV_NONE
usTimeBalance ESS_TIMEBAL_NONE
usSkip ESS_SKIP_NONE
usShare ESS_SHARE_DYNCALCNOSTORE
usStorage ESS_DIMTYPE_SPARSE
usCategory ESS_CAT_ATTRIBUTE
usStorageCategory ESS_STORECAT_ATTRIBUTE
Attribute.usDataType For an attribute dimension or zero-level (leaf node) attribute member, set one of the following data types:
You may instead set a zero-level (leaf node) attribute member to ESS_ATTRMBRDT_AUTO.
You may set attribute members that are not zero level to ESS_ATTRMBRDT_NONE or ESS_ATTRMBR_AUTO.
Notes on Adding an Attribute Member:

m Adding a zero-level attribute member that is not of type ESS_ATTRMBRDT_STRING
also sets the szMember field of the ESS_MBRINFO_T structure to the attribute member's
long name, using the specifications for the outline in the “ESS_ATTRSPECS_T” on page
113 structure.
m You must set usCategory and usStorageCategory for an attribute member, as well as an
attribute dimension. (You need not set usCategory and usStorageCategory for a base
member. You must set them for a base dimension only.)
m Do not set the szDimName field of the ESS_MBRINFO_T structure.
m For a zero-level attribute member that is not of type ESS_ATTRMBRDT_STRING, do
not set the Attribute.value field of the “ESS_ATTRIBUTEVALUE_T” on page 113
structure. The attribute value is derived internally by converting the attribute member
long name.
737
m If you set an attribute member's data type to ESS_ATTRMBRDT_AUTO, Essbase does
the following:
o Sets the member's data type to the data type of its dimension, if the member name
can be converted to a value of that type.
o If the member name cannot be converted to a value of the dimension's data type,
sets the member's data type to ESS_ATTRMBRDT_NONE.
o For the first child member converted from ESS_ATTRMBRDT_AUTO to a data
type other than ESS_ATTRMBRDT_NONE, converts the parent's long name to a
short name.
l To add a dimension:
m To add an attribute dimension, call EssOtlAddDimension. Do not call
EssOtlAddMember.
m To add a dimension that is not an attribute dimension, call either
EssOtlAddDimension or EssOtlAddMember.
o EssOtlAddDimension gives you the benefit of selecting any member in the added
dimension to be assigned the data values associated with the existing dimensions.
o If EssOtlAddMember is used, the top member (dimension) of the added dimension
is assigned the data values associated with the existing dimensions.
Return Value
l OTLAPI_BAD_CONSOL
l OTLAPI_ERR_ADDNAMEUSED
738
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberProfit;
ESS_HMEMBER_T hNewMember;

Object.hCtx = hCtx;
sts = EssOtlOpenOutline(hCtx, &Object,

ESS_TRUE, ESS_TRUE, &hOutline);
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Profit",
&hMemberProfit);
}
if (!sts && hMemberProfit)
{
memset(&MbrInfo, '\0', sizeof(MbrInfo));
strcpy(MbrInfo.szMember, "Inventory");
sts = EssOtlAddMember(hOutline, &MbrInfo,
ESS_NULL, hMemberProfit, &hNewMember);
}
See Also
l EssOtlAddDimension
l EssOtlSetMemberInfo
l EssOtlFindMember
EssOtlAssociateAttributeDimension
Associates an attribute dimension with a standard or base dimension.
Syntax
739
hOutline; ESS_HOUTLINE_T Handle to the outline
hStandardDimension; ESS_HMEMBER_T Handle to the standard or base dimension
hAttributeDimension; ESS_HMEMBER_T Handle to the attribute dimension
Notes
l The attribute dimension must be sparse.

l The standard or base dimension must be sparse.
l You must associate an attribute dimension with a standard or base dimension.
l You can associate more than one attribute dimension with a base dimension.
l You cannot associate an attribute dimension with more than one base dimension.
Example
void ESS_OtlAssociateAttributeDimension()
{
ESS_HMEMBER_T hBaseMbr;
ESS_HMEMBER_T hAttrMbr;

Object.hCtx = hCtx;
sts = EssOtlOpenOutline(hCtx, &Object, ESS_TRUE, ESS_TRUE, &hOutline);

printf("EssOtlOpenOutline() sts: %ld\n",sts);
sts = EssOtlFindMember(hOutline, "Product", &hBaseMbr);

printf("EssOtlFindMember() sts: %ld\n",sts);
sts = EssOtlFindMember(hOutline, "Color", &hAttrMbr);

sts = EssOtlAssociateAttributeDimension(hOutline,hBaseMbr,hAttrMbr);
printf("EssOtlAssociateAttributeDimension() sts: %ld\n",sts);
sts = EssOtlWriteOutline(hOutline, &Object);
740
printf("EssOtlWriteOutline() sts: %ld\n",sts);
sts = EssOtlRestructure(hCtx, ESS_DOR_ALLDATA);

printf("EssOtlRestructure() sts: %ld\n",sts);
if (!sts)
{
while (!sts || (pState.State != ESS_STATE_DONE))
}
sts = EssOtlCloseOutline(hOutline);
printf("EssOtlCloseOutline() sts: %ld\n",sts);
}
See Also
l EssFreeStructure
EssOtlAssociateAttributeMember
Associates an attribute member with a standard or base member.
Syntax
hStandardMember; ESS_HMEMBER_T Handle to the standard or base member
hAttributeMember; ESS_HMEMBER_T Handle to the attribute member
Notes
741
l Before you associate an attribute member with a standard or base member using this
function, associate the dimension of the attribute member with the dimension of the
standard or base member using EssOtlAssociateAttributeDimension().
l You cannot associate an attribute member with a base dimension.
l Only a zero-level attribute member can associate with a standard or base member.
l You cannot associate members of a given attribute dimension with base members that are
at different levels from each other.
l You cannot associate more than one member of an attribute dimension with a base member.
l You can associate members of more than one attribute dimension with a base member.
Example
void ESS_OtlAssociateAttributeMember()
{

Object.hCtx = hCtx;



sts = EssOtlAssociateAttributeMember(hOutline,hBaseMbr,hAttrMbr);
printf("EssOtlAssociateAttributeMember() sts: %ld\n",sts);


if (!sts)
{
742
}
}
See Also
l EssFreeStructure
EssOtlClearAliasTable
Clears all entries from an existing alias table. The alias table is not deleted.
Syntax
ESS_FUNC_M EssOtlClearAliasTable (hOutline, pszAliasTable);
pszAliasTable; ESS_STR_T Name of alias table to clear. Use ESS_NULL or "Default" for the default table.
Notes
When clearing aliases from an alias table, language codes associated with the alias table are
removed.
Return Value
Returns 0 if successful; otherwise:
OTLAPI_BAD_ALIASTABLE
743
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;
sts = EssOtlOpenOutline(hCtx, &Object, ESS_TRUE,

ESS_TRUE, &hOutline);
if (!sts)
{
sts = EssOtlClearAliasTable(hOutline,
"Default");
}
See Also
l EssOtlCreateAliasTable
l EssOtlCopyAliasTable
l EssOtlRenameAliasTable
l EssOtlDeleteAliasTable
l EssOtlSetAliasTableLanguage
EssOtlClearAliasTableLanguages
Clears the set of language codes associated with the specified alias table.
Syntax
ESS_FUNC_M EssOtlClearAliasTableLanguages (hOutline, pszAliasTable);
hOutline ESS_HOUTLINE_T Outline context handle.
pszAliasTable ESS_STR_T Name of the alias table from which to remove all associated language codes.
Return Value
l If successful, returns 0.
744
l If unsuccessful, returns the error OTLAPI_BAD_ALIASTABLE (invalid alias table).
Access
This function does not require special privileges.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_PALIASLANG_T pLangs=ESS_NULL;
ESS_ULONG_T nLangs = 0, i=0;
memset(&NewInfo, '\0', sizeof(NewInfo));

sts = EssOtlNewOutline(hCtx, &NewInfo, &hOutline);
if (!sts)
{
sts = EssOtlCreateAliasTable(hOutline,
"French Alias Table");
}
if (!sts)
{
sts = EssOtlSetAliasTableLanguage (hOutline,
"French Alias Table", "fr");
}
if (!sts)
{
"French Alias Table", "fr-CA");
}
if (!sts)
{
sts = EssOtlGetAliasTableLanguages(hOutline, "French Alias Table", &nLangs,
&pLangs);
if ( !sts == ESS_STS_NOERR && ( pLangs) )

{
for (i=0;i<nLangs ;++i)
{
if (pLangs[i])
{
printf("Language Code: %s\n", pLangs[i]);
}
}
EssFree(hInst, pLangs);
}
}
if (!sts)
{
sts = EssOtlClearAliasTableLanguages (hOutline,
745
}
See Also
l EssOtlGetAliasTableLanguages
EssOtlCloseOutline
Frees all information associated with the outline.
Syntax
ESS_FUNC_M EssOtlCloseOutline (hOutline);
Notes
l This function should always be called if EssOtlNewOutline() or EssOtlOpenOutline() is
called.
l If the object was locked when it was opened, you should call EssUnlockObject() before
making this call.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

746
/* body of code */
if (!sts)
{
}
/* restructure db using EssOtlRestructure() */

if (!sts)
{
}
See Also
l EssOtlOpenOutline
l EssOtlWriteOutline
l EssOtlRestructure
EssOtlCompactOutline
Compacts an outline file that requires compacting at the client side.
Syntax
ESS_FUNC_M EssOtlCompactOutline (hCtx, filename);
hCtx ESS_HCTX_T API context acquired during login
filename ESS_STR_T Path and outline file to be compacted
Return Value
Returns 0 if successful. The compacted file is named the same with extension .otn and is available
in the path specified.
Example
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#pragma pack(push, api, 1)

#include <essapi.h>
#include <essotl.h>
#pragma pack(pop, api)
/* default names */
ESS_APPNAME_T app = "ASOSamp";
ESS_DBNAME_T db = "Sample";
747
int main(int argc, char *argv[ ])
{

ESS_HINST_T hInst = NULL;
ESS_HOUTLINE_T hOutlineQuery = NULL, hOutline = NULL;
ESS_HCTX_T hCtx = NULL;
ESS_USHORT_T Items;

/* structure */
{
(ESS_PVOID_T)0, /* user-defined message context */
NULL, //(ESS_STR_T)"C:\\Hyperion\\AnalyticServices", /* local
path */
NULL, //(ESS_PFUNC_T)MessageFunc, /* error handling function
pointer */
0L /* Reserved for internal use. */
/* Set to NULL */
#ifdef AD_UTF8
, ESS_API_UTF8
#endif
};
/* get appname and dbname from the argument list */

if (argc < 6) {
puts(" Usage: EssCompactOtl ServerName Userid Password AppName DbName
\n");
exit (0);
}
strcpy(srvrName, argv[1]);
strcpy(userName, argv[2]);
strcpy(pswd, argv[3]);
strcpy(app, argv[4]);
strcpy(db, argv[5]);
/* Initialize the Essbase API */

{
exit ((int) sts);
}
/* Login to Essbase */
748
if ((sts = EssLogin (hInst, srvrName, userName, pswd, &Items, &pAppsDbs,
&hCtx)) != ESS_STS_NOERR)
{
exit ((int) sts);
}
if(pAppsDbs)
/* Select the application */

if ((sts = EssSetActive(hCtx, app, db, &Access)) != ESS_STS_NOERR)
{
printf("EssSetActive failure: %ld\n", sts);
exit ((int) sts);
}
/* compact the outline and restructure */

if ((sts = EssCompactOutline(hCtx)) != ESS_STS_NOERR)
{
printf("EssCompactOutline failure: %ld\n", sts);
exit ((int) sts);
}
/* done, logout and terminate the api */

if ((sts = EssLogout (hCtx)) != ESS_STS_NOERR)
{
printf("EssLogout failure: %ld\n", sts);
exit ((int) sts);
}

{
exit((int) sts);
}
return(0);
}
EssOtlCopyAliasTable
Copies an alias table to another alias table.
Syntax
ESS_FUNC_M EssOtlCopyAliasTable (hOutline, pszSourceAliasTable, pszDestAliasTable,
fMerge);
pszSourceAliasTable ESS_STR_T Name of alias table to copy from. If this parameter is ESS_NULL, the default
alias table is used.
749
pszDestAliasTable ESS_STR_T Name of alias table to copy to. Cannot be the same as pszSourceAliasTable.
fMerge ESS_BOOL_T Set to ESS_TRUE to merge the source file into the existing destination alias
table. Set to ESS_FALSE to clear the destination alias table before copying.
Notes
l If the destination alias table does not exist, it is created. If the destination alias table exists,
it is cleared first, unless the fMerge flag is set to ESS_TRUE.
l The maximum number of alias tables in a single block storage or aggregate storage database
outline (including the default table) is 32.
l When copying an alias table, language codes associated with the alias table are removed from
the copied alias table.
Return Value
l OTLAPI_BAD_ALIASTABLE
l OTLAPI_ERR_MAXALIASTABLES
l OTLAPI_ERR_ALIASTABLENAME
l OTLAPI_ERR_COPYALIASTABLE: Source and destination tables are the same.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlCopyAliasTable(hOutline, ESS_NULL,
"Alias Table 2", ESS_TRUE);
}
750
See Also
l EssOtlClearAliasTable
EssOtlCreateAliasTable
Creates an empty alias table in the outline.
Syntax
ESS_FUNC_M EssOtlCreateAliasTable (hOutline, pszAliasTable);
pszAliasTable ESS_STR_T Name of alias table to create.
Notes
l An alias table named “Default” cannot be created, since the default alias table always exists.
l The maximum number of alias tables in a single block storage or aggregate storage database
outline (including the default table) is 32.
l You can specify multiple language codes for an alias table, using the
EssOtlSetAliasTableLanguage API. When you create an alias table, a language code is
not specified.
Return Value
OTLAPI_ERR_ALIASTABLEEXISTS
OTLAPI_ERR_MAXALIASTABLES
OTLAPI_ERR_ALIASTABLENAME
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

&hOutline);
if (!sts)
{
751
"Alias Table 1");
}
See Also
EssOtlCreateObject
Creates an object of the specified object type and name and returns the object handle.
Syntax
ESS_FUNC_M EssOtlCreateObject (hOutline, objType, name, phObjHandle)
hOutline ESS_HOUTLINE_T Outline handle (Edit mode only)
objType ESS_OBJECT_TYPES Object type with the following value:

OBJECT_SMARTLIST (Object type is Text List)
name ESS_STR_T String identifying the object
phObjHandle ESS_PHOBJECT_T Returns the created object handle.
Return Value
Returns:
l 0—If successful
Object created with handle in phObjHandle
No object created, and phObjHandle is NULL.
l OTLAPI_ERR_OBJTYPE_NOTSUPPORTED
If invalid object type is passed.
Example
void TestCreateObject()
{
ESS_OBJECT_TYPES objType;
ESS_STR_T smartListName;
ESS_HOBJECT_T ObjHandle;
ESS_ULONG_T Count, i;
ESS_PHOBJECT_T ObjHandles;
ESS_HOBJECT_T hObjHandle;
752
ESS_HSMARTLIST_T hSmartList;
ESS_STR_T objName;

Object.hCtx = hCtx;
/* Open outline */
/* Create a static SmartList */

objType = OBJECT_SMARTLIST;
smartListName = "SList1";
sts = EssOtlCreateObject(hOutline, objType,
smartListName, &ObjHandle);
/* List all SmartList objects */

sts = EssOtlListObjects(hOutline, objType,
&Count, &ObjHandles);
/* Free resources */
if(ObjHandles)
EssFree (hInst, ObjHandles);
/* Save */
SaveOutline(hOutline);
/* Find objects */
objName = "SList1";
sts = EssOtlFindObject(hOutline, objType, objName,
&hObjHandle);
/* Delete objects */
hSmartList = (ESS_HSMARTLIST_T)hObjHandle;
sts = EssOtlDeleteObject(hOutline, hSmartList);
if(ObjHandles)
/* Unlock objects */
sts = EssUnlockObject(hCtx, Object.ObjType,
Object.AppName, Object.DbName, Object.FileName);
/* Close outline */
}
See Also
l EssOtlGetMemberSmartList
l EssOtlCreateObject
753
l EssOtlDeleteObject
l EssOtlGetSmartListInfo
l EssOtlFindObject
l EssOtlFreeObjectArray
l EssOtlFreeSmartListInfo
l EssOtlGetMemberType
l EssOtlGetObjectReferenceCount
l EssOtlGetObjectReferences
l EssOtlImportExportObject
l EssOtlListObjects
l EssOtlQueryObjects
l EssOtlSetMemberType
l EssOtlSetMemberTypeToSmartList
EssOtlDeleteAliasTable
Deletes the specified alias table from the outline, clearing all of its entries.
Syntax
ESS_FUNC_M EssOtlDeleteAliasTable (hOutline, pszAliasTable);
pszAliasTable ESS_STR_T Name of alias table to delete.
Notes
You cannot delete the default alias table.
Return Value
OTLAPI_ERR_DELETEDEFALIAS
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;
754

if (!sts)
{
sts = EssOtlDeleteAliasTable(hOutline,
" Alias Table 1");
}
See Also
EssOtlDeleteDimension
Deletes a dimension from the outline. The call also specifies a member of the dimension being
deleted from which to keep data when the outline is restructured.
Syntax
ESS_FUNC_M EssOtlDeleteDimension (hOutline, hMember, pszDataMbr);
hMember ESS_HMEMBER_T Handle of member to delete.
pszDataMbr ESS_STR_T Member name in the dimension to be deleted from which data will be saved when
the outline is restructured. If this field is ESS_NULL, the dimension is used.
Notes
l All shared members of the dimension and its descendants are deleted.
l All members of the dimension are deleted.
l To delete a dimension, you can use this call or EssOtlDeleteMember().
EssOtlDeleteDimension() gives you the benefit of selecting a member of the deleted
dimension whose data values will be used as the data values for the other dimensions when
the database is restructured. If EssOtlDeleteMember() is used, the data values of the top
member (dimension) of the deleted dimension are used.
l In order for the pszDataMbr field to take effect, the outline must have been opened with
EssOtlOpenOutline() with the fKeepTrans flag set to ESS_TRUE.
755
Return Value
OTLAPI_ERR_ADDDELETEDIMDYNAMICCALC
OTLAPI_ERR_NOTIMEDIM
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberScenario;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Scenario",
&hMemberScenario);
}
if (!sts && hMemberScenario)

{
sts = EssOtlDeleteDimension(hOutline,
hMemberScenario, "Actual");
}
See Also
l EssOtlAddMember
l EssOtlFindMember
EssOtlDeleteDTSMemberAlias
Deletes an alias name for a Dynamic Time Series (DTS) member.
756
Syntax
ESS_STS_T EssOtlDeleteDTSMemberAlias (hOutline, pszDTSMember, pszAliasTable);
hOutline ESS_HOUTLINE_T The Essbase outline handle returned from the EssOtlOpenOutline call.
pszDTSMember ESS_STR_T Name of the DTS member which provides the alias.
pzsAliasTable ESS_STR_T Name of the alias table which provides the alias. If NULL, use the default alias
table.
Return Value
If successful the return value is zero. Otherwise, one of the following is returned:
l OTLAPI_ERR_DTSMBRNOTDEFINED
l OTLAPI_ERR_NOALIAS
Example
#include "essapi.h"
#include "essotl.h"
#include "esserror.h"
ESS_STS_T ESS_OtlDeleteDTSMemberAlias(ESS_HCTX_T hCtx)

{
ESS_STS_T sts =ESS_STS_NOERR;
ESS_CHAR_T pszAliasTable[ESS_ALIASNAMELEN];
ESS_CHAR_T pszDTSMember[ESS_MBRNAMELEN];
ESS_POUTERROR_T pMbrErrors = NULL;
strcpy(szAppName, "sample");
strcpy(pszDTSMember, "Q-T-D");
strcpy(pszAliasTable, "Default");
Object.hCtx = hCtx;
if(sts)
757
{
printf("Could not open outline\n");
return sts;
}
sts = EssOtlDeleteDTSMemberAlias(hOutline, pszDTSMember, pszAliasTable);

if(sts)
{
printf("Could not get DTS member alias\n");
return sts;
}

if(sts)
{
printf("Could not write outline\n");
return sts;
}

if(sts)
{
printf("Could not restructure outline\n");
return sts;
}
memset (&pState, 0, sizeof(ESS_PROCSTATE_T));

sts = EssGetProcessState(hCtx, &pState);
{
while ((sts == ESS_STS_NOERR ) && (pState.State != ESS_STATE_DONE))
{
}
}
sts = EssUnlockObject(hCtx, ESS_OBJTYPE_OUTLINE, szAppName, szDbName,

szFileName);
if (sts)
{
printf("Could not unlock outline\n");
return sts;
}
EssOtlCloseOutline(hOutline);
return sts;
}
See Also
l EssOtlEnableDTSMember
l EssOtlGetEnabledDTSMembers
l EssOtlGetDTSMemberAlias
l EssOtlSetDTSMemberAlias
758
EssOtlDeleteGenName
Deletes the name of a specific generation within a dimension.
Syntax
ESS_FUNC_M EssOtlDeleteGenName (hOutline, pszDimension, usGen);
pszDimension; ESS_STR_T Name of the dimension that contains the generation.
usGen ESS_USHORT_T Number of generation for which to delete name. Leaf members are level 0.
Return Value
OTLAPI_NO_GENLEVELNAME
OTLAPI_ERR_NOTADIM
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T Dimension;
ESS_USHORT_T GenNum;

Object.hCtx = hCtx;
/*********** Delete Generation Name ***********/
Dimension = "Year";
GenNum = 2;
if (!sts)
{
sts = EssOtlDeleteGenName(hOutline, Dimension,
GenNum);
}
759
See Also
l EssOtlGetGenName
l EssOtlSetGenName
EssOtlDeleteLevelName
Deletes the name for a specific level within a dimension.
Syntax
ESS_FUNC_M EssOtlDeleteLevelName (hOutline, pszDimension, usLevel);
pszDimension ESS_STR_T Name of the dimension that contains the level name.
usLevel ESS_USHORT_T Number of level for which to delete name. Leaf members are level 0.
Notes
In C programs, call EssFree() to free the returned buffer.
Return Value
OTLAPI_NO_GENLEVELNAME
OTLAPI_ERR_NOTADIM
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_USHORT_T LevelNum;

Object.hCtx = hCtx;
760
/********** Delete Level Name *************/

Dimension = "Year";
LevelNum = 2;
if (!sts)
{
sts = EssOtlDeleteLevelName(hOutline,
Dimension, LevelNum);
}
See Also
l EssOtlGetLevelName
l EssOtlSetLevelName
EssOtlDeleteObject
Deletes the object passed.
Syntax
ESS_FUNC_M EssOtlDeleteObject (hOutline, objHandle)
objHandle ESS_HOBJECT_T Object to be deleted
Notes
You cannot delete objects with existing associations. With Text List objects (SmartList objects),
you cannot delete the SmartList object without removing references—use the Get Object
References API to do so.
Return Value
Returns:
l 0—If successful
Example
{
761
ESS_STR_T objName;

Object.hCtx = hCtx;
/* Open outline */


/* Save */
/* Find objects */
objName = "SList1";
&hObjHandle);
if(ObjHandles)
/* Close outline */
}
See Also
l EssOtlFindObject
762
l EssOtlListObjects
EssOtlDeleteMember
Deletes a member from the outline.
Syntax
ESS_FUNC_M EssOtlDeleteMember (hOutline, hMember);
hMember ESS_HMEMBER_T Handle of member to delete.
Notes
l All descendants of the member are deleted.
l All shared members of this member and its descendants are deleted.
l If a shared member, only the specified member is deleted.
l To delete a dimension, you can use this call or EssOtlDeleteDimension().
EssOtlDeleteDimension() gives you the benefit of selecting a member of the deleted
dimension whose data values will be used as the data values for the other dimensions when
the database is restructured. If EssOtlDeleteMember() is used, the data values of the top
member (dimension) of the deleted dimension are used.
Return Value
OTLAPI_ERR_LEAFLABEL
OTLAPI_ERR_NOTIMEDIM
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hCOGS;
763

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "COGS", &hCOGS);
}
if (!sts && hCOGS)

{
sts = EssOtlDeleteMember(hOutline, hCOGS);
}
See Also
l EssOtlAddMember
l EssOtlFindMember
EssOtlDeleteMemberAlias
Deletes the default member alias for a specified member in a specified alias table.
Syntax
ESS_FUNC_M EssOtlDeleteMemberAlias (hOutline, hMember, pszAliasTable);
hMember ESS_HMEMBER_T Handle of member to delete the alias from.
pszAliasTable ESS_STR_T Alias table to delete the alias from. If this parameter is ESS_NULL, the default table
is used.
Return Value
764
OTLAPI_ERR_NOALIAS
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberJan;

Object.hCtx = hCtx;
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Jan",
&hMemberJan);
}
if (!sts && hMemberJan)
{
sts = EssOtlDeleteMemberAlias(hOutline,
hMemberJan, ESS_NULL);
}
See Also
l EssOtlGetMemberAlias
l EssOtlSetMemberAlias
EssOtlDeleteMemberFormula
Deletes the formula for the specified member.
Syntax
ESS_FUNC_M EssOtlDeleteMemberFormula (hOutline, hMember);
hMember ESS_HMEMBER_T Member handle.
765
Return Value
OTLAPI_ERR_NOFORMULA
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline,
"Variance", &hMember);
}
if (!sts && hMember)

}
sts = EssOtlDeleteMemberFormula(hOutline,
hMember);
}
See Also
l EssOtlSetMemberFormula
l EssOtlGetMemberFormula
EssOtlDeleteQueryHint
Deletes the query hint indicated by the input outline and hint number.
Hints are numbered from 1 to n. This function deletes the specified query hint and decreases
the number of hints with one. All hints with a hintNum greater than the deleted hint are
renumbered to hintNum - 1.
766
Syntax
ESS_FUNC_M EssOtlDeleteQueryHint (hOutline, hintNum);
hintNum ESS_SHORT_T Query hint number (input).
Notes
Return Value
Example
ESS_PMBRINFO_T pMemberInfo = ESS_NULL;
ESS_SHORT_T nmHints = 0;
ESS_SHORT_T i, j, hintNum;
ESS_HMEMBER_T hMember[10]; /* (nm real dimensions) < 10 */
/* Code to assign hOutline variable omitted */

/* Code to assign hintNum variable omitted */
sts = EssOtlGetNumQueryHints(hOutline, &nmHints);

if (sts) return sts; /* error out */
if (hintNum <= nmHints)

{
sts = EssOtlDeleteQueryHint(hOutline, hintNum);
if (sts)
printf("Error [%s] deleting query hint (%d)\n", sts, hintNum);
else
printf("Query-Hint number: (%d) deleted\n", hintNum);
}
else
{
printf("Query-Hint number: (%d) does not exist\n", hintNum);
}
See Also
l EssOtlAddQueryHint
767
EssOtlDeleteUserAttribute
Deletes a user-defined attribute of a member.
Syntax
ESS_FUNC_M EssOtlDeleteUserAttribute (hOutline, hMember, pszString);
hOutline ESS_HOUTLINE_T Outline context handle
hMember ESS_HMEMBER_T Handle of member that contains the attribute you are deleting
pszString ESS_STR_T User attribute string.
Notes
The caller passes in a string to identify the attribute.
Return Value
OTLAPI_NO_USERATTR.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T AttributeList;

Object.hCtx = hCtx;

/******** Delete User Attributes *********/
AttributeList = "Read Write";
if (!sts)
768
{
&hMember);
}

{
sts = EssOtlDeleteUserAttribute(hOutline,
hMember, AttributeList);
}
See Also
l EssOtlGetUserAttributes
l EssOtlSetUserAttribute
EssOtlDetailQueryAttributes
Not specific to varying attributes, but similar to EssOtlQueryVaryingAttributes, except that the
results provide specific associated attributes in pphDetailMemberArray.
Syntax
ESS_FUNC_M EssOtlDetailQueryAttributes (
ESS_HOUTLINE_T hOutline,
ESS_PATTRIBUTEQUERY_T pAttrQuery,
ESS_PMBRCOUNTS_T pCount,
ESS_PPHMEMBER_T pphReturnedMemberArray,
ESS_PPHMEMBER_T pphDetailMemberArray)
hOutline ESS_HOUTLINE_T Outline context handle (input)
pAttrQuery ESS_PATTRIBUTEQUERY_T Pointer to the structure that defines the query
pCount ESS_PMBRCOUNTS_T Pointer to the number of base members returned
pphReturnedMemberArray ESS_PPHMEMBER_T Pointer to the array of returned member handles
pphDetailMemberArray ESS_PPHMEMBER_T Pointer to the array of member details
Return Value
Returns:
l 0—If successful
See Also
l EssOtlQueryVaryingAttributes
769
EssOtlDetailQueryVaryingAttributes
Similar to EssOtlQueryVaryingAttributes, except that the results provide the specific associated
attributes in pphDetailMemberArray.
Syntax
ESS_FUNC_M EssOtlDetailQueryVaryingAttributes(
ESS_PVARYING_ATTRIBUTEQUERY_T pAttrQuery,
ESS_PPERSPECTIVE_T pPerspective,
ESS_PMBRCOUNTS_T pCount,
ESS_PPHMEMBER_T pphMembers,
ESS_PPHMEMBER_T pphDetailMemberArray,
ESS_USHORT_T usValiditySetType,
ESS_PVALIDITYSET_T **pppValiditySets);
pAttrQuery ESS_PVARYING_ATTRIBUTEQUERY_T Pointer to the structure that defines the query
pPerspective ESS_PPERSPECTIVE_T Pointer to a collection of independent members

used when querying the client or server for
associations
pCount ESS_PMBRCOUNTS_T Pointer to the number of base members returned
pphMembers ESS_PPHMEMBER_T Pointer to the array of attribute member handles
pphDetailMemberArray ESS_PPHMEMBER_T Pointer to the array of attribute member detail

handles
usValiditySetType ESS_USHORT_T See “ESS_VALIDITYSET_T” on page 720.
**pppValiditySets ESS_PVALIDITYSET_T Pointer to the validity set array
Return Value
Returns:
l 0—If successful
Example
void TestEssOtlDetaileQueryVaringAttributes()
{
ESS_USHORT_T i = 0;
ESS_PMBRINFO_T pMbrInfo = ESS_NULL;
ESS_VARYING_ATTRIBUTEQUERY_T pAttrQuery;
ESS_MBRCOUNTS_T Counts;
ESS_USHORT_T usValiditySetType;
ESS_HMEMBER_T hIndepMbrHandlesArray[4];
770
ESS_PERSPECTIVE_T Perspective;
ESS_PHMEMBER_T phMbrHandles = ESS_NULL;
ESS_PHMEMBER_T phDetailedMembers = ESS_NULL;
ESS_PVALIDITYSET_T *pValiditySets = ESS_NULL;
ESS_HMEMBER_T hAttrMbr, hBaseMbr;
ESS_HMEMBER_T hAttrDim;
ESS_PREDICATE_T Predicate;
memset(&Object, '\0', sizeof(ESS_OBJDEF_T));

memset(&Counts, '\0', sizeof(ESS_MBRCOUNTS_T));
memset(&pAttrQuery, 0x00, sizeof(ESS_ATTRIBUTEQUERY_T));
memset(&Predicate, '\0', sizeof(ESS_PERSPECTIVE_T));
Object.hCtx = hCtx;
Object.FileName = szDbName;
sts = EssOtlOpenOutlineQuery(hCtx, &Object, &hOutline);
printf("EssOtlOpenOutlineQuery sts: %ld\n",sts);
Counts.ulStart = 0;
Counts.ulMaxCount = 10;
Predicate.ulQuery = ESS_SEARCH;
Predicate.ulOptions = ESS_MEMBERSONLY;
Predicate.pszDimension = "";
Predicate.pszString2 = "";
/* Get handles for attribute member and dimension */

Predicate.pszString1 = "Type";
sts = EssOtlQueryMembersByName(hOutline, ESS_NULL, &Predicate, &Counts,
&phMbrHandles);
hAttrDim = phMbrHandles[0];
Predicate.pszString1 = "Contractor";
&phMbrHandles);
hAttrMbr = phMbrHandles[0];
Predicate.pszString1 = "Doe,Jane";
&phMbrHandles);
hBaseMbr = phMbrHandles[0];
/* Get handles for independent members */

Predicate.pszString1 = "Jan";
&phMbrHandles);
hIndepMbrHandlesArray[0] = phMbrHandles[0];
Predicate.pszString1 = "FY03";
&phMbrHandles);
771
&phMbrHandles);
memset(&Perspective, '\0', sizeof(ESS_PERSPECTIVE_T));

Perspective.usValiditySetType = ESS_VALIDITYSET_TYPE_MBRHDLS;
Perspective.countOfIndepDims = 2;
Perspective.countOfIndepRanges = 1;
Perspective.pIndepMbrs = hIndepMbrHandlesArray;
/* Query by handle with InputMemberType of ESS_ATTRIBUTE_MEMBER and OutputMemberType

of ESS_BASE_MEMBER*/
printf("\n*** Query by handle with InputMemberType of ESS_ATTRIBUTE_MEMBER and
OutputMemberType of ESS_BASE_MEMBER:\n");
pAttrQuery.bInputMemberIsHandle = ESS_TRUE;
pAttrQuery.uInputMember.hMember = hAttrMbr;
pAttrQuery.usInputMemberType = ESS_ATTRIBUTE_MEMBER;
pAttrQuery.usOutputMemberType = ESS_BASE_MEMBER;
pAttrQuery.Attribute.usDataType = ESS_ATTRMBRDT_NONE;
pAttrQuery.usOperation = ESS_ALL;
usValiditySetType = ESS_VALIDITYSET_TYPE_MBRHDLS;
sts = EssOtlDetailQueryVaryingAttributes(hOutline, &pAttrQuery, &Perspective,
&Counts,
&phMbrHandles, &phDetailedMembers, usValiditySetType,
&pValiditySets);
printf("EssOtlDetailQueryVaryingAttributes sts: %d\n", sts);
if (!sts)
{
if (phMbrHandles)
{
printf("\tReturned member:\n");
GetMemberInfo(hOutline, Counts, phMbrHandles);
if(Counts.ulReturnCount && phMbrHandles)
sts = EssOtlFreeMembers(hOutline, Counts.ulReturnCount, phMbrHandles);
}
if(phDetailedMembers)
{
printf("\tAssociated attribute member:\n");
GetMemberInfo(hOutline, Counts, phDetailedMembers);
if (Counts.ulReturnCount && phDetailedMembers)
sts = EssOtlFreeMembers(hOutline, Counts.ulReturnCount,
phDetailedMembers);
}
}
sts = EssUnlockObject(hCtx, ESS_OBJTYPE_OUTLINE, Object.AppName, Object.DbName,

Object.FileName);
printf("\nEssUnlockObject sts: %d\n", sts);
printf("EssOtlCloseOutline sts: %d\n",sts);
}
See Also
772
EssOtlDisassociateAttributeDimension
Disassociates an attribute dimension from a base dimension.
Syntax
hBaseDimension; ESS_HMEMBER_T Handle to the base dimension
hAttributeDimension; ESS_HMEMBER_T Handle to the attribute dimension
Notes
When you dissassociate an attribute dimension from a base dimension, you disassociate all
members of the attribute dimension from members of the base dimension.
Example
void ESS_OtlDisassociateAttributeDimension()
{

Object.hCtx = hCtx;



sts = EssOtlDisassociateAttributeDimension(hOutline,hBaseMbr,hAttrMbr);
printf("EssOtlDisassociateAttributeDimension() sts: %ld\n",sts);

773
if (!sts)
{
}
}
See Also
l EssFreeStructure
EssOtlDisassociateAttributeMember
Disassociates an attribute member from a base member.
Syntax
ESS_FUNC_M EssOtlDisassociateAttributeMember (hOutline, hBaseMember, hAttributeMember);
hBaseMember; ESS_HMEMBER_T Handle to the base member
hAttributeMember; ESS_HMEMBER_T Handle to the attribute member
Notes
When you disassociate an attribute dimension from a base dimension, you disassociate all
members of the attribute dimension from members of the base dimension.
774
Example
void ESS_OtlDisassociateAttributeMember()
{

Object.hCtx = hCtx;



sts = EssOtlDisassociateAttributeMember(hOutline,hBaseMbr,hAttrMbr);
printf("EssOtlDisassociateAttributeMember() sts: %ld\n",sts);


if (!sts)
{
}
}
See Also
l EssFreeStructure
775
EssOtlEnableDTSMember
Enables a new DTS member for the outline.
Syntax
ESS_FUNC_M EssOtlEnableDTSMember (hOutline, pszDTSMember,
usGen, bEnable);
hOutline; ESS_HOUTLINE_T The Essbase outline handle returned from the EssOtlOpenOutline call.
pszDTSMember; ESS_STR_T Name of the DTS member
usGen; ESS_USHORT _T Generation to assign to the DTS member
bEnable; ESS_BOOL_T Flag to enable the DTS member
Notes
This function also fills in the ESS_DTSMBRNAME_T structure passed to it.
Return Value
Returns zero if successful.
Example
#include "essapi.h"
#include "essotl.h"
ESS_STS_T ESS_OtlEnableDTSMember(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
776
strcpy(szAppName, "1Sample");

Object.hCtx = hCtx;

if(sts)
{
return sts;
}
sts = EssOtlEnableDTSMember(hOutline, "H-T-D", 1, ESS_TRUE);

if(sts)
{
printf("Could not enable DTS member alias\n");
}
sts = EssOtlVerifyOutline(hOutline, &ulErrors, &ulCount, &pMbrErrors);

if(sts)
{
printf("Could not verify outline\n");
return sts;
}

if(sts)
{
return sts;
}

if(sts)
{
return sts;
}

{
printf("sts from Proc State is %d and ProcState is %d\n", sts,
pState.State);
while ((sts == ESS_STS_NOERR) && (pState.State != ESS_STATE_DONE))
{
777
printf("sts from Proc State is %d and ProcState is %d\n", sts,
pState.State);
}
}
EssUnlockObject(hCtx, Object.ObjType, Object.AppName, Object.DbName,

Object.FileName);
return sts;
}
See Also
l EssOtlDeleteDTSMemberAlias
EssOtlFindAlias
Finds a member with the specified alias name and returns a handle to the member.
Syntax
ESS_FUNC_M EssOtlFindAlias (hOutline, pszAlias, pszAliasTable, phMember);
pszAlias ESS_STR_T Alias name to find. Can be a simple alias name or a qualified alias name
(distinguishing this member from another member having the same name). For
information about syntax used to specify a qualified alias name, see the Oracle
Essbase Database Administrator's Guide section entitled "Creating and Working
With Duplicate Member Outlines."
pszAliasTable ESS_STR_T Alias table to search in. Use ESS_NULL to search all alias tables. Use "Default" to
search the default alias table.
phMember ESS_PHMEMBER_T Variable for the return of the member handle. ESS_NULL if the member is not
found.
Notes
Aliases used in alias combinations are also searched.
Return Value
Returns 0 if successful. If no member is found, *phMember is set to ESS_NULL and the call
returns 0.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
778
ESS_HMEMBER_T hMemberAlias;
Object.hCtx = hCtx;
if (!sts)
{
/* search all alias tables */
sts = EssOtlFindAlias(hOutline, "Colas",
ESS_NULL, &hMemberAlias);
}
See Also
l EssOtlGetOutlineInfo
EssOtlFindAttributeMembers
Returns all attribute members having the specified short name.
Syntax
pszMember; ESS_STR_T Attribute short name
pszDimName; ESS_STR_T Attribute dimension name (optional)
pusCount; ESS_PUSHORT_T Number of base members returned
pphMembers; ESS_PPHMEMBER_T Pointer to an array of base member handles
Notes
l pszMember must be a short name.

l pszDimName is optional. You may enter NULL.
779
Example
void ESS_OtlFindAttributeMembers()
{
ESS_SHORT_T index;
ESS_USHORT_T count;
ESS_PPHMEMBER_T phMember;
ESS_PPMBRINFO_T phMemberInfo;
ESS_MBRNAME_T mbrName;

Object.hCtx = hCtx;

/* Returning an array of member handles? */

sts = EssOtlFindAttributeMembers(hOutline,"12", "", &count, &phMember);
/* sts = EssOtlFindAttributeMembers(hOutline,"10-01-1996", "", &count, &phMember); */
printf("EssOtlFindAttributeMembers() sts: %ld\n",sts);
/* Allocate memory for an array of memberinfo struct handles */
sts = EssAlloc(hInst,count * (sizeof(ESS_HMEMBER_T)), (ESS_PPVOID_T)&phMemberInfo);
if (!sts)
{
for(index = 0; index < count; index++)
{
/* Step through array of member handles, and assign member */
sts = EssOtlGetMemberInfo(hOutline,phMember[index],&phMemberInfo[index]);
printf("EssOtlGetMemberInfo() sts: %ld\n",sts);
strcpy(mbrName,phMemberInfo[index]->szMember);
printf("Attribute member name #%d is: %s\n",(index + 1),mbrName);
}
EssFree(hInst, phMember);
EssFree(hInst, phMemberInfo);
}
}
See Also
l EssFreeStructure
780
EssOtlFindMember
Finds a member with the specified name and returns a handle to the member.
Syntax
ESS_FUNC_M EssOtlFindMember (hOutline, pszMember, phMember);
pszMember ESS_STR_T Member name to find. Can be a simple member name or a qualified member name
(distinguishing this member from another member having the same name). For
information about syntax used to specify a qualified member name, see the Oracle
Essbase Database Administrator's Guide section entitled "Creating and Working
With Duplicate Member Outlines."
phMember ESS_PHMEMBER_T Variable for the return of the member handle. ESS_NULL if the member is not
found.
Notes
l If the target member has shared members, only the handle to the actual member is returned.
l Once you have the member handle to the actual member, use
EssOtlGetNextSharedMember() to get shared member information.
l If no member is found, *phMember is set to ESS_NULL and the call returns 0.
l Whenever you use EssOtlFindMember(), always perform two checks:
1. Check the return status.
2. Check whether the handle was returned.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
781
ESS_HMEMBER_T hDimProduct;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Product",
&hDimProduct);
}
See Also
l EssOtlMoveMember
l EssOtlRenameMember
l EssOtlAddMember
l EssOtlGetNextSharedMember
EssOtlFindObject
Returns the object handle of the specified type and name.
Syntax
ESS_FUNC_M EssOtlFindObject(hOutline, objType, objName, pObjHandle)

objName ESS_STR_T String identifying the object
phObjHandle ESS_PHOBJECT_T Returns the found object handle.
782
Return Value
Returns:
l 0—If successful
phObjHandle contains the object handle.
phObjHandle in NULL.
Example
{
ESS_STR_T objName;

Object.hCtx = hCtx;
/* Open outline */


/* Save */
/* Find objects */
objName = "SList1";
&hObjHandle);
783
if(ObjHandles)
/* Close outline */
}
See Also
l EssOtlFindObject
l EssOtlListObjects
EssOtlFreeMembers
Frees the member array returned from EssOtlQueryMembers().
Syntax
ESS_FUNC_M EssOtlFreeMembers (hOutline, ulCount, phMembers);
hOutline ESS_HOUTLINE_T Essbase outline handle. This must have been returned from
EssOtlOpenOutlineQuery().
ulCount ESS_ULONG_T The number of elements in the phMember array.
phMembers ESS_PHMEMBER_T An array of member handles to be freed.
Return Value
The return value is zero if the function was successful.
784
Example
See the example for EssOtlQueryMembers.
See Also
l EssOtlOpenOutlineQuery
l EssOtlQueryMembers
l EssOtlQueryMembersByName
EssOtlFreeSmartListInfo
Frees the Text List (SmartList) object obtained by EssOtlGetSmartListInfo.
Syntax
ESS_FUNC_M EssOtlFreeSmartListInfo(hOutline, pSmartListInfo);
hOutline ESS_HOUTLINE_T The source Essbase outline for the Text List (SmartList).
pSmartListInfo ESS_PSMARTLISTINFO_T Text List (SmartList) information.
Return Value
Returns:
l 0—If successful
Example
DisplaySmartListInfo(ESS_HOUTLINE_T hOutline, ESS_PHOBJECT_T ObjHandles)
{
ESS_PSMARTLISTINFO_T SmartListInfo;
ESS_ULONG_T i;
sts = EssOtlGetSmartListInfo(hOutline, ObjHandles,

&SmartListInfo);
if(!sts)
{
printf("\n");
printf("\tName: %s\n", SmartListInfo->szName);
printf("\tMissing Name: %s\n",
SmartListInfo->szMissingName);
printf("\tOut of Range Name: %s\n",
SmartListInfo->szOutOfRangeName);
printf("\tusLen: %d\n", SmartListInfo->usLen);
for (i = 0; i < SmartListInfo->usLen; i++)
{
printf("\tpIDs: %d, \tpszText[%d]: %s\n",
SmartListInfo->pIDs[i], i,
SmartListInfo->ppszText[i]);
}
785
printf("\n");
}
else
printf("\t\tEssOtlGetSmartListInfo sts: %d\n",sts);
if(SmartListInfo)
sts =
EssOtlFreeSmartListInfo(hOutline, SmartListInfo);
See Also
l EssOtlFindObject
l EssOtlListObjects
EssOtlFreeObjectArray
Deallocates the object handle array.
Syntax
ESS_FUNC_M EssOtlFreeObjectArray(hOutline, count, objHandles)
hOutline ESS_HOUTLINE_T Outline handle (Query mode only)
count ESS_ULONG_T Count of object handles
objHandles ESS_PHOBJECT_T Array of object handles to be de allocated
Return Value
Returns:
l 0—If successful
786
Example
void TestFreeObjectArray()
{
ESS_STR_T objNames[1];
ESS_ULONG_T count;
ESS_PHOBJECT_T hObjHandles = ESS_NULL;

Object.hCtx = hCtx;
/* Set up */
count = 2;
objNames[0] = "Smartlist1";
/* Query objects */
sts = EssOtlQueryObjects(hOutline, objType,
objNames, &Count, &hObjHandles);
/* Free object array */

if(hObjHandles)
{
sts = EssOtlFreeObjectArray(hOutline, count,
hObjHandles);
}
/* Close outline */
}
See Also
l EssOtlFindObject
787
l EssOtlListObjects
EssOtlFreeStructure
Frees memory dynamically allocated by EssOtlGetAttributeInfo() and
EssOtlGetMemberInfo() for string type attribute information.
Syntax
structId; ESS_ULONG_T One of the following constant identifiers for the structure:
l ESS_DT_STRUCT_ATTRIBUTEINFO
l ESS_DT_STRUCT_ATTRSPECS
l ESS_DT_STRUCT_MBRINFO
l ESS_DT_STRUCT_TIGENINFO
count; ESS_ULONG_T Number of structures
structPtr; ESS_PVOID_T Pointer to memory
Notes
Always call this function, EssOtlFreeStructure(), after you call EssOtlGetMemberInfo().
Example
void ESS_OtlGetAssociatedAttributes()
{
ESS_SHORT_T index;
ESS_USHORT_T count;
ESS_PPHMEMBER_T hMember;

Object.hCtx = hCtx;
788

sts = EssOtlFindMember(hOutline, "100-10", &hMember);

sts = EssOtlGetAssociatedAttributes(hOutline, hMember, &count, &phMember);

printf("EssOtlGetAssociatedAttributes() sts: %ld\n",sts);
/* Allocate memory for an array of memberinfo structs */

sts = EssAlloc(hInst,count * (sizeof(ESS_MBRINFO_T)), (ESS_PPVOID_T)&phMemberInfo);
if (!sts)
{
{
printf("Associated attribute member name #%d is: %s\n",(index + 1),mbrName);
}
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1, phMemberInfo);
}
printf("\n Attributes associated :%ld\n\n", count);

}
See Also
l EssFreeStructure
EssOtlGenerateCurrencyOutline
Generates a currency outline based on the existing outline.
789
Syntax
ESS_FUNC_M EssOtlGenerateCurrencyOutline (hOutline, phCurOutline);
phCurOutline ESS_PHOUTLINE_T Pointer to an outline context handle for the return of the currency outline.
Notes
l The source outline must have a Time, Accounts, and Country dimension.
l Time dimension and all descendants are copied directly from the source outline to a Time
dimension in the new outline.
l A dimension named CurCategory (Dense, Category = Accounts) is created in the new
outline. All currency categories in the source Accounts dimension become children of the
CurCategory dimension in the new outline.
l A dimension named CurName (Dense, Category = Country) is created in the new outline.
All currency names from the source Country dimension become children of the CurName
dimension in the new outline.
l A dimension named CurType (Sparse, Category = Type) is created with no children in the
new outline.
l The currency outline must be saved by calling EssOtlWriteOutline() followed by
EssOtlRestructure() and closed by calling EssOtlCloseOutline().
l The new outline has the following attributes:
m Auto-configure is set to ESS_TRUE
m Case-sensitivity is the same as the original outline
Return Value
l OTLAPI_ERR_ALREADYCURRENCY
l OTLAPI_CUR_NOACCOUNTS
l OTLAPI_CUR_NOTIME
l OTLAPI_CUR_NOCOUNTRY
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HOUTLINE_T hCurOutline;
790
Object.hCtx = hCtx;
strcpy(szDbName, "Interntl");
strcpy(szFileName, "Interntl");

if (!sts)
{
sts = EssOtlGenerateCurrencyOutline(hOutline,
&hCurOutline);
}
See Also
l EssOtlOpenOutline
l EssOtlRestructure
EssOtlGetAggLevelUsage
Returns the applied view selection properties on stored hierarchies.
Syntax
ESS_FUNC_M EssOtlGetAggLevelUsage (hOutline, hMember, pAgglevelUsage);
hMember ESS_HMEMBER_T Member handle (input).
pAgglevelUsage ESS_PSHORT_T One of the Level Usage Constants listed in EssOtlSetAggLevelUsage

documentation (output).
Notes
This function is applicable only to Release 9.3 or higher aggregate storage databases.
Return Value
Example
ESS_HMEMBER_T hMember = ESS_NULL;
ESS_SHORT_T sAggLevelUsage = 0;
791
/* code to assign hMember variable omitted */
if (hOutline && hMember)

{
sts = EssOtlGetAggLevelUsage (hOutline, hMember, &sAggLevelUsage);
if (sts)
printf("Error (%ld) getting AggLevelUsage\n", sts);
else
printf("AggLevelUsage is: %d ", sAggLevelUsage);
switch (sAggLevelUsage)
{
case ESS_AGGLEVELUSAGE_NOTSET :
printf("(not set)\n");
break;
case ESS_AGGLEVELUSAGE_DEFAULT :
printf("(Default)\n");
break;
case ESS_AGGLEVELUSAGE_ALL :
printf("(All levels considered)\n");
break;
case ESS_AGGLEVELUSAGE_NOAGGREGATION :
printf("(Do not aggregate)\n");
break;
case ESS_AGGLEVELUSAGE_BOTTOMONLY :
printf("(Bottom level only considered)\n");
break;
case ESS_AGGLEVELUSAGE_TOPONLY :
printf("(Top level only considered)\n");
break;
case ESS_AGGLEVELUSAGE_BOTTOMTOP :
printf("(Never aggregate intermediate levels)\n");
break;
case ESS_MULTIPLE_HIERARCHY_IS_ENABLED :
printf("(Error: Multiple hierarchies - hierarchy members are gen=2)\n");
break;
case ESS_MULTIPLE_HIERARCHY_NOT_ENABLED :
printf("(Error: Single hierarchy - hierarchy member is gen=1)\n");
break;
case ESS_NOT_HIERARCHY_MEMBER :
printf("(Error: This member does not carry agglevel information)\n");
break;
default: printf("(Unrecognized response)\n");
}
}
else
{
if (!hOutline)
if (!hMember)
printf("Member not provided\n");
}
See Also
l EssOtlSetAggLevelUsage
792
EssOtlGetAliasTableLanguages
Returns an array of language codes, and the number of language codes in the array, that are
associated with the specified alias table.
Syntax
ESS_FUNC_M EssOtlGetAliasTableLanguages (hOutline, pszAliasTable, pulCount, ppLangArray);
hOutline ESS_HOUTLINE_T Handle to the outline.
pszAliasTable ESS_STR_T Name of the alias table for which to get the associated language codes.
pulCount ESS_PULONG_T Address of a variable in which to return the number of language codes
associated with the alias table.
ppLangArray ESS_PPALIASLANG_T An array of the language codes associated with the alias table specified in
pszAliasTable.
The memory allocated for ppLangArray should be freed using EssFree().
Return Value
l If unsuccessful, returns the error OTLAPI_BAD_ALIASTABLE (invalid alias table).
Access
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

if (!sts)
{
}
if (!sts)
{
}
793
if (!sts)
{
}
if (!sts)
{
&pLangs);

{
{
if (pLangs[i])
{
}
}
}
}
if (!sts)
{
}
See Also
l EssOtlClearAliasTableLanguages
EssOtlGetAltHierarchyEnabled
Returns the dimension's multiple-hierarchy-enabled setting.
Syntax
ESS_FUNC_M EssOtlGetAltHierarchyEnabled(hOutline, hDimMember, pEnabled);
hDimMember ESS_HMEMBER_T A dimension member (input).
pEnabled ESS_BOOL_T Returns TRUE if the dimension is multiple hierarchy enabled, and FALSE
otherwise.
Return Value
l 0—If successful
l Returns error OTLAPI_ERR_BADDIM if hDimMember is not a dimension member.
794
See Also
l EssOtlSetAltHierarchyEnabled
l EssOtlGetHierarchyType
l EssOtlSetHierarchyType
EssOtlGetASOCompressionDimension
Returns the handle of the aggregate storage dimension tagged as Compression.
Syntax
ESS_FUNC_M EssOtlGetASOCompressionDimension (hOutline, phDim);
phDim ESS_PHMEMBER_T Pointer to a dimension handle (output).
Notes
By default, the compression dimension in aggregate storage databases is the Accounts dimension.
To change the compression dimension, use EssOtlSetASOCompressionDimension. Changing
the compression dimension triggers a full restructure of the database.
Return Value
Example
ESS_PMBRINFO_T pMemberInfo = ESS_NULL;
if (hOutline)
{
sts = EssOtlGetASOCompressionDimension(hOutline, &hMember);
if (!sts)
{
if (hMember)
{
sts = EssOtlGetMemberInfo(hOutline, hMember, &pMemberInfo);
printf("\The ASO compression dimension is: %s\n", pMemberInfo->szMember);
}
else
{
printf("Outline has no dimension selected for compression\n");
}
}
else
{
795
printf("Error returned\n");
}
}
else
{
printf("NULL outline selected");
}
See Also
l EssOtlSetASOCompressionDimension
EssOtlGetAssociatedAttributes
Returns all attribute members that are associated with a base member or dimension.
Syntax
ESS_FUNC_M EssOtlGetAssociatedAttributes(hOutline,hMember,
pusCount,pphMemberArray);
hMember; ESS_HMEMBER_T Handle to the base member or base dimension
pusCount; ESS_PUSHORT_T Number of attribute members returned
pphMemberArray; ESS_PPHMEMBER_T Pointer to an array of attribute member handles
Example
void ESS_OtlGetAssociatedAttributes()
{
ESS_SHORT_T index;
ESS_USHORT_T count;
ESS_PPHMEMBER_T hMember;

Object.hCtx = hCtx;
796

sts = EssOtlFindMember(hOutline, "100-10", &hMember);

sts = EssOtlGetAssociatedAttributes(hOutline, hMember, &count, &phMember);

printf("EssOtlGetAssociatedAttributes() sts: %ld\n",sts);
/* Allocate memory for an array of memberinfo struct handles */

sts = EssAlloc(hInst,count * (sizeof(ESS_HMEMBER_T)), (ESS_PPVOID_T)&phMemberInfo);
if (!sts)
{
{
printf("Associated attribute member name #%d is: %s\n",(index + 1),mbrName);
}
EssFree(hInst, phMemberInfo);
}
printf("\n Attributes associated :%ld\n\n", count);

}
See Also
l EssFreeStructure
EssOtlGetAttributeAssocLevel
Gets the association level for an attribute or linked attribute dimension.
797
Every attribute has an association level and an attachment level associated with the attribute
dimension definition. For a linked attribute dimension, the association level is always the shorter
of the two periods in the periodic comparison represented by the linked attribute dimension.
For example, in the linked attribute dimension Quarter by Year, Quarter is the association level,
and Year is the attachment level.
Syntax
ESS_FUNC_M EssOtlGetAttributeAssocLevel (hOutline, hDimMember, psLevel);
hDimMember ESS_HMEMBER_T Attribute or linked-attribute dimension member handle (input).
psLevel ESS_PUSHORT_T The attribute association level (output).
Notes
l Before you call this function, open the outline in edit or query mode using either
EssOtlOpenOutline or EssOtlOpenOutlineQuery.
l This function is applicable when hDimMember is any type of attribute dimension.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER hDimMember;
ESS_USHORT_T usAssocLevel;

Object.hCtx = hCtx;

if (!sts)
{
798
sts = EssOtlFindMember(hOutline, "Quarter By Year",
&hDimMember);
}

{
sts = EssOtlGetAttributeAssocLevel(hOutline,
hDimMember, &usAssocLevel);
See Also
l EssOtlGetLinkedAttributeAttachLevel
l EssOtlQueryGenerationInfo
EssOtlGetAttributeInfo
Returns attribute information for a given attribute member or dimension.
Syntax
hAttribute; ESS_HMEMBER_T Handle to the attribute member or dimension
pAttributeInfo; “ESS_ATTRIBUTEINFO_T” on page 112 Attribute information
Notes
l This function is similar to EssGetAttributeInfo().

l After you call this function, call EssOtlFreeStructure() to free memory dynamically allocated
by EssOtlGetAttributeInfo() for string type attribute information.
Example
void ESS_GetAttributeInfo()
{
ESS_PPATTRIBUTEINFO_T pAttributeInfo = ESS_NULL;

Object.hCtx = hCtx;
799
sts = EssOtlFindMember(hOutline, "100-10", &hmember);

sts = EssOtlGetAttributeInfo(hOutline, hMember, &pAttributeInfo);

if (sts == ESS_STS_NOERR && pAttributeInfo)
{
printf("\n------Attribute Information------\n");
printf("Member name: %s\n", pAttributeInfo->MbrName);
printf("Dim name: %s\n", pAttributeInfo->DimName);
switch(pAttributeInfo->Attribute.usDataType)
{
case (ESS_ATTRMBRDT_STRING):
printf("Attribute data type: Text\n");
if(pAttributeInfo->Attribute.value.strData)
printf("Attribute value: %s\n",pAttributeInfo-
>Attribute.value.strData);
break;
case (ESS_ATTRMBRDT_BOOL):
printf("Attribute data type: Boolean\n");
printf("Attribute value: %d\n",pAttributeInfo-
>Attribute.value.bData);
break;
case (ESS_ATTRMBRDT_DOUBLE):
printf("Attribute data type: Numeric\n");
printf("Attribute value: %f\n",pAttributeInfo-
>Attribute.value.dblData);
break;
case (ESS_ATTRMBRDT_DATETIME):
printf("Attribute data type: Date\n");
printf("Attribute value: %s\n",ctime(&pAttributeInfo-
>Attribute.value.dtData));
break;
case (ESS_ATTRMBRDT_NONE):
printf("Attribute data type: None\n");
break;
default:
printf("Attribute data type: \n");
break;
}
}
}
800
See Also
l EssFreeStructure
EssOtlGetAttributeSpecifications
Retrieves attribute specifications for the outline.
Syntax
pAttrSpecs; “ESS_ATTRSPECS_T” on page 113 Attribute specifications
Notes
l This function is similar to EssGetAttributeSpecifications(), except that it returns

information from the opened outline.
l Set attribute specifications for the outline using EssOtlSetAttributeSpecifications().
used with it
Example
void ESS_OtlGetAttributeSpecifications()
{
801
ESS_PATTRSPECS_T AttrSpecs;

Object.hCtx = hCtx;

sts = EssOtlGetAttributeSpecifications(hOutline,&AttrSpecs);
printf("EssOtlGetAttributeSpecifications() sts: %ld\n",sts);
switch(AttrSpecs->usGenNameBy)
{
break;
break;
default:
break;
}
switch(AttrSpecs->usUseNameOf)
{
break;
break;
break;
break;
break;
default:
break;
}
802
switch(AttrSpecs->cDelimiter)
{
break;
break;
break;
default:
break;
}
switch(AttrSpecs->usDateFormat)
{
break;
break;
default:
break;
}
switch(AttrSpecs->usBucketingType)
{
break;
break;
break;
break;
default:
break;
}
printf("\n Default for TRUE : %s",

AttrSpecs->pszDefaultTrueString);
printf("\n Default for FALSE : %s",

AttrSpecs->pszDefaultFalseString);
printf("\n Default for Attr Calc : %s",

AttrSpecs->pszDefaultAttrCalcDimName);
803
printf("\n Default for Sum : %s",
AttrSpecs->pszDefaultSumMbrName);
printf("\n Default for Count : %s",

AttrSpecs->pszDefaultCountMbrName);
printf("\n Default for Average : %s",

AttrSpecs->pszDefaultAverageMbrName);
printf("\n Default for Min : %s",

AttrSpecs->pszDefaultMinMbrName);
printf("\n Default for Max : %s",

AttrSpecs->pszDefaultMaxMbrName);
printf("\n");


if (!sts)
{
}
EssOtlFreeStructure(hInst, ESS_DT_STRUCT_ATTRSPECS, 1,&AttrSpecs);

}
See Also
l EssFreeStructure
804
EssOtlGetChild
Returns the child of a member.
Syntax
ESS_FUNC_M EssOtlGetChild (hOutline, hMember, phMember);
hMember ESS_HMEMBER_T Handle of member to retrieve the child of.
phMember ESS_PHMEMBER_T Pointer for return of a member handle of the child of the hMember parameter.
Notes
If there is no child, *phMember is set to ESS_NULL and the call returns 0.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberParent;
ESS_HMEMBER_T hMemberChild;

Object.hCtx = hCtx;
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Year",
&hMemberParent);
}
if (!sts && hMemberParent)
{
sts = EssOtlGetChild(hOutline, hMemberParent,
805
&hMemberChild);
}
See Also
l EssOtlGetParent
l EssOtlGetNextSibling
l EssOtlGetPrevSibling
l EssOtlGetFirstMember
EssOtlGetCountOfDupMemberNameInDim
Returns the number of members in a dimension whose names are duplicate in the outline opened
in query mode.
Syntax
ESS_FUNC_M EssOtlGetDimensionNameUniqueness (hOutline, hDim, *pulDupCount);
hDim ESS_HMEMBER_T Input dimension, returned by EssOtlQueryGetFirstDimension() or

EssOtlQueryGetNextDimension().
*pulDupCount ESS_ULONG_T The number of members with duplicate names (output).
Notes
l A shared member in the dimension will not influence the count.
l Before you call this function, call EssOtlOpenOutlineQuery to open the outline in query
mode.
Return Value
Example
ESS_FUNC_M ESS_GetCount()
{
ESS_STS_T sts = 0;
ESS_HMEMBER_T hDim;
ESS_LONG_T pulDupCount;

Object.hCtx = hCtx;
strcpy(szAppName, "Demo");
806
strcpy(szDbName, "Test");
strcpy(szFileName, "Test");
sts = EssOtlOpenOutlineQuery (hCtx, &Object, &hOutline);
if (!sts)
{
sts = EssOtlQueryGetFirstDimension(hOutline, &hDim);
if (sts)
printf("EssOtlQueryGetFirstDimension failed sts %ld\n",sts);
}
if (!sts)
{
// returns pulDupCount which gives the number of members in a dimension
// whose names are duplicate
sts = EssOtlGetCountOfDupMemberNameInDim (hOutline, hDim, &pulDupCount);
if (sts)
printf("EssOtlGetCountOfDupMemberNameInDim failed sts %ld\n",sts);
}
return sts;
}
See Also
l EssOtlQueryGetFirstDimension
l EssOtlQueryGetNextDimension
EssOtlGetDateFormatString
This function gets the outline property date format String.
Syntax
ESS_FUNC_M EssOtlGetDateFormatString(
ESS_PSTR_T formatString)
hOutline ESS_HOUTLINE_T Outline handle
formatString ESS_PSTR_T Returns the outline date format string to this argument.
Return Value
Returns:
l 0—If successful
807
formatString contains the outline date format.
Example
void TestGetSetDateFormatString()
{
ESS_SHORT_T length = 80;
ESS_STR_T dateFormatString = "";
ESS_STR_T localeStr;
ESS_STR_T* pdateStrings;
ESS_STR_T* pformatStrings;

Object.hCtx = hCtx;

/* Get current value */

sts = EssOtlGetDateFormatString(hOutline, &dateFormatString);
printf("EssOtlGetSMDateFormatString sts: %d \n", sts);
printf("\tDate format string: %s\n", dateFormatString);
printf("\n");
localeStr = "English_UnitedStates.Latin1@Binary";
sts = EssOtlGetServerDateFormats(hCtx, localeStr,
&Count, &pdateStrings, &pformatStrings);
printf("EssOtlGetServerDateFormats sts: %d \n", sts);

{
printf("\nCase with %s:\n", pformatStrings[i]);
sts = EssOtlSetDateFormatString(hOutline,
pformatStrings[i]);
printf("EssOtlSetSMDateFormatString sts: %d \n", sts);
sts = EssOtlGetDateFormatString(hOutline,
&dateFormatString);

808
}
See Also
l EssOtlGetServerDateFormats
l EssOtlSetDateFormatString
EssOtlGetDimensionNameUniqueness
Returns the dimension's member-name uniqueness setting.
Syntax
ESS_FUNC_M EssOtlGetDimensionNameUniqueness (hOutline, hDim, pbNameUnique);
hDim ESS_HMEMBER_T Member handle of the dimension root member (input).
pbNameUnique ESS_PBOOL_T The dimension member name uniqueness setting (output). If TRUE, the
dimension cannot have duplicate member names.
Notes
Call EssOtlFindMember to set up the ESS_HMEMBER_T (hDim) variable.
Return Value
Example
ESS_FUNC_M ESS_GetSetDimNameUniq()
{
ESS_STS_T sts = 0;
ESS_POUTLINEINFO_T pInfo = ESS_NULL;
ESS_BOOL_T pbNameUnique;
ESS_HMEMBER_T hDim = ESS_NULL;

Object.hCtx = hCtx;
809
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Year",&hDim);
if (sts)
printf("EssOtlFindMember failed sts %ld\n",sts);
}
/*Get the dimension's, Year, member-name uniqueness setting */

if (!sts)
{
sts = EssOtlGetDimensionNameUniqueness (hOutline, hDim, &pbNameUnique);
if (sts)
printf("EssOtlGetDimensionNameUniqueness failed sts %ld\n",sts);
else
printf("Dimension Year has Member Name Uniqueness value: %ld\n", pbNameUnique);
}
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Product",&hDim);
if (sts)
}
if (!sts)
{
/*set Product to prohibit duplicate (non-unique) member names*/
pbNameUnique = ESS_TRUE;
sts = EssOtlSetDimensionNameUniqueness (hOutline, hDim, pbNameUnique);
if (sts)
printf("EssOtlSetDimensionNameUniqueness failed sts %ld\n",sts);
else
printf("Dimension Product has Member Name Uniqueness value: %ld\n", pbNameUnique);
}
return sts;
See Also
l EssOtlSetDimensionNameUniqueness
EssOtlGetDimensionSolveOrder
Returns the solve order of a dimension.
810
Syntax
ESS_FUNC_M EssOtlGetDimensionSolveOrder (hOutline, hMember, pOrder);
hMember ESS_PHMEMBER_T Dimension handle (input).
pOrder ESS_PUCHAR_T Solve order (output).
Notes
Solve order is applicable only to aggregate storage databases.
Return Value
Example
ESS_UCHAR_T ucOrder = 0;


{
sts = EssOtlGetDimensionSolveOrder(hOutline, hMember, &ucOrder);
if (sts)
printf("Error [%ld] returned\n", sts);
else
printf("Solve Order: %d\n", ucOrder);
}
else
printf("Both hOutline and hMember must have values\n");
See Also
l EssOtlSetDimensionSolveOrder
l EssOtlGetMemberSolveOrder
l EssOtlSetMemberSolveOrder
EssOtlGetDimensionUserAttributes
Returns the user defined attributes used in the specified dimension.
Syntax
ESS_FUNC_M EssOtlGetDimensionUserAttributes (hOutline, pPredicate,
pCounts, ppAttributeNames);
811
pPredicate “ESS_PREDICATE_T” on Structure defining the query. The fields of this structure are used as
page 719 follows:
l ulQuery—Value defining the operation to perform. The only
valid value is ESS_DIMUSERATTRIBUTES.
l pszDimension—Dimension to limit the scope of the query.
Specify a valid dimension name.
pCounts “ESS_MBRCOUNTS_T” on Structure defining information about counts It contains the

page 709 following fields:
l ulStart—Starting number to return
l ulMaxCount—Maximum number of member names to return
l ulTotalCount—Total number of members that are defined in
the results of the query
l pulReturnCount—Number of member names returned in this
query
ppAttributeNames ESS_PPMBRNAME_T An array of attribute names returned from the query.
Notes
l This function is used only to get the user's defined attributes on a specific dimension.
Therefore, the only valid value for Predicate is ESS_DIMUSERATTRIBUTES_T.
l Solve order property on a member or dimension specifies its calculation order.
l Member solve order takes precedence over dimension solve order. Solve order can be
between 0 and 127. The default is 0.
l Members without formulas that do not have a specified solve order inherit the solve order
of their dimension. Members with formulas that do not have a specified solve order have a
solve order of zero.
Return Value
Example
#include <essapi.h>
#include <essotl.h>

ESS_MBRNAME_T pAttribNames;
ESS_ULONG_T i;
ESS_STR_T AppName;
ESS_STR_T DbName;
812
AppName = "Sample";
DbName = "Basic";
if ( sts == 0)
{
memset(&Predicate, '\0', sizeof(Predicate));

Predicate.ulQuery = ESS_DIMUSERATTRIBUTES;
Predicate.pszDimension = "Market";
memset(&Counts, '\0', sizeof(Counts));

Counts.ulStart = 0;
if(!sts)
{
sts = EssOtlGetDimensionUserAttributes(hOutline,
&Predicate, &Counts, &pAttribNames);
if (!sts && Counts.ulReturnCount)

{
sts = EssFree(hInstance, pAttribNames);
}
}
}
See Also
l EssFree
EssOtlGetDTSMemberAlias
Gets an alias name for a Dynamic Time Series (DTS) member.
Syntax
ESS_STS_T EssOtlGetDTSMemberAlias (hOutline, pszDTSMember, pszAliasTable, ppszAlias);
813
pszAliasTable ESS_STR_T Name of the alias table which provides the alias. If NULL, the default alias table
is used.
ppszAlias ESS_PSTR_T Pointer to a pointer to a C string containing the alias name for the DTS member.
Return Value
Example
#include "essapi.h"
#include "essotl.h"
ESS_STS_T ESS_OtlGetDTSMemberAlias(ESS_HCTX_T hCtx)

{
ESS_STR_T pszAlias;
Object.hCtx = hCtx;
sts = EssOtlOpenOutline(hCtx, &Object, ESS_FALSE, ESS_TRUE, &hOutline);
if(sts)
{
return sts;
}
sts = EssOtlGetDTSMemberAlias(hOutline, pszDTSMember, pszAliasTable, &pszAlias);

if(sts)
{
printf("Could not get DTS member alias\n");
return sts;
814
}
printf("MEMBER %s is aliased to %s\n", pszDTSMember, pszAlias);
return sts;
}
See Also
EssOtlGetEnabledDTSMembers
Retrieves the member information structures for the enabled Dynamic Time Series (DTS)
members in the specified outline.
Syntax
ESS_STS_T EssOtlGetEnabledDTSMembers (hOutline, pusCount, ppEnabledDTSMemberList);
hOutline ESS_HOUTLINE_T The Essbase outline handle returned from the

EssOtlOpenOutline call.
pusCount ESS_PUSHORT_T The number of enabled DTS Members.
ppEnabledDTSMemberList ESS_PPDTSMBRINFO_T Pointer to an array of DTS member info structures (for the
enabled DTS members for the outline).
Notes
This function also fills in theESS_DTSMBRNAME_T structure passed to it.
Return Value
If successful the return value is zero. Otherwise, returns the status of the
EssOtlQueryMembers() call.
Example
#include "essapi.h"
#include "essotl.h"
ESS_STS_T ESS_OtlGetEnabledDTSMembers(ESS_HCTX_T hCtx)

{
ESS_USHORT_T usCount, i;
815
ESS_PDTSMBRNAME_T pEnabledDTSMbrList;

Object.hCtx = hCtx;
sts = EssOtlOpenOutline(hCtx, &Object, ESS_FALSE, ESS_TRUE, &hOutline);

if(sts)
{
return sts;
}
sts = EssOtlGetEnabledDTSMembers(hOutline, &usCount, &pEnabledDTSMbrList);

if(sts)
{
printf("Could not get enabled DTS member alias\n");
}
else
{
printf("No of enabled DTS members is %u\n", usCount);
for (i = 0; i < usCount; i++)
{
printf("%s\n", pEnabledDTSMbrList[i]);
}
}
return sts;
}
See Also
EssOtlGetFirstMember
Returns a member handle to the first member in the outline. The first member is the first
dimension defined in the outline.
Syntax
ESS_FUNC_M EssOtlGetFirstMember (hOutline, phMember);
816
phMember ESS_PHMEMBER_T Pointer for return of a member handle of the first member in the outline. This
parameter is passed to subsequent calls for traversing the outline.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_MEMBER_T hMemberFirst

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlGetFirstMember(hOutline,
&hMemberFirst);
}
See Also
l EssOtlGetParent
l EssOtlGetChild
EssOtlGetGenName
Retrieves the name for a specific generation within a dimension.
Syntax
ESS_FUNC_M EssOtlGetGenName (hOutline, pszDimension, usGen, ppszName);
817
pszDimension ESS_STR_T Name of dimension that contains the generation.
usGen ESS_USHORT_T Number of generation for which to get a name. The dimension is generation 1.
ppszName ESS_PSTR_T Buffer for return of generation name, allocated by the API.
Notes
l The generation name follows the same rules as a member name and must be unique across
the entire member name space. It cannot duplicate any other generation, level, member
name, or alias. Attempting to add a duplicate name generates an error.
l Generation names are not automatically assigned. For this function to return the name, a
name must have been assigned. The name can be assigned with EssOtlSetGenName
l Call EssFree() to free the returned buffer.
Return Value
l OTLAPI_NO_GENLEVELNAME
l OTLAPI_ERR_NOTADIM
l OTLAPI_ ERR_GENLEVELNAMEMBR
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T GenName;

Object.hCtx = hCtx;

818
/************ Get Gen Name ***************/
Dimension = "Year";
GenNum = 3;
if (!sts)
{
sts = EssOtlGetGenName(hOutline, Dimension,
GenNum, &GenName);
}
if (!sts && GenName)

{
printf("Gen Name: %s\n",GenName);
EssFree(hInst, GenName);
}
See Also
l EssFree
l EssOtlDeleteGenName
l EssOtlSetGenName
EssOtlGetGenNameEx
Retrieves the name and member uniqueness setting for a specific generation within a dimension.
Syntax
ESS_FUNC_M EssOtlGetGenName (hOutline, pszDimension, usGen, ppszName, pbNameUnique);
usGen ESS_USHORT_T Number of generation for which to get a name. The dimension is generation 1.
ppszName ESS_PSTR_T Buffer for return of generation name, allocated by the API.
pbNameUnique ESS_PBOOL_T Member name uniqueness setting.
Notes
l The generation name must be unique across the entire member name space. It cannot
duplicate any other generation, level, member name, or alias. Attempting to add a duplicate
generation name generates an error.
l Generation names are not automatically assigned. For this function to return the name, a
name must have been assigned. The name can be assigned with EssOtlSetGenName
l Call EssFree() to free the returned buffer.
Return Value
Returns 0 if successful; otherwise, returns an error code.
819
Example
void ESS_GetGenNameEx()
ESS_STS_T sts = 0;
ESS_STR_T GenName;
ESS_BOOL_T bUnique= ESS_FALSE;

Object.hCtx = hCtx;

printf("EssOtlOpenOutline sts: %ld\n",sts);
/*************** Set and Get GenName **************/

Dimension = "Year";
GenNum = 1;
GenName = "Gen 1 Year";
//SetGenNameEx() so that Gen 1 members of Year cannot be non-unique

if (!sts)
{
sts = EssOtlSetGenNameEx(hOutline, Dimension,
GenNum, GenName, ESS_TRUE);
}
// GetGenNameEx() to see if the gen is able to be non-unique

if (!sts)
{
sts = EssOtlGetGenNameEx(hOutline, Dimension,
GenNum, &GenName, &bUnique);
printf("Generation 1 members of Year have bUnique value of %ld\n", bUnique);
printf("EssOtlGetGenNameEx sts: %ld\n",sts);
}

{
820
}
See Also
l EssOtlGetGenName
l EssFree
l EssOtlSetGenNameEx
EssOtlGetGenNames
Retrieves all generation names specified for a particular dimension.
Syntax
ESS_FUNC_M EssOtlGetGenNames (hOutline, pszDimension, ulOptions, pulCount, pNameArray);
hOutline ESS_HOUTLINE_T Essbase outline handle.
pszDimension ESS_STR_T The dimension to retrieve generation names for.
ulOptions ESS_ULONG_T This can be one of the following values:

l ESS_GENLEV_ALL—Returns default and actual generation
names.
l ESS_GENLEV_ACTUAL—Returns only generation names that
are actually defined.
l ESS_GENLEV_DEFAULT—Returns all default generation
names. This includes the default names for generations that have
an actual name.
l ESS_GENLEV_NOACTUAL—Returnsdefault generation
names. This includes only the generations that don't have an
actual generation name.
pulCount ESS_PULONG_T Return of the number of elements in the pNameArray. It is the

number of generation names for the specified member.
pNameArray “ESS_GENLEVELNAME_T” An array of generation name structures for the specified dimension.
on page 708
Notes
l The caller should free the pNameArray structure after use by calling EssFree().
l This call will work for both EssOtlOpenOutline() and EssOtlOpenOutlineQuery(). The
information will exist locally for both, since it is returned from the server during the
EssOtlOpenOutlineQuery() call.
Return Value
821
Example
#include <essapi.h>
#include <essotl.h>

ESS_ULONG_T GenOpt;
ESS_ULONG_T pCount = 0, i;
ESS_PGENLEVELNAME_T pNameArray = ESS_NULL;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts=EssSetActive(hCtx, AppName, DbName, &Access);
if (sts == 0)
{
Dimension = "Year";
GenOpt = ESS_GENLEV_ALL;
if (!sts)
{
sts = EssOtlGetGenNames(hOutline, Dimension,
GenOpt, &Count, &pNameArray);
if(!sts && Count )

{
for(i = 0; i<Count; i++)
{
printf("\nNumber %ld, Name %s ",
pNameArray[i].usNumber, pNameArray[i].szName);
}
EssFree(hInst, pNameArray);
}
}
}
See Also
l EssFree
l EssOtlGetGenName
l EssOtlGetLevelNames
l EssOtlOpenOutline
822
EssOtlGetHierarchyType
Gets the dimension's hierarchy type designation: Multiple hierarchies enabled, dynamic
hierarchy, or stored hierarchy.
Syntax
ESS_FUNC_M EssOtlGetHierarchyType(hOutline, hMember, pType);
hMember ESS_HMEMBER_T A dimension member (input).
pType ESS_UCHAR_T If hMember is a dimension member, one of the following values (output):
l ESS_STORED_HIERARCHY—The dimension is a single, stored hierarchy.
l ESS_DYNAMIC_HIERARCHY—The dimension is a single, dynamic hierarchy.
l ESS_MULTIPLE_HIERARCHY_IS_ENABLED—The dimension is multiple-
hierarchy enabled.
See Notes.
Notes
l Once the dimension is multiple-hierarchy enabled, the hierarchy types are determined by
the generation 2 members. If hMember is a generation 2 member, pType can return the
following values:
m ESS_STORED_HIERARCHY—The hierarchy with hMember as top is a single, stored
hierarchy.
m ESS_DYNAMIC_HIERARCHY—The hierarchy with hMember as top is a single,
dynamic hierarchy.
m ESS_MULTIPLE_HIERARCHY_NOT_ENABLED—The dimension is not multiple-
hierarchy enabled.
l If hMember is of a generation greater than 2, pType returns
ESS_NOT_HIERARCHY_MEMBER.
Return Value
See Also
l EssOtlGetAltHierarchyEnabled
EssOtlGetImpliedShare
Returns the Implied Share setting of an outline.
823
Syntax
ESS_FUNC_M EssOtlGetImpliedShare(hOutline, &impliedShareSetting);
&impliedShareSetting ESS_USHORT Address of an implied share setting.
Return Value
l 0—If successful
The implied share setting value. See “Implied Share Setting (C)” on page 97.
Return Parameter
ESS_USHORT impliedShareSetting
See Also
l EssOtlSetImpliedShare
EssOtlGetLevelName
Gets the name for a specific level within a dimension.
Syntax
ESS_FUNC_M EssOtlGetLevelName (hOutline, pszDimension, usLevel, pszName);
usLevel ESS_USHORT_T Number of level number for which to get a name. Leaf members are level 0.
pszName ESS_PSTR_T Buffer for return of the level of the specified dimension, allocated by the API.
Notes
l In C programs, call EssFree() to free the returned buffer.
l Level names are not automatically assigned. For this function to return the name, a name
must have been assigned. The name can be assigned with EssOtlSetLevelName
Return Value
l OTLAPI_NO_GENLEVELNAME
824
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T LevelName;

Object.hCtx = hCtx;

/*************** Get Level Name **************/

Dimension = "Year";
LevelNum = 0;
if (!sts)
{
sts = EssOtlGetLevelName(hOutline, Dimension,
LevelNum, &LevelName);
}
if (!sts && LevelName)

{
printf("Level Name: %s\n",LevelName);
EssFree(hInst, LevelName);
}
See Also
l EssOtlSetLevelName
l EssOtlDeleteLevelName
l EssOtlSetGenName
EssOtlGetLevelNameEx
Returns the member-name uniqueness setting for a specific level within a dimension.
825
Syntax
ESS_FUNC_M EssOtlGetLevelNameEx (hOutline, pszDimension, usLevel, pszName, pbNameUnique);
usLevel ESS_USHORT_T Number of level number for which to get a name. Leaf members are level 0.
pszName ESS_PSTR_T Buffer for return of the level of the specified dimension, allocated by the API
(output).
pbNameUnique ESS_PBOOL_T The member-name uniqueness setting (output).
Notes
l In C programs, call EssFree() to free the returned buffer.
l Level names are not automatically assigned. For this function to return the name, a name
must have been assigned. The name can be assigned with EssOtlSetLevelName
l This function gets the member-name uniqueness information for the level. If you want to
change the member-name uniqueness setting, use EssOtlSetLevelNameEx.
Return Value
Example
ESS_FUNC_M
ESS_GetLevelNameEx()
{
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

826
/*************** Set and Get Level Name **************/
Dimension = "Year";
LevelNum = 0;
LevelName = "Level 0 Year";
//SetLevelNameEx() so that level 0 member of Year cannot be non-unique

if (!sts)
{
sts = EssOtlSetLevelNameEx(hOutline, Dimension,
LevelNum, LevelName, ESS_TRUE);
}
// GetLevelNameEx() to see if the level is able to be non-unique

if (!sts)
{
sts = EssOtlGetLevelNameEx(hOutline, Dimension,
LevelNum, &LevelName, &bUnique);
printf("Level 0 members of Year have bUnique value of %ld\n", bUnique);

{
}
return (sts);
}
See Also
l EssOtlSetLevelNameEx
EssOtlGetLevelNames
Retrieves all level names specified for a particular dimension.
Syntax
ESS_FUNC_M EssOtlGetLevelNames (hOutline, pszDimension, ulOptions, pulCount, pNameArray);
hOutline ESS_HOUTLINE_T Essbase outline handle.
pszDimension ESS_STR_T The dimension to retrieve level names for.
827
ulOptions ESS_ULONG_T This can be one of the following values:

l ESS_GENLEV_ALL—Returns default and actual level names
l ESS_GENLEV_ACTUAL—Returns only level names that are
actually defined
l ESS_GENLEV_DEFAULT—Returns all default level names.
This includes the default names for levels that have an actual
name.
l ESS_GENLEV_NOACTUAL—Returns default level names.
This includes only the levels that don't have an actual level name.
pulCount ESS_PULONG_T Return of the number of elements in the pNameArray. It is the

number of level names for the specified member.
pNameArray “ESS_GENLEVELNAME_T” An array of level name structures for the specified dimension.
on page 708
Notes
l The caller should free the pNameArray structure after use by calling EssFree().
l This call will work for both EssOtlOpenOutline() and EssOtlOpenOutlineQuery(). The
information will exist locally for both, since it is returned from the server during the
EssOtlOpenOutlineQuery() call.
Return Value
Example
#include <essapi.h>
#include <essotl.h>

ESS_ULONG_T LevOpt;
ESS_ULONG_T pCount = 0, i;
ESS_PGENLEVELNAME_T pNameArray = ESS_NULL;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts=EssSetActive(hCtx, AppName, DbName, &Access);
if (sts == 0)
{
828
Dimension = "Year";
LevOpt = ESS_GENLEV_ALL;
if (!sts)
{
sts = EssOtlGetLevelNames(hOutline, Dimension,
LevOpt, &Count, &pNameArray);
if(!sts && Count )

{
for(i = 0; i<Count; i++)
{
printf("\nNumber %ld, Name %s ",
pNameArray[i].usNumber, pNameArray[i].szName);
}
EssFree(hInst, pNameArray);
}
}
}
See Also
l EssFree
l EssOtlGetGenName
l EssOtlGetGenNames
l EssOtlOpenOutline
EssOtlGetLinkedAttributeAttachLevel
Gets the attachment level for a linked attribute dimension.
Linked attribute dimensions enable periodic comparisons between members in a date-time
dimension. Every linked attribute has an association level and an attachment level associated
with the attribute dimension definition.
The attachment level is always the longer of the two periods in the periodic comparison
represented by a linked attribute dimension. For example, in the linked attribute dimension
Quarter by Year, Year is the attachment level, and Quarter is the association level.
Syntax
ESS_FUNC_M EssOtlGetLinkedAttributeAttachLevel (hOutline, hDimMember, psLevel);
hDimMember ESS_HMEMBER_T Linked attribute dimension member handle (input).
psLevel ESS_PUSHORT_T The linked attribute attachment level (output).
829
Notes
l Before you call this function, open the outline in edit or query mode using either
EssOtlOpenOutline or EssOtlOpenOutlineQuery.
l This function is only applicable when hDimMember is a linked attribute dimension.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER hDimMember;
ESS_USHORT_T usAttachLevel;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Quarter By Year",
&hDimMember);
}

{
sts = EssOtlGetLinkedAttributeAttachLevel(hOutline,
hDimMember, &usAttachLevel);
}
See Also
l EssOtlGetAttributeAssocLevel
l EssOtlQueryGenerationInfo
830
EssOtlGetMemberAlias
Gets the default member alias for the specified member in the specified alias table.
Syntax
ESS_FUNC_M EssOtlGetMemberAlias (hOutline, hMember, pszAliasTable, ppszAlias);
hMember ESS_HMEMBER_T Handle of member to get the alias for.
pszAliasTable ESS_STR_T Alias table to get the alias from. If this parameter is ESS_NULL, the default alias
table is used.
ppszAlias ESS_PSTR_T Buffer for the return of the alias. The buffer is allocated by the API.
Notes
Use EssFree() to free the alias buffer.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T pszAlias;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "100",
&hMember);}
831
{
sts = EssOtlGetMemberAlias(hOutline,
hMember, ESS_NULL, &pszAlias);
}
if (pszAlias)
{
EssFree(hInst, pszAlias);
}
See Also
l EssOtlSetMemberAlias
l EssOtlDeleteMemberAlias
EssOtlGetMemberCommentEx
Gets the extended comment for the specified member.
Syntax
ESS_FUNC_M EssOtlGetMemberCommentEx (hOutline, hMember, pszCommentEx);
pszCommentEx ESS_PSTR_T Variable for the return of the extended comment. This buffer is allocated by the
API.
Notes
Use EssFree() to release the buffer containing the extended member comment.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T pszCommentEx = ESS_NULL;

Object.hCtx = hCtx;
832
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Variance", &hMember);
}

{
sts = EssOtlGetMemberCommentEx(hOutline, hMember, &pszCommentEx);
}
if (pszCommentEx)
{
EssFree(hInst, pszCommentEx);
}
See Also
l EssFree
l EssOtlOpenOutline
EssOtlGetMemberField
Returns data for the specified field of a specified outline member.
Syntax
ESS_FUNC_M EssOtlGetMemberField(hOutline, hMember, MbrFieldID, ppFieldElement);
hMember ESS_HMEMBER_T Member handle returned by EssOtlQueryMembersEx().
MbrFieldID ESS_ULONG_T A member field identifier constant. See Notes.
ppFieldElement ESS_PPVOID_T Returned pointer to the required field element.
Notes
l EssOtlGetMemberField() takes a member handle and field identifier, and returns a pointer
to data for the specified field.
833
l If you specify for MbrFieldID a constant that was not in the fieldSelection string in
EssOtlQueryMembersEx(), EssOtlGetMemberField() returns the error
OTLAPI_ERR_MBRINVALID.
l The caller of EssOtlGetMemberField() should call EssFree() to free the memory set aside
for the specified field data.
l The following member field identifier constants are valid values for MbrFieldID:
m ESS_OTLQRYMBR_NONE
m ESS_OTLQRYMBR_NAME
m ESS_OTLQRYMBR_LEVEL
m ESS_OTLQRYMBR_GENERATION
m ESS_OTLQRYMBR_CONSOLIDATION
m ESS_OTLQRYMBR_TWOPASS
m ESS_OTLQRYMBR_EXPENSE
m ESS_OTLQRYMBR_CURRENCYCONVTYPE
m ESS_OTLQRYMBR_CURRENCYCONVNAME
m ESS_OTLQRYMBR_TIMEBALANCE
m ESS_OTLQRYMBR_SKIP
m ESS_OTLQRYMBR_SHARE
m ESS_OTLQRYMBR_STORAGE
m ESS_OTLQRYMBR_CATEGORY
m ESS_OTLQRYMBR_STORAGECATEGORY
m ESS_OTLQRYMBR_COMMENT
m ESS_OTLQRYMBR_CHILDCOUNT
m ESS_OTLQRYMBR_NUMBER
m ESS_OTLQRYMBR_DIMNAME
m ESS_OTLQRYMBR_DIMNUMBER
m ESS_OTLQRYMBR_ALIASNAME
m ESS_OTLQRYMBR_NEXTNAME
m ESS_OTLQRYMBR_PREVNAME
m ESS_OTLQRYMBR_PARENTNAME
m ESS_OTLQRYMBR_CHILDNAME
m ESS_OTLQRYMBR_UDA
m ESS_OTLQRYMBR_FORMULA
m ESS_OTLQRYMBR_LASTFORMULA
m ESS_OTLQRYMBR_EXTCOMMENT
m ESS_OTLQRYMBR_ALIASCOMBO
834
m ESS_OTLQRYMBR_VALID
m ESS_OTLQRYMBR_CURRENCYCONVDB
m ESS_OTLQRYMBR_STATUS
m ESS_OTLQRYMBR_ATTRIBUTED
True—if attributes are associated
m ESS_OTLQRYMBR_ASSOCATTRDIMNAME
Associated Attribute Dimension name
m ESS_OTLQRYMBR_ASSOCATTRMEMNAME
Associated Attribute Member name
m ESS_OTLQRYMBR_ASSOCATTRVALUE
Associated Attribute value
m ESS_OTLQRYMBR_ATTRVALUE
Attribute value of the member
m ESS_OTLQRYMBR_UNIQUENAME
Unique Name of the member
m ESS_OTLQRYMBR_FORMATSTRING
Format String of the member
m ESS_OTLQRYTIDIM_TIMEPERIODS
Query Time dimension for time periods list
m ESS_OTLQRYMBR_MBRINFO
Return Value
The return value is zero if the function call was successful.
Example
See “Extended Member Query Code Example” on page 1000 for an example that uses
EssOtlQueryMembersEx(), EssOtlGetMemberField(), and ESS_OTLQUERYERRORLIST_T,
and includes calls to EssOtlFreeMembers() and EssFree().
See Also
l EssFree
l EssOtlGetDimensionUserAttributes
l EssOtlQueryMembersEx
835
EssOtlGetMemberFormula
Gets the formula for the specified member.
Syntax
ESS_FUNC_M EssOtlGetMemberFormula (hOutline, hMember, pszFormula);
ppszFormula ESS_PSTR_T Variable for the return of the member formula. This buffer is allocated by the API.
Notes
Use EssFree() to free the formula buffer.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T pszFormula = ESS_NULL;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Variance",
&hMember);
}
836
{
sts = EssOtlGetMemberFormula(hOutline,
hMember, &pszFormula);
}
if (pszFormula)
{
EssFree(hInst, pszFormula);
}
See Also
l EssFree
l EssOtlDeleteMemberFormula
l EssOtlGetMemberLastFormula
l EssOtlOpenOutline
EssOtlGetMemberInfo
Gets member information for the specified member.
Syntax
ESS_FUNC_M EssOtlGetMemberInfo (hOutline, hMember, pInfo);
pInfo “ESS_MBRINFO_T” on page 709 Pointer to a member information structure, allocated by the API.
Notes
l Call EssOtlFindMember() to retrieve the member handle.
l Call EssFreeStructure() to free the information structure.
l Two fields of the “ESS_MBRINFO_T” on page 709 structure are for attributes only:
m fAttributed
m Attribute
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
837
ESS_HMEMBER hMemberJan;
ESS_PMBRINFO_T pMbrInfo;

Object.hCtx = hCtx;

if (!sts)
{
&hMemberJan);
}

{
sts = EssOtlGetMemberInfo(hOutline,
hMemberJan, &pMbrInfo);
}
if (pMbrInfo)
{
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1, pMbrInfo);
}
EssOtlGetMemberInfoArray
Gets member information for the specified member array.
Syntax
ESS_FUNC_M EssOtlGetMemberInfoArray (hOutline, memberCount, hMemberArr, pInfoArr,
pStsArr);
hOutline ESS_HOUTLINE_T Outline handle.
memberCount ESS_SHORT_T Count of members in the input array.
hMemberArr ESS_HMEMBER_T Array of memberCount member handles.
pInfoArr ESS_PPMBRINFO_T Array of memberCount member information pointers.
838
pStsArr ESS_STS_T Array of memberCount status return codes.

If any errors occur, the function returns the value of the first error encountered.
Notes
l Call EssOtlFindMember() to retrieve the member handles.
l Call EssFreeStructure() to free the information structure.
l Two fields of the “ESS_MBRINFO_T” on page 709 structure are for attributes only:
m fAttributed
m Attribute
Return Value
Returns 0 if successful. If unsuccessful, the pStsArr has the return code for each member.
Example
#include <essapi.h>
#include <essotl.h>
ESS_HMEMBER hMemberArr[3];
ESS_PMBRINFO_T pMbrInfoArr[3];
ESS_STS_T stsArr[3];
ESS_SHORT_T i;

Object.hCtx = hCtx;
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Jan", &hMemberArr[0]);
}
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Feb", &hMemberArr[1]);
}
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Mar", &hMemberArr[2]);
}
839
if (!sts)
{
sts = EssOtlGetMemberInfoArray(hOutline, 3, hMemberArr, pMbrInfoArr, stsArr);
}
for (i = 0; i < 3; i++)
{
if (pMbrInfoArr[i])
{
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1, pMbrInfoArr[i]);
}
}
EssOtlGetMemberLastFormula
Returns the last formula used to calculate the member.
Syntax
ESS_FUNC_M EssOtlGetMemberLastFormula (hOutline, hMember, ppszFormula);
ppszFormula ESS_PSTR_T Variable for the return of the member formula. This buffer is allocated by the API.
Notes
l Use EssFree() to free the formula buffer.
l This call will work for both EssOtlOpenOutline() and EssOtlOpenOutlineQuery().
l EssOtlGetMemberLastFormula() returns the last formula applied to the selected member,
which might differ from the Database Outline formula associated with that member.
l The last formula is derived from the last calculation (either from the outline or calc scripts)
done on the member.
Return Value
Example
#include <ESSAPI.H>
#include <ESSOTL.H>
ESS_STS_T sts = 0 ;
ESS_STR_T pszFormula = ESS_NULL;
840
Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Margin", &hMember);
}

{
sts = EssOtlGetMemberLastFormula(hOutline, hMember, &pszFormula);
printf("Member Last Formula: %s\n",pszFormula);
}
if (pszFormula)
{
}
See Also
l EssFree
l EssOtlOpenOutline
EssOtlGetMemberSmartList
Returns the Text List (SmartList) associated with the input outline member.
Syntax
ESS_FUNC_M EssOtlGetMemberSmartList(hOutline, hMember, *phSmartlist);
hMember ESS_HMEMBER_T Outline member handle
*phSmartlist ESS_HSMARTLIST_T Returns the associate Text List (SmartList) handle
841
Return Value
Returns:
l 0—If successful
*phSmartlist contains return value.
*phSmartlist is NULL.
Example
void TestGetMemberSmartList()
{

Object.hCtx = hCtx;
/* Open outline */
/* Find member */
sts = EssOtlFindMember(hOutline, "Original Price",
&hMember);
/* Return SmartList associated with member */

sts = EssOtlGetMemberSmartList(hOutline, hMember,
&hSmartList);
/* Unlock object */
/* Close outline */
}
See Also
l EssOtlFindObject
842
l EssOtlListObjects
EssOtlGetMemberSolveOrder
Returns the solve order of a member.
Syntax
ESS_FUNC_M EssOtlGetMemberSolveOrder (hOutline, hMember, pOrder);
pOrder ESS_PUCHAR_T Solve order (ouput).
Notes
l Solve order is applicable only to aggregate storage databases.
Return Value
Example

843
{
sts = EssOtlGetMemberSolveOrder(hOutline, hMember, &ucOrder);
if (sts)
else
}
else
EssOtlSetMemberSolveOrder
EssOtlSetDimensionSolveOrder
EssOtlGetDimensionSolveOrder
EssOtlGetMemberType
Returns the member type of the input outline member.
Syntax
ESS_FUNC_M EssOtlGetMemberType(hOutline, hMember, *pusType)
*pusType ESS_USHORT_T Type of the outline member:

l ESS_MEMBERTYPE_NUMERIC
Member type is a numeric.
l ESS_MEMBERTYPE_SMARTLIST
Member type is textual and has an associated Text List (SmartList) object.
l ESS_MEMBERTYPE_DATE
Member type is date typed.
Return Value
Returns:
l 0—If successful
pusType contains a value.
pusType is NULL.
Example
void TestGetSetMemberType()
{
844
ESS_USHORT_T usMemberType;

Object.hCtx = hCtx;
/* Open outline */
/* Find a member */
sts = EssOtlFindMember(hOutline, "Original Price", &hMember);
/* Get Member Type of an outline that is not member

type enabled */
/* Get original type */
sts = EssOtlGetMemberType(hOutline, hMember, &usMemberType);
DisplayMemberType(usMemberType); /* a display function */
/* Get Member Type of an outline that is member

type enabled */
EnableSmartList(hOutline);

printf("EssOtlGetMemberType sts: %d\n", sts);
DisplayMemberType(usMemberType);
/* Set type to NUMERIC */

usMemberType = ESS_MEMBERTYPE_NUMERIC;
sts = EssOtlSetMemberType(hOutline, hMember, usMemberType);
printf("EssOtlSetMemberType sts: %d\n",sts);

/* Clean up */
/* Close outline */
}
See Also
845
l EssOtlFindObject
l EssOtlListObjects
EssOtlGetMemberUniqueName
Returns the member name (if the member name is unique) or the minimum qualified name
required to distinguish the member (if the member name is duplicate).
Syntax
ESS_FUNC_M EssOtlGetMemberUniqueName (hOutline, hMember, *szFullName);
*szFullName ESS_STR_T The returned member name or qualified member name (output).
Notes
l Before you call this function, call EssOtlOpenOutline to open the outline in editing mode,
or call EssOtlOpenOutlineQuery to open the outline in query mode.
l Use a Member Traversal Function to get a member handle for the second argument of this
function.
l In an outline that allows duplicate member names, if the member handle passed in is an
extended shared member or a regular shared member, this function returns the unique
name.
Return Value
846
Example
Example 1
The output of this function in the following example is the fully qualified member name of Qtr1:
[2004].[Qtr1]
ESS_FUNC_M ESS_GetMemberUniq()
{
ESS_STS_T sts = 0;
ESS_STR_T szFullName;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "2004", &hMemberParent);
}

{
sts = EssOtlGetChild(hOutline, hMemberParent, &hMemberChild);
}
/*Get the qualified name of the first child of 2004, Qtr1*/

if (!sts)
{
sts = EssOtlGetMemberUniqueName (hOutline, hMemberChild, &szFullName);
if (sts)
printf("EssOtlGetMemberUniqueName failed sts %ld\n",sts);
else
printf("Qtr1's qualified name is: %s\n", szFullName);
}
847
return sts;
}
Example 2
The following example shows this function used in query mode.
member_fields = "<SelectMbrInfo (membername, uniquename) ";

member_selection = "@SHARE(@DESCENDANTS(product))";
MaxCount = -1;
phMemberArray = ESS_NULL;
pqryErrorList = ESS_NULL;
status = EssOtlQueryMembersEx(hOutline,
member_fields,
member_selection,
&MaxCount,
&phMemberArray,
&pqryErrorList);
if (status) goto exit;
for (int i = 0; i < MaxCount; i++)

{
status = EssOtlGetMemberField(hOutline, phMemberArray[i], ESS_OTLQRYMBR_NAME,
(ESS_PPVOID_T) &pName);
status = EssOtlGetMemberUniqueName(hOutline, phMemberArray[i], &pUniqueName2);

}
EssOtlGetNextSharedMember
Returns the member handle to the next shared member of the specified member.
Syntax
ESS_FUNC_M EssOtlGetNextSharedMember (hOutline, hMember, phMember);
hMember ESS_HMEMBER_T Handle of member to find the next shared member for.
phMember ESS_PHMEMBER_T Pointer for return of a member handle of the next shared member in the outline.
This parameter is ESS_NULL if there are no more shared members.
Notes
l If hmember is the actual member, the first shared member is returned in the phMember
parameter. If hmember is a shared member, the next shared member is returned in the
phMember parameter.
848
l If there are no (more) shared members, phMember is set to ESS_NULL and the call returns
0.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberShared;
ESS_HMEMBER_T hNextShared;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "200-20",
&hMember);
}

{
/* get first shared member of actual member */
sts = EssOtlGetNextSharedMember(hOutline, hMember, &hMemberShared);
/* do something with hMemberShared */

/* get next shared member, if any*/
while(!sts && hMemberShared)

{
sts = EssOtlGetNextSharedMember(hOutline,
hMemberShared, &hNextShared);
hMemberShared = hNextShared;
/* do something with hMemberShared */

}
}
849
See Also
l EssOtlFindMember
EssOtlGetNextSibling
Returns the next sibling of a member.
Syntax
ESS_FUNC_M EssOtlGetNextSibling (hOutline, hMember, phMember);
hMember ESS_HMEMBER_T Handle of member whose sibling you want to retrieve
phMember ESS_PHMEMBER_T Pointer for return of a member handle of the sibling of the hMember parameter
Notes
If there is no next sibling, *phMember is set to ESS_NULL and the call returns 0.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberSibling;

Object.hCtx = hCtx;

if (!sts)
{
850
&hMemberJan);
}

{
sts = EssOtlGetNextSibling(hOutline,
hMemberJan, &hMemberSibling);
}
See Also
l EssOtlGetParent
l EssOtlGetChild
EssOtlGetNumQueryHints
Returns the hint numbers of all query hints in the outline.
Syntax
ESS_FUNC_M EssOtlGetNumQueryHints (hOutline, pNumHints);
pNumHints ESS_PSHORT_T Pointer to an array of query hint numbers (output).
Notes
Return Value
Example
See EssOtlSetQueryHint.
See Also
851
EssOtlGetObjectReferenceCount
Returns the count of outline members referencing the input object handle.
Syntax
ESS_FUNC_M EssOtlGetObjectReferenceCount(hOutline, objHandle, pCount)
objHandle ESS_HOBJECT_T Object handle to be imported or exported
pCount ESS_ULONG_T* Count of outline members
Return Value
Returns:
l 0—If successful
pCount contains values.
pCount is NULL.
Example
void TestGetObjectReferenceCount()
{
ESS_HOBJECT_T hObjHandle = ESS_NULL;
ESS_STR_T objName;

Object.hCtx = hCtx;

/* Get count of an object that is referenced */

objName = "Smartlist1";
sts = EssOtlFindObject(hOutline, objType,
objName, &hObjHandle);
printf("EssOtlFindObject sts: %ld\n",sts);
sts = EssOtlGetObjectReferenceCount(hOutline,
hObjHandle, &Count);
852
printf("EssOtlGetObjectReferenceCount sts: %ld\n",sts);
printf("\tCount returned: %d\n", Count);

}
See Also
l EssOtlFindObject
l EssOtlListObjects
EssOtlGetObjectReferences
Returns an array of outline members referencing the input object handle. This function should
be followed by deallocing phMembers using EssFree.
Syntax
ESS_FUNC_M EssOtlGetObjectReferences(hOutline, objHandle, ulMaxCount, phMembers,
pulNumMembers)
objHandle ESS_HOBJECT_T Object handle
ulMaxCount ESS_ULONG_T Count of max outline members that the client can handle
phMembers ESS_HMEMBER_T* Output array of outline members
pulNumMembers ESS_ULONG_T* Number of outline members returned.
Return Value
Returns:
853
l 0—If successful
ulMaxCount, phMembers, and pulNumMembers contain values.
ulMaxCount, phMembers, and pulNumMembers are NULL.
Example
void TestGetObjectReferences()
{
ESS_ULONG_T ulMaxCount;
ESS_HMEMBER_T hMembers[256];
ESS_ULONG_T ulNumMembers, i;
ESS_STR_T objName;
ESS_PMBRINFO_T pMbrInfo;

Object.hCtx = hCtx;

/* Get the member(s) of the object that is referenced */

objName = "SmartList1";
sts = EssOtlFindObject(hOutline, objType, objName, &hObjHandle);
ulMaxCount = 256;
sts = EssOtlGetObjectReferences(hOutline, hObjHandle,
ulMaxCount, hMembers, &ulNumMembers);
printf("EssOtlGetObjectRefrences sts: %ld\n",sts);
for(i = 0; i < ulNumMembers; i++)

{
sts = EssOtlGetMemberInfo(hOutline, hMembers[i], &pMbrInfo);
if(pMbrInfo)
printf("\tMember: %s\n", pMbrInfo->szMember);
}

}
See Also
854
l EssOtlFindObject
l EssOtlListObjects
EssOtlGetOriginalMember
Returns the original member name of a shared or extended shared member. If the member is
not shared, the return value is NULL. This function returns the fully qualified original member
name.
Syntax
ESS_FUNC_M EssOtlGetOriginalMember (hOutline, hMember, ppOriMember);
hMember ESS_HMEMBER_T Member name (input).
ppOriMember ESS_PSTR_T The original member name (output).
Notes
l This function works in both edit and query modes.
l If you use this function on an outline in which all member names are unique, it will have
no effect.
l In an outline that allows duplicate member names, if the member handle passed in is an
extended shared member or a regular shared member, this function returns its original
member as a path expression.
l Given the following hierarchy, if you pass to this function the member handle corresponding
to [Diet].[100-10], it returns [200].[100-10].
100
100-10
200
100-10 (duplicate)
Diet
100-10 (shared with [200.100-10])
855
Return Value
Example
The "original member" returned for the Sample Basic shared member 100-10 is [100].
[100-20].
ESS_FUNC_M ESS_GetOrigMember()
{
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMember = ESS_NULL, ChildMember = ESS_NULL;
ESS_STR_T OriMember;

Object.hCtx = hCtx;

// sts = EssOtlOpenOutlineQuery (hCtx, &Object, &hOutline);
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Diet", &hMember);
}
//Get member handle for shared member "100-10"

{
sts = EssOtlGetChild(hOutline, hMember, &ChildMember);
}
if (!sts && ChildMember)

{
sts = EssOtlGetOriginalMember (hOutline, ChildMember, &OriMember);
printf("Original member for shared member \"100-10\" is: %s", OriMember);
}
856
return sts;
}
See Also
l EssOtlSetOriginalMember
EssOtlGetOutlineInfo
Returns information about the outline file.
Syntax
ESS_FUNC_M EssOtlGetOutlineInfo (hOutline, ppInfo);
ppInfo “ESS_OUTLINEINFO_T” on page 716 Pointer to a pointer to a structure allocated by the API for storing
outline information.
Notes
Use EssFree() to free the information structure.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
857
{
sts = EssOtlGetOutlineInfo(hOutline, &pInfo);
}
if(pInfo)
{
EssFree(hInst, pInfo);
}
See Also
l EssFree
l EssOtlSetOutlineInfo
EssOtlGetParent
Returns the parent of a member.
Syntax
ESS_FUNC_M EssOtlGetParent (hOutline, hMember, phMember);
hMember ESS_HMEMBER_T Handle of member to retrieve the parent of.
phMember ESS_PHMEMBER_T Pointer for return of a member handle of the parent of the hMember parameter.
Notes
If there is no parent, *phMember is set to ESS_NULL and the call returns 0. (The hMember is a
dimension.)
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;
858

if (!sts)
{
&hMemberChild);
}
if (!sts && hMemberChild)

{
sts = EssOtlGetParent(hOutline,
hMemberChild, &hMemberParent);
}
See Also
l EssOtlGetChild
EssOtlGetPrevSibling
Returns the previous sibling of a member.
Syntax
ESS_FUNC_M EssOtlGetPrevSibling (hOutline, hMember, phMember);
hMember ESS_HMEMBER_T Handle of member to retrieve the previous sibling of.
phMember ESS_PHMEMBER_T Pointer for return of a member handle of the previous sibling of the hMember
parameter.
Notes
If there is no previous sibling, *phMember is set to ESS_NULL and the call returns 0.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
859
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberFeb;
ESS_HMEMBER_T hMemberSibling;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Feb",
&hMemberFeb);
}
if (!sts && hMemberFeb)

{
sts = EssOtlGetPrevSibling(hOutline,
hMemberFeb, &hMemberSibling);
}
See Also
l EssOtlGetParent
l EssOtlGetChild
EssOtlGetQueryHint
Returns the query hint indicated by the input outline and hint number.
Syntax
ESS_FUNC_M EssOtlGetQueryHint (hOutline, hintNum, numMembers, pMemberArray);
860
numMembers ESS_SHORT_T Number of members that the array provided is able to hold - usually the number
of real dimensions in the outline (input)
array needs to be allocated with size numMembers. (Output)
Notes
Return Value
Example
/* clear array just to be safe */

memset(hMember, 0x00, 10*sizeof(ESS_HMEMBER_T));

for (i = 0; i < nmHints; i++)

{
hintNum = i+1;
sts = EssOtlGetQueryHint(hOutline, hintNum, 10, hMember);
for (j = 0; j < 10; j++)

{
if (hMember[j] != AD_NULL)
{
sts = EssOtlGetMemberInfo(hOutline, hMember[j], &pMemberInfo);
printf("Hint (%d), member (%d): [%s]\n",
hintNum, j, pMemberInfo->szMember);
/* Code to free pMemberInfo omitted */
}
else
{
861
printf("Hint (%d), member (%d): [NULL]\n", hintNum, j);
}
}
}
See Also
EssOtlGetQueryHintSize
Returns the size (in number of members) of the query hints defined on the outline.
Syntax
ESS_FUNC_M EssOtlGetQueryHintSize (hOutline, pHintSize);
pHintSize ESS_SHORT_T Query hint size (output).
Notes
Usually the number of members in a query hint is the same as the number of real dimensions.
But if you add or delete dimensions after the hints were added, the number of members in the
hMember array might be different than the number of real dimensions. This function returns
how large the member array should be in GetQueryHint.
Return Value
See Also
862
EssOtlGetSmartListInfo
Returns the Text List (SmartList) information for the Text List (SmartList) passed in the
hSmartList handle. This must be followed by an EssOtlFreeSmartListInfo call on
ppSmartListInfo.
Syntax
ESS_FUNC_M EssOtlGetSmartListInfo(hOutline, hSmartList, **ppSmartListInfo);
hSmartlist ESS_HSMARTLIST_T Text List (SmartList) handle
**ppSmartListInfo ESS_SMARTLISTINFO_T Contains the Text List (SmartList) information structure.
Return Value
Returns:
l 0—If successful
ppSmartListInfo contains the Text List (SmartList) information.
ppSmartListInfo is NULL.
Example
DisplaySmartListInfo(ESS_HOUTLINE_T hOutline, ESS_PHOBJECT_T ObjHandles)
{
ESS_PSMARTLISTINFO_T SmartListInfo;
ESS_ULONG_T i;
sts = EssOtlGetSmartListInfo(hOutline, ObjHandles,

&SmartListInfo);
if(!sts)
{
printf("\n");
printf("\tName: %s\n", SmartListInfo->szName);
printf("\tMissing Name: %s\n",
SmartListInfo->szMissingName);
printf("\tOut of Range Name: %s\n",
SmartListInfo->szOutOfRangeName);
printf("\tusLen: %d\n", SmartListInfo->usLen);
for (i = 0; i < SmartListInfo->usLen; i++)
{
printf("\tpIDs: %d, \tpszText[%d]: %s\n",
SmartListInfo->pIDs[i], i,
SmartListInfo->ppszText[i]);
}
printf("\n");
}
else
printf("\t\tEssOtlGetSmartListInfo sts: %d\n",sts);
863
if(SmartListInfo)
sts = EssOtlFreeSmartListInfo(hOutline, SmartListInfo);
EssOtlGetServerDateFormats
This function returns the list of server date formats supported.
Syntax
ESS_FUNC_M EssOtlGetServerDateFormats(
ESS_HCTX_T hCtx,
ESS_STR_T localeStr,
ESS_USHORT_T* pcount,
ESS_STR_T** ppdateStrings,
ESS_STR_T** ppformatStrings)
hCtx ESS_HCTX_T Server context handle
localeStr ESS_STR_T Locale in which the example date Strings to be generated.

l If localeStr is empty, the default environment locale is used to generate
thedate Strings
l If localeStr is invalid, invalid error message is returned
l If localeStr is null, error message is returned
pcount ESS_USHORT_T* Count of date formats supported
ppdateStrings ESS_STR_T** Returns the example current date in different date formats as an array (to be de
allocated).
ppformatStrings ESS_STR_T** Returns the array of formats supported (to be de allocated).
Return Value
Returns:
l 0—If successful
Values are contained in ppdateStrings and ppformatStrings.
Example
{
864

Object.hCtx = hCtx;


printf("\n");

{
pformatStrings[i]);
&dateFormatString);
}
}
See Also
l EssOtlSetDateFormatString
l EssOtlGetDateFormatString
EssOtlGetUpdateTime
Returns a timestamp for the specified outline.
Syntax
865
hOutline; ESS_HOUTLINE_T Outline handle
pOtlTimeStamp; ESS_PTIME_T Pointer to the timestamp for the outline
Notes
l The value for time, of type ESS_ULONG_T, is represented by the number of seconds since
00:00:00 1/1/1970 GMT.
l The value for time is not persistent; that is, the value for time is reset whenever the server
loads the database.
Return Value
Returns the timestamp for the specified outline.
Example
sts = EssOtlGetUpdateTime(hOutline, &TimeStamp);
See Also
l EssOtlSetOutlineInfo
l EssOtlSortChildren
l EssOtlGenerateCurrencyOutline
EssOtlGetUserAttributes
Retrieves all user-defined attributes for a member.
Syntax
ESS_FUNC_M EssOtlGetUserAttributes (hOutline, hMember, pusCount,
ppAttributeList);
hMember ESS_HMEMBER_T Handle of member for which to get the user-defined attribute.
pusCount ESS_PUSHORT_T Count of user attributes returned; defines the number of elements in the
ppAttributeList array.
ppAttributeList ESS_PPMBRNAME_T Array of *pusCount members. Each element of the array contains a single user-
defined attribute string.
866
Notes
l A caller can set any number of user-defined attributes for a member using the
EssOtlSetUserAttribute() call. Each attribute is defined as a unique string that follows the
same conventions as member names.
l A user attribute can be the same as any member name, alias, or generation or level name.
l Call EssFree() to free the returned attribute list.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_PMBRNAME_T AttributeList = ESS_NULL;

Object.hCtx = hCtx;

/************ Get User Attributes ***********/
if (!sts)
{
&hMember);
}

{
sts = EssOtlGetUserAttributes(hOutline,
hMember, &Count, &AttributeList);
}
if (!sts && AttributeList)

{
printf("User Attribute:\n");
867
for(ind = 0; ind < Count; ind++)
{
printf("%s\n",AttributeList[ind]);
}
EssFree(hInst, AttributeList);
}
See Also
l EssOtlDeleteUserAttribute
l EssOtlSetUserAttribute
EssOtlImportExportObject
Imports or exports the contents of the input object to the input file based on bImport being true
or false.
Syntax
ESS_FUNC_M EssOtlImportExportObject(hOutline, objHandle, FileName, bImport)
objHandle ESS_HOBJECT_T Object handle to be imported or exported
FileName ESS_STR_T Name of the file to which object needs to be exported or imported from
bImport ESS_BOOL_T l true

Import
l false
Export
Return Value
Returns:
l 0—If successful
Example
void TestImportExportObject()
{
ESS_PHOBJECT_T hObjHandles;
ESS_STR_T sFileName;
ESS_BOOL_T bImport;
ESS_STR_T objName = "";
868
Object.hCtx = hCtx;

/* Create an object for the test */

objName = "CSRatings";

/* Import a SmartList */
sFileName = "F:\\testArea\\Smartlist\\ImpCSRatingsSL.txt";
bImport = ESS_TRUE;
sts = EssOtlImportExportObject(hOutline, hObjHandle,
sFileName, bImport);
printf("EssOtlImportExportObject sts: %ld\n",sts);
/* Verify import results */

&Count, &hObjHandles);
for (i = 0; i < Count; i++)
DisplaySmartListInfo(hOutline, hObjHandles[i]);
printf("\n");
objName = "CSRatings";
printf("EssOtlFindObject sts: %ld\n",sts);
/* Export a SmartList */
bImport = ESS_FALSE;
sFileName = "F:\\testArea\\Smartlist\\ExpCSRatingsSL.txt";
sts = EssOtlImportExportObject(hOutline, hObjHandle,
sFileName, bImport);
/* Close */
}
See Also
869
l EssOtlFindObject
l EssOtlListObjects
EssOtlIsMemberNameNonUnique
Discovers if a member name is duplicate.
Syntax
ESS_FUNC_M EssOtlIsMemberNameNonUnique (hOutline, hMember, fNameNonUnique);
hMember ESS_HMEMBER_T The member to query for non-uniqueness (input).
*fNameNonUnique ESS_BOOL_T TRUE if the member queried is a duplicate member name (output).
Notes
l Before you call this function, call EssOtlOpenOutline to open the outline in editing mode.
l Use aMember Traversal Function to get a member handle for the second argument of this
function.
l This function checks whether a member name is duplicated. If a member name is duplicated,
you might be interested in getting the fully qualified name of a member (its unique name
or its key), because if a non specific name is used by other functions in your program to
refer to a member name that is duplicated, unexpected behavior could occur.
l However, if all names are unique, you do not need to spend the resources to use fully qualified
names or keys.
l After you use this function, if you discover that a member name is duplicated, you can get
the fully qualified name and save it somewhere using EssOtlGetMemberUniqueName.
Return Value
870
Example
ESS_FUNC_M ESS_ISUniqMemberName()
{
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberParent, hMemberChild;

Object.hCtx = hCtx;
sts = EssOtlOpenOutline(hCtx, &Object, ESS_FALSE,

if (!sts)
{
sts = EssOtlFindMember(hOutline, "2004", &hMemberParent);
}

{
sts = EssOtlGetChild(hOutline, hMemberParent, &hMemberChild);
}
if (!sts)
{
//Check whether Qtr1 is unique member name, returns 0 if unique and 1 if non-unique
sts = EssOtlIsMemberNameNonUnique (hOutline, hMemberChild, &pbNameUnique);
if (sts)
printf("EssOtlIsMemberNameNonUnique failed sts %ld\n",sts);
}
return sts;
}
See Also
l EssOtlIsMemberNameUniqueWithinDim
l EssOtlIsMemberNameUniqueWithinDimAtGenLevel
871
EssOtlIsMemberNameUniqueWithinDim
Discovers if member names are all unique within a dimension.
Syntax
ESS_FUNC_M EssOtlIsMemberNameUniqueWithinDim (hOutline, hDim, *pbNameUnique);

*pbNameUnique ESS_BOOL_T TRUE if the dimension queried contains no duplicate member names; FALSE
otherwise.
Notes
l This function is one of three functions that query for member name uniqueness or non
uniqueness.
m EssOtlIsMemberNameNonUnique discovers if a member name is duplicate within an
outline.
m EssOtlIsMemberNameUniqueWithinDim discovers if all member names are unique
within a dimension.
m EssOtlIsMemberNameUniqueWithinDimAtGenLevel discovers if all member
names are unique within a dimension at the generation or level specified.
l Before you call this function, call EssOtlOpenOutlineQuery() to open the outline in query
mode.
Return Value
Example
ESS_FUNC_M ESS_ISUniq()
{
ESS_STS_T sts = 0;
ESS_BOOL_T pbNameUnique = 0;

Object.hCtx = hCtx;
872
if (!sts)
{
if (sts)
}
if (!sts)
{
sts = EssOtlIsMemberNameUniqueWithinDim (hOutline, hDim, &pbNameUnique);
if (sts)
printf("EssOtlIsMemberNameUniqueWithinDim failed sts %ld\n",sts);
else
printf("pbNameUnique is %d\n", pbNameUnique);
}
return sts;
}
See Also
l EssOtlGetCountOfDupMemberNameInDim
l EssOtlIsMemberNameNonUnique
l EssOtlIsMemberNameUniqueWithinDimAtGenLevel
EssOtlIsMemberNameUniqueWithinDimAtGenLevel
Discovers if all member names are unique within a dimension at the generation or level specified.
Syntax
ESS_FUNC_M EssOtlIsMemberNameUniqueWithinDimAtGenLevel (hOutline, hDim, bGen,
usGenLevel, *pbNameUnique);

bGen ESS_BOOL_T Input. If TRUE, usGenLevel is considered a generation number. If FALSE,

usGenLevel is considered a level number.
873
usGenLevel ESS_USHORT_T Input generation or level number.
*pbNameUnique ESS_BOOL_T Output. TRUE if the dimension queried contains duplicate member names at
the generation or level specified; FALSE otherwise.
Notes
l This function is one of three functions that query for member name uniqueness or non
uniqueness.
m EssOtlIsMemberNameNonUnique discovers if a member name is duplicate within an
outline.
m EssOtlIsMemberNameUniqueWithinDim discovers if all member names are unique
within a dimension.
m EssOtlIsMemberNameUniqueWithinDimAtGenLevel discovers if all member names
are unique within a dimension at the generation or level specified.
l Before you call this function, call EssOtlOpenOutlineQuery() to open the outline in query
mode.
Return Value
Example
ESS_FUNC_M ESS_ISUniqMemberNameWithinDimatGenLev()
{
ESS_STS_T sts = 0;
ESS_HMEMBER_T hDim,hNextDim;
ESS_BOOL_T pbNameUnique, bGen = ESS_TRUE;
ESS_USHORT_T usGenLevel = 3;

Object.hCtx = hCtx;
if (!sts)
874
{
if (sts)
}
if (!sts)
{
sts = EssOtlIsMemberNameUniqueWithinDimAtGenLevel (hOutline, hDim, bGen, usGenLevel,
&pbNameUnique);
if (sts)
printf("EssOtlIsMemberNameUniqueWithinDimAtGenLevel failed sts %ld\n",sts);
else
}
if (!sts)
{
sts = EssOtlQueryGetNextDimension (hOutline, hDim, &hNextDim);
if (sts)
}
if (!sts)
{
sts = EssOtlIsMemberNameUniqueWithinDimAtGenLevel (hOutline, hNextDim, bGen,
usGenLevel, &pbNameUnique);
if (sts)
else
}
return sts;
}
See Also
l EssOtlGetCountOfDupMemberNameInDim
l EssOtlIsMemberNameNonUnique
EssOtlListObjects
Returns an array of all object handles of the specified type.
Syntax
ESS_FUNC_M EssOtlListObjects(hOutline, objType, pCount, pObjHandles)
875

pCount ESS_ULONG_T* Count of object handles
pObjHandles ESS_PPHOBJECT_T Returns an array of object handles. Must be deallocated using EssFree.
Return Value
Returns:
l 0—If successful
pCount and pObjHandles contain values.
pCount and pObjHandles are NULL.
Example
{
ESS_STR_T objName;

Object.hCtx = hCtx;
/* Open outline */

876
/* Save */
/* Find objects */
objName = "SList1";
&hObjHandle);
if(ObjHandles)
/* Close outline */
}
See Also
l EssOtlFindObject
l EssOtlListObjects
EssOtlMoveMember
Moves a member.
Syntax
ESS_FUNC_M EssOtlMoveMember (hOutline, hMember, hNewParent, hNewPrevSibling);
877
hMember ESS_HMEMBER_T Handle of member to move
hNewParent ESS_HMEMBER_T Handle of new parent. Use this field only if the hNewPrevSibling field is
ESS_NULL.
hNewPrevSibling ESS_HMEMBER_T Handle of new previous sibling
Notes
l The moved member is inserted following the hPrevSibling member. If this field is ESS_NULL,
the moved member becomes the first child of the parent specified by hParent.
l If both hParent and hPrevSibling are ESS_NULL, the moved member becomes the first
dimension in the outline.
l Moving a zero-level (leaf node) attribute member that is not of type
ESS_ATTRMBRDT_STRING resets the member's long name, using the specifications for
the outline in the “ESS_ATTRSPECS_T” on page 113 structure.
l Moving an ancestor may affect the long name of a zero-level attribute member.
Return Value
OTLAPI_BAD_MOVE
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMemberMar;

Object.hCtx = hCtx;

878
if (!sts)
{
&hMemberJan);
}

{
sts = EssOtlFindMember(hOutline, "Mar",
&hMemberMar);
}
if (!sts && hMemberMar)

{
sts = EssOtlMoveMember(hOutline, hMemberJan,
ESS_NULL, hMemberMar);
}
See Also
l EssOtlFindMember
l EssOtlRenameMember
l EssOtlAddMember
EssOtlNewOutline
Creates an outline without creating a file. This call is used as an alternative to
EssOtlOpenOutline().
Syntax
ESS_FUNC_M EssOtlNewOutline (hCtx, pNewInfo, phOutline);
hCtx ESS_HCTX_T Essbase Context handle.
pNewInfo “ESS_OUTLINEINFO_T” on page Structure describing the new outline.

716
phOutline ESS_PHOUTLINE_T Pointer to ESS_HOUTLINE_T variable. This handle is set by the API
and should be passed in to subsequent Outline API functions.
Notes
l This function creates an empty outline in memory.
l No transactions are kept when this call is used. See EssOtlOpenOutline() for more
information on keeping transactions.
Return Value
879
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

&hOutline);
See Also
l EssOtlOpenOutline
l EssOtlRestructure
l EssOtlCloseOutline
EssOtlOpenOutline
Opens and reads in an existing outline. This function (or EssOtlNewOutline) must be called
before any operations on the outline can take place.
Syntax
ESS_FUNC_M EssOtlOpenOutline (hCtx, pObject, fLock, fKeepTrans, phOutline);
pObject ESS_POBJDEF_T Pointer to an object structure defining the outline object to open.
fLock ESS_BOOL_T Flag to determine if the outline should be locked when it is opened. This is valid
only for server outlines.
fKeepTrans ESS_BOOL_T Flag to determine whether to keep transactions.

If you are opening an existing outline to make changes, and you intend to
restructure the database and keep data, we recommend that you set this flag to
ESS_TRUE. When ESS_TRUE, a log is kept of activities done to the outline.
If you are starting from an empty outline or are not planning on saving data when
you restructure, we recommend that you set this field to ESS_FALSE. When
ESS_FALSE, no log is kept, saving time and memory.
phOutline ESS_PHOUTLINE_T Pointer to an ESS_HOUTLINE_T variable. This handle is set by the API and should
be passed to subsequent Outline API functions.
Notes
l For Unicode mode outlines, use EssOtlOpenOutlineEx.
l If the outline file exists on the server, this call copies the file locally for client access.
880
l For aggregate storage database outlines, this function keeps the outline open until
EssOtlCloseOutline is called. Because aggregate storage outlines are paged into memory
(instead of being read entirely into memory) the outline is kept open. As a result, temporary
files remain in your computer's Temp folder until EssOtlCloseOutline is called.
Return Value
l OTLAPI_BAD_OBJTYPE
l OTLAPI_ERR_FILEOPEN
l OTLAPI_ERR_FILEIO
Access
This function requires you to have the appropriate level of access to the specified application
and/or database to contain the outline object. To lock the outline object (lock flag is ESS_TRUE),
you must have Application Designer or Database Designer privilege (ESS_PRIV_APPDESIGN
or ESS_PRIV_DBDESIGN) for the specified application or database containing the outline.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;
See Also
l EssOtlOpenOutlineEx
l EssOtlNewOutline
l EssOtlRestructure
881
EssOtlOpenOutlineEx
Opens and reads in an existing outline, identifying the correct locale. This function (or
EssOtlNewOutline()) must be called before any operations on the outline can take place.
Syntax
ESS_FUNC_M EssOtlOpenOutlineEx(hCtx, pObject, fLock, fKeepTrans, pLocaleDescription,
phOutline);
pObject ESS_POBJDEF_T Pointer to an object structure defining the outline object to open.
fLock ESS_BOOL_T Flag to determine if the outline should be locked when it is opened. This is
valid only for server outlines.
fKeepTrans ESS_BOOL_T Flag to determine whether to keep transactions.

If you are opening an existing outline to make changes, and you intend to
restructure the database and keep data, we recommend that you set this
flag to ESS_TRUE. When ESS_TRUE, a log is kept of activities done to the
outline.
If you are starting from an empty outline or are not planning on saving
data when you restructure, we recommend that you set this field to
ESS_FALSE. When ESS_FALSE, no log is kept, saving time and memory.
pLocaleDescription The identifier used by GlobalC to identify the Locale.

The LocaleDescription is in the form of:
[language]_[territory].[codepage]@[sort]
For example: Japaness_japan.MS932@binary to provide the

locale description of the language of the outline file. It is the program’s
responsibility to pass pLocaleDescription in the current format.
phOutline ESS_PHOUTLINE_T Pointer to an ESS_HOUTLINE_T variable. This handle is set by the API
and should be passed to subsequent Outline API functions.
Notes
l This function works like EssOtlOpenOutline(), but with the addition of a Unicode-specific
LocaleDescription argument.
l If the outline file exists on the server, this call copies the file locally for client access.
l For aggregate storage database outlines, EssOtlOpenOutline keeps the outline open until
EssOtlCloseOutline is called. Because aggregate storage outlines are paged into memory
(instead of being read entirely into memory) the outline is kept open. As a result, temporary
files remain in your computer's Temp folder until EssOtlCloseOutline is called.
Return Value
882
l OTLAPI_ERR_FILEIO
Access
and/or database to contain the outline object. To lock the outline object (lock flag is ESS_TRUE),
you must have Application Designer or Database Designer privilege (ESS_PRIV_APPDESIGN
or ESS_PRIV_DBDESIGN) for the specified application or database containing the outline.
See Also
l EssOtlNewOutline
l EssOtlRestructure
l EssOtlWriteOutlineEx
EssOtlOpenOutlineQuery
Opens an existing outline.
Syntax
ESS_FUNC_M EssOtlOpenOutlineQuery (hCtx, pObject, phOutline);
hCtx ESS_HCTX_T Outline context handle. This must be a valid server login context.
pObject ESS_POBJDEF_T Pointer to object structure defining the outline object to open. Currently this is
ignored. You should call EssSetActive() for the database you are accessing.
phOutline ESS_PHOUTLINE_T Pointer to an ESS_HOUTLINE_T variable. This will be set by the API and should
be passed in to subsequent API functions.
Notes
l Use this function to access an outline using EssOtlQueryMembers().
l The call will not download the outline and load the entire file into memory.
l Therefore, many of the outline API calls will not work with hOutline that is passed back
from this call.
l The following calls are accessible after this call is made. All other Outline API calls will return
an error.
m EssOtlCloseOutline
m EssOtlGetMemberAlias
m EssOtlGetMemberFormula
883
m EssOtlGetMemberInfo
m EssOtlGetNextAliasCombination
m EssOtlGetOutlineInfo
m EssOtlGetUserAttributes
m EssOtlGetGenName
m EssOtlGetGenNames
m EssOtlGetLevelName
m EssOtlGetLevelNames
m EssOtlGetMemberLastFormula
Return Value
l OTLAPI_ERR_FILEIO
Example
#include <essapi.h>
#include <essotl.h>

ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
if ( sts == 0)
{
}
See Also
l EssOtlOpenOutline
l EssSetActive
884
EssOtlPutSmartList
Populates the contents of the Text List (SmartList) handle created by EssOtlCreateObject. The
object handle created can be typecast to an ESS_HSMARTLIST_T handle.
Verification rules:
l Each entry in pIDs and in ppszText must be unique
l The strings in ppszText must pass the same name validation rules as specified for text list
names.
l ppszText text strings may not be empty, #OUTOFRANGE, or the same as
pszMissingName or pszOutofRangeName
l The number of entries len cannot be more than 1024.
Syntax
ESS_FUNC_M EssOtlPutSmartList(hOutline, hSmartList, len, *pIDs, *ppszText,
pszMissingName, pszOutofRangeName);
hOutline ESS_HOUTLINE_T The source Essbase outline for the text list.
hSmartList ESS_HSMARTLIST_T Text list handle
len ESS_UINT16 Number of items
*pIDs ESS_UINT32_T Integer IDs
*ppszText ESS_STR_T Enumerated text
pszMissingName ESS_STR_T Name of the missing smart text
pszOutofRangeName ESS_STR_T Name of the out of range smart text.
Return Value
Returns:
l 0—If successful
pIDs and ppszText contain values.
pIDs and ppszText are NULL.
Example
void TestPutSmartList()
{
ESS_PHOBJECT_T hObjHandles;
ESS_PSMARTLISTINFO_T SmartListInfo = ESS_NULL;
885
ESS_USHORT_T len;
ESS_SMARTLISTID_T pIds[4];
ESS_STR_T ppszText[4];
ESS_STR_T pszMissingName;
ESS_STR_T pszOutOfRangeName;
ESS_STR_T smartListNames[3] =
{ "MainColors", "TempColors1", "TempColors2" };

Object.hCtx = hCtx;
/* Open outline */
/* Create a SmartList */
smartListNames[0], &hObjHandle);
/* Set up and put SmartList */

len = 4;
pIds[0] = 1;
pIds[1] = 2;
pIds[2] = 3;
pIds[3] = -1;
ppszText[0] = "Red";
ppszText[1] = "Green";
ppszText[2] = "Blue";
ppszText[3] = "Yellow";
pszMissingName = "Missing";
pszOutOfRangeName = "OutOfRange";
sts = EssOtlPutSmartList(hOutline, hSmartList,
len, pIds, ppszText, pszMissingName,
pszOutOfRangeName);
/* Clean up */
for(i = 0; i <= 12; i++)
{
smartListNames[i], &hObjHandle);
}
886
&Count, &hObjHandles);
for (i = 0; i < Count; i++)
DisplaySmartListInfo(hOutline, hObjHandles[i]);
if(hObjHandles)
EssFree (hInst, hObjHandles);

}
EssOtlQueryAttributes
Queries member information for a given attribute member or dimension.
Syntax
pAttributeQuery; “ESS_ATTRIBUTEQUERY_T” on page 707 Structure that defines the query
pCount; ESS_PULONG_T Number of member handles returned
pphMemberArray; ESS_PPHMEMBER_T Pointer to an array of member handles returned
Notes
Before you call this function, call EssOtlOpenOutlineQuery to open the outline in query
mode.
Example
void ESS_OtlQueryAttributes()
{
ESS_SHORT_T hOutlineQuery;
ESS_ATTRIBUTEQUERY_T pAttributeQuery;
ESS_PHMEMBER_T phMemberArray = ESS_NULL;
int index;
memset(&pAttributeQuery, 0x00, sizeof(ESS_ATTRIBUTEQUERY_T));

Object.hCtx = hCtx;
887
sts = EssOtlOpenOutlineQuery(hCtx, &Object, &hOutlineQuery);

printf("EssOtlOpenOutlineQuery() sts: %ld\n",sts);
pAttributeQuery.bInputMemberIsHandle == ESS_FALSE;
pAttributeQuery.uInputMember.szMember = "100-10";
pAttributeQuery.usInputMemberType = ESS_BASE_MEMBER;
pAttributeQuery.usOutputMemberType = ESS_ATTRIBUTE_MEMBER;
pAttributeQuery.usOperation = ESS_ALL;
pAttributeQuery.Attribute.usDataType = ESS_ATTRMBRDT_NONE;
sts = EssOtlQueryAttributes(hOutlineQuery, &pAttributeQuery, &Count, &phMemberArray);

printf("EssOtlQueryAttributes() sts: %ld\n",sts);
if (!sts && phMemberArray)

{
printf("\n------- Query Results -------\n");
{
sts = EssOtlGetMemberInfo(hOutlineQuery,phMemberArray[index],&pMbrInfo);
printf("\t%s\n",pMbrInfo->szMember);
}
if (Count && phMemberArray)

{
sts = EssOtlFreeMembers(hOutlineQuery,Count, phMemberArray);
}
}
}
See Also
l EssFreeStructure
888
Queries member information for a given attribute member or dimension.
Syntax
pAttributeQuery; “ESS_ATTRIBUTEQUERY_T” on page 707 Structure that defines the query
pCount; ESS_PMBRCOUNTS_T Number of member handles returned
pphMemberArray; ESS_PPHMEMBER_T Pointer to an array of member handles returned
Notes
Before you call this function, call EssOtlOpenOutlineQuery to open the outline in query
mode.
See Also
l EssFreeStructure
EssOtlQueryGenerationInfo
EssOtlQueryGenerationInfo() queries for the time dimension generation information
contained in the comment field for the dimension's top member. Once this information is
known, it can be used with EssOtlGetLinkedAttributeAttachLevel() to provide period over
period analysis.
Syntax
ESS_FUNC_M EssOtlQueryGenerationInfo (hOutline, szName, queryID, ppReturns);
889
hOutline ESS_HOUTLINE_T Outline handle. This must have been returned from EssOtlOpenOutlineQuery().
szName ESS_STS_T Name of the top member of the date-time dimension
queryID ESS_ULONG_T Use the query identifier constant ESS_OTLQRYTIDIM_TIMEPERIODS
ppReturns ESS_PPVOID_T A pointer to the query information structure for this dimension.
Notes
The caller of EssOtlQueryGenerationInfo() should call EssOtlFreeStructure() with structure
ID ESS_DT_STRUCT_TIGENINFO to free the memory set aside for the returned structure pointer.
Return Value
If successful, returns a pointer to a ESS_PTIMEDIM_GENINFO_T structure.
Example
SS_STR_T strBuf1 = "Year";
ESS_ULONG_T queryId = ESS_OTLQRYTIDIM_TIMEPERIODS;
ESS_PVOID_T pReturns;
ESS_PTIMEDIM_GENINFO_T tpStruc = NULL;
sts = EssOtlQueryGenerationInfo (hOutline, /*query outline handle*/

strBuf1, /* IN - date-time dimension member name*/
queryId, /* IN - query ID */
&pReturns);
if (sts)
goto exit;
switch (queryId)
{
case ESS_OTLQRYTIDIM_TIMEPERIODS:
tpStruc = (ESS_PTIMEDIM_GENINFO_T)pReturns;
for (ii = 0; ii < tpStruc->usCount; ii++)

fprintf(cmdctxp->output, "Time period for Gen %d = %s\n", ii+1, TimePeriodNames[tpStruc->ptps[ii]]);
sts = EssOtlFreeStructure (cmdctxp->hOutline[hOutlineChoice], ESS_DT_STRUCT_TIGENINFO,

1, pReturns);
if (sts)
goto exit;
break;
890
default:
break;
}
See Also
l EssOtlGetLinkedAttributeAttachLevel
EssOtlQueryGetFirstDimension
Returns the dimension handle of the first dimension in the outline.
Syntax
hOutline; ESS_HOUTLINE_T Handle to the outline (input).
phDim; ESS_PHMEMBER_T The dimension handle (output).
Notes
mode.
l This function returns the dimension handle of the first dimension in the outline. The handle
returned by this function can then be used to call
EssOtlGetDimensionNameUniqueness, EssOtlGetCountOfDupMemberNameInDim,
or EssOtlIsMemberNameUniqueWithinDim.
Return Value
Example
ESS_FUNC_M ESS_ISUniq()
{
ESS_STS_T sts = 0;
ESS_BOOL_T pbNameUnique = 0;

Object.hCtx = hCtx;
891
if (!sts)
{
if (sts)
}
if (!sts)
{
sts = EssOtlIsMemberNameUniqueWithinDim (hOutline, hDim, &pbNameUnique);
if (sts)
printf("EssOtlIsMemberNameUniqueWithinDim failed sts %ld\n",sts);
else
}
return sts;
}
See Also
l EssOtlQueryGetNextDimension
EssOtlQueryGetNextDimension
Returns the next dimension handle of the dimension in the outline opened in query mode.
Syntax
hOutline; ESS_HOUTLINE_T Handle to the outline (input)
hDim; ESS_HMEMBER_T The dimension handle (input)
phNextDim; ESS_PHMEMBER_T The handle of the next dimension (output)
892
Notes
mode.
l As shown in the example, you must call EssOtlQueryGetFirstDimension before you
call this function. Otherwise, an error will be returned.
l If you pass in the handle of the dimension that appears last in the dimension, this function
returns null.
Return Value
Example
ESS_FUNC_M ESS_ISUniqMemberNameWithinDimatGenLev()
{
ESS_STS_T sts = 0;
ESS_HMEMBER_T hDim,hNextDim;
ESS_BOOL_T pbNameUnique, bGen = ESS_TRUE;
ESS_USHORT_T usGenLevel = 3;

Object.hCtx = hCtx;
if (!sts)
{
if (sts)
}
if (!sts)
{
sts = EssOtlIsMemberNameUniqueWithinDimAtGenLevel (hOutline, hDim, bGen, usGenLevel,
&pbNameUnique);
if (sts)
893
else
}
if (!sts)
{
sts = EssOtlQueryGetNextDimension (hOutline, hDim, &hNextDim);
if (sts)
}
if (!sts)
{
sts = EssOtlIsMemberNameUniqueWithinDimAtGenLevel (hOutline, hNextDim, bGen,
usGenLevel, &pbNameUnique);
if (sts)
else
}
return sts;
}
See Also
l EssOtlQueryGetFirstDimension
EssOtlQueryMembers
Queries the outline.
Syntax
ESS_FUNC_M EssOtlQueryMembers (hOutline, hMember, pPredicate, pMbrCounts, phMemberArray);
EssOtlOpenOutlineQuery.
894
hMember ESS_HMEMBER_T The handle of the member on which execute the operation. If this value
is NULL, it is assumed to be the very top of the outline, representing
the logical parent of the dimensions.
If the handle is a shared member, this function executes on the stored
member on which it is based.
This value will be ignored for the following options:
l ESS_NAMEDLEVEL
l ESS_USERATTRIBUTE
l ESS_SEARCH
l ESS_WILDSEARCH
pPredicate “ESS_PREDICATE_T” on Structure defining the query. The fields of this structure are described
page 719 in Notes.
pMbrCounts “ESS_MBRCOUNTS_T” Structure defining information about counts. It contains the following
on page 709 fields:
l ulMaxCount—Maximum number of member handles to return
l ulTotalCount—Total number of members that are defined in the
results of the query
l pulReturnCount—Number of member handles returned in this
query
phMemberArray ESS_PPHMEMBER_T An array of member handles returned from the query.
Notes
l The call takes a member handle to operate on and returns an array of member handles
satisfying the criteria specified by the option value.
l The caller should call EssOtlFreeMembers when the returned phMembers member array is
no longer needed.
l Each hMember element in the array can be used only in calls that are listed in
EssOtlOpenOutlineQuery. For example, a returned member handle cannot be used to call
EssOtlGetSibling.
l The fields of the pPredicate structure are used as follows:
m ulQuery—Value defining the operation to perform. It can be one of the following:
o ESS_CHILDREN
o ESS_DESCENDANTS
o ESS_BOTTOMLEVEL
o ESS_SIBLINGS
o ESS_SAMELEVEL
o ESS_SAMEGENERATION
895
o ESS_PARENT
o ESS_DIMENSION
o ESS_NAMEDGENERATION
o ESS_NAMEDLEVEL
o ESS_SEARCH
o ESS_WILDSEARCH
o ESS_USERATTRIBUTE
o ESS_ANCESTORS
o ESS_DTSMEMBERS
m ulOptions—Value defining search options. Valid values:
o ESS_COUNTONLY—Returns no member handles, but fills in the pTotalCount
field in the pCounts structure
o ESS_NOTOTALCOUNTS
o ESS_FORCECASESENSITIVE
o ESS_FORCEIGNORECASE
When the Query type is set to ESS_SEARCH or ESS_WILDSEARCH, three additional

values for Option are valid:
o ESS_MEMBERSONLY
o ESS_ALIASESONLY
o ESS_MEMBERSANDALIASES
To specify multiple values, use bitwise OR ( | ); for example:

ESS_FORCECASESENSITIVE | ESS_MEMBERSONLY
m szDimension—Dimension to limit the scope of the query. It is used with the following
query options and ignored otherwise:
o ESS_NAMEDLEVEL
o ESS_USERATTRIBUTE
o ESS_SEARCH—Set to NULL to search through all dimensions
o ESS_WILDSEARCH—Set to NULL to search through all dimensions
m pszString1—
Input string that is determined by the option. It is used with the following query options
and ignored otherwise:
o ESS_NAMEDGENERATION—Name of the generation
o ESS_NAMEDLEVEL—Name of the level
o ESS_SEARCH—String to search for. The string is defined as an exact match.
896
o ESS_WILDSEARCH—String to search for. The string is defined as an exact search
string with an optional '*' at the end to mean any set of characters.
o ESS_USERATTRIBUTE—User defined attribute.
m pszString2—Input string that is determined by the option. It is used with the following
o ESS_SEARCH, ESS_WILDSEARCH—If the options are set to look in the alias
tables, this string specifies the alias table in which to search. If null, all alias tables
are searched.
Return Value
Example
#include <essapi.h>
#include <essotl.h>

ESS_HMEMBER_T hMember = 0;
ESS_ULONG_T i;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
if ( sts == 0)
{

Predicate.ulQuery = ESS_CHILDREN;
Predicate.pszDimension = "Year";

Counts.ulStart = 0;
if(!sts)
{
sts = EssOtlQueryMembers(hOutline, hMember,
&Predicate, &Counts, &phMemberArray);
897
{
sts = EssOtlFreeMembers(hOutline,
Counts.ulReturnCount, phMemberArray);
}
}
}
See Also
l EssOtlFreeMembers
EssOtlQueryMembersByName
Queries the outline.
Syntax
ESS_FUNC_M EssOtlQueryMembersByName (hOutline, pszMember, pPredicate,
pMbrCounts, phMemberArray);
hOutline ESS_HOUTLINE_T Outline context handle. This must have been returned from
pszMember ESS_STR_T The member name string of the member to do the operation on. If this
value is NULL, it is assumed to be the very top of the outline,
representing the logical parent of the dimensions. This value will be
ignored for the following options:
l ESS_NAMEDLEVEL
l ESS_USERATTRIBUTE
l ESS_SEARCH
l ESS_WILDSEARCH
pPredicate “ESS_PREDICATE_T” on Structure defining the query. The fields of this structure are described
page 719 in Notes.
pMbrCounts “ESS_MBRCOUNTS_T” on Structure defining information about member counts. It contains the
page 709 following fields:
l ulMaxCount—Maximum number of member handles to return.
l ulTotalCount—Total number of members that are defined in the
results of the query.
l pulReturnCount—Number of member handles returned in this
query.
phMemberArray ESS_PPHMEMBER_T An array of member handles returned from the query.
898
Notes
l The call takes a member name string to operate on and returns an array of member handles
satisfying the criteria specified by the option value.
l The caller should call EssOtlFreeMembers() when the returned phMembers member array
is no longer needed.
l Each hMember element in the array can only be used in calls that are listed in
EssOtlOpenOutlineQuery(). For example, a returned member handle cannot be used to
call EssOtlGetSibling().
l The fields of the pPredicate structure are used as follows:
m ulQuery—Value defining the operation to perform. It can be one of the following:
o ESS_CHILDREN
o ESS_DESCENDANTS
o ESS_BOTTOMLEVEL
o ESS_SIBLINGS
o ESS_SAMELEVEL
o ESS_SAMEGENERATION
o ESS_PARENT
o ESS_DIMENSION
o ESS_NAMEDLEVEL
o ESS_SEARCH
o ESS_WILDSEARCH
o ESS_USERATTRIBUTE
o ESS_ANCESTORS
o ESS_DTSMEMBERS
m ulOptions—Value defining search options. Valid values:
o ESS_COUNTONLY—Returns no member handles, but only fills in the
pTotalCount field in the pCounts structure
o ESS_NOTOTALCOUNTS
o ESS_FORCECASESENSITIVE
o ESS_FORCEIGNORECASE
When the Query type is set to ESS_SEARCH or ESS_WILDSEARCH three additional

values for Option are valid:
o ESS_MEMBERSONLY
o ESS_ALIASESONLY
o ESS_MEMBERSANDALIASES
899
To specify multiple values, use bitwise OR ( | ); for example:
ESS_FORCECASESENSITIVE | ESS_MEMBERSONLY
o ESS_NAMEDGENERATION—Name of the generation
o ESS_NAMEDLEVEL—Name of the level
o ESS_SEARCH—String to search for. The string is defined as an exact
o ESS_WILDSEARCH—String to search for. The string is defined as an exact search
string with an optional '*' at the end to mean any set of characters.
o ESS_USERATTRIBUTE—User defined attribute
o ESS_SEARCH, ESS_WILDSEARCH—If the options are set to look in the alias
tables, this string specifies the alias table to search in. If it's null, all alias tables will
be searched.
Return Value
Example
#include <essapi.h>
#include <essotl.h>

ESS_STR_T pszMember;
ESS_ULONG_T i;
ESS_STR_T AppName;
ESS_STR_T DbName;
pszMember = "Qtr1";
AppName = "Sample";
DbName = "Basic";
if ( sts == 0)
{
900
Predicate.ulQuery = ESS_CHILDREN;
Predicate.pszDimension = "Year";

Counts.ulStart = 0;
if(!sts)
{
sts = EssOtlQueryMembersByName(hOutline, pszMember,
&Predicate, &Counts, &phMemberArray);

{
sts = EssOtlFreeMembers(hOutline,
Counts.ulReturnCount, phMemberArray);
}
}
}
See Also
l EssOtlFreeMembers
EssOtlQueryMembersEx
Queries the outline for specific members and member fields, and returns an array of member
handles. The returned member handles can be used with other Outline API functions such as
EssOtlGetMemberInfo(). (EssOtlGetMemberInfo() can retrieve any of the individual fields
contained in “ESS_MEMBERINFO_T” on page 143 and “ESS_MBRINFO_T” on page 709.)
Syntax
ESS_FUNC_M EssOtlQueryMembersEx (hOutline, pszFieldSelection, pszMemberSelection,
pMaxCount, ppMemberArray, ppqryErrorList)
hOutline ESS_HOUTLINE_T Essbase outline handle. This must have been returned
from EssOtlOpenOutlineQuery().
pszFieldSelection ESS_STR_T The query string which defines the set of fields that will
be returned for each member. The syntax of
pszFieldSelection is shown in Notes.
pszMemberSelection ESS_STR_T The query string which defines the set of members to be
returned. The syntax of this query string is the syntax for
member selection; that is, the query string can be
anything that you can use in a FIX() statement.
901
pMaxCount ESS_PULONG_T Input: A pointer to the maximum number of member

handles to be returned.
Output: A pointer to the number of member handles
returned.
ppMemberArray ESS_PPHMEMBER_T Reference to a pointer to the first in an array of member

handles returned.
ppqryErrorList “ESS_OTLQUERYERRORLIST_T” Reference to a pointer to a structure containing the list

on page 713 of errors in the query.
Notes
l In an outline that allows duplicate member names, this function returns the fully qualified
names of shared members. For example, in Sample Basic, any query that includes the shared
member 100-20 would return its fully qualified name, [Diet].[100-20].
l Use of UniqueName as part of the member fields selection automatically includes
ShareOption as part of the field selection.
l EssOtlQueryMemberEx() takes an outline handle and returns an array of member handles
specified by pszMemberSelection.
l The caller should call EssOtlFreeMembers() when the returned pphMembers member array
l Each member handle element of the array can only be used in calls that are listed in
EssOtlOpenOutlineQuery(). For example, a returned member handle cannot be used to call
EssOtlGetSibling().
l The syntax of pszFieldSelection is the following:
QueryString ==: <SelectMbrInfo ( FieldName {, FieldName}, ... )
where FieldName is one of the following:
MemberName /* Member name */

MemberLevel /* Member level number */
MemberGeneration /* Member generation number */
Cosolidation /* Whether this member is consolidated */
TwoPass /* Whether this member undergoes a two pass operation
*/
Expense /* Whether this is an expense member */
CurrencyConvType /* Currency conversion type */
CurrencyMember /* Whether this is a currency member */
TimeBalance /* Time balance measure */
SkipOption /* Whether this member skips the time balance
operation */
ShareOption /* Whether this is a shared member*/
StorageType /* Dimension's storage type */
DimensionCategory /* Dimension category: accounts, time, currency, etc.
*/
DimensionStorageCategory /* Dimension storage category: time, units, scenario,
etc. */
Comment /* Member comment */
ChildrenCount /* Number of children */
902
MemberNumber /* Member number */
DimensionName /* Dimension name */
DimensionNumber /* Dimension number */
MemberAliasName /* Alias for this member */
ParentMemberName /* Parent's name */
ChildMemberName /* Child's name */
PreviousMemberName /* Left sibling's name */
NextMemberName /* Right sibling's name */
CurrencyConversionDatabase /* Whether this database has currency conversion */
MemberStatus /* Member status */
UDAList /* List of UDAs attached to this member */
MemberFormula /* Formula for this member */
MemberValidity /* Whether this member is valid */
Attributes /* All attribute fields. If the member is not
attributed, then attribute name is set to NULL */
UniqueName /* If the member is duplicate, its fully qualified,
unique name. */
Note: There is no leading '<' character for the individual fieldnames.

l To use this function with EssOtlGetMemberField(), include in this function's
pszFieldSelection string the same fields that you will specify using the MbrFieldID constants
of EssOtlGetMemberField(). Otherwise, EssOtlGetMemberField() returns the error
OTLAPI_ERR_MBRINVALID.
Return Value
Example
The following code snippet return the name, consolidation and formula for each menmber
which is a child of Market or a child of Product. Upon return, MaxCount contains the number
of members returned, and phMemberArray contains the array of handles for the set of members
returned. Further Outline API calls allow interrogation of the members using the returned array
of member handles in phMemberArray.
member_fields = "<SelectMbrInfo ( MemberName, Consolidation, MemberFormula ) ";
member_selection = "@ichild(Product), @ichild(Market)";
MaxCount = -1;
phMemberArray = ESS_NULL;
pqryErrorList = ESS_NULL;
sts = EssOtlQueryMembersEx(hOutline,
member_fields,
member_selection,
&MaxCount,
&phMemberArray,
&pqryErrorList);
if (sts != 0) goto error_exit;
903
See Also
l EssOtlFreeMembers
l EssOtlGetMemberField
EssOtlQueryMembersExArray
Queries the outline for specific members and member fields, and returns an array of member
handles. The returned member handles can be used with other Outline API functions such as
EssOtlGetMemberInfo(). (EssOtlGetMemberInfo() can retrieve any of the individual fields
contained in “ESS_MEMBERINFO_T” on page 143 and “ESS_MBRINFO_T” on page 709.)
Syntax
ESS_FUNC_M EssOtlQueryMembersExArray (hOutline, pszFieldSelection, queryCount,
pszMemberSelectionArr, pMaxCountArr, pphMemberArr, ppqryErrorList)
hOutline ESS_HOUTLINE_T Outline handle returned from

pszFieldSelection ESS_STR_T Selects the member fields that the queries return. The
same selections are used for all queries in the array.
queryCount ESS_SHORT_T Count of members in the input array.
pszMemberSelectionArr ESS_STR_T Array of queryCount query strings for member

selection. The syntax of this query string is the syntax
for member selection; that is, the query string can be
anything that you can use in a FIX() statement.
pMaxCountArr ESS_PULONG_T Array of queryCount values for how many members

each query in the array at most should return. Each
value is replaced with the actual returned count.
pphMemberArr ESS_PPHMEMBER_T queryCount array of returned member handle arrays

(each with pMaxCountArr[i] values).
ppqryErrorList “ESS_OTLQUERYERRORLIST_T” List of members with errors.

on page 713
Notes
l In an outline that allows duplicate member names, this function returns the fully qualified
names of shared members. For example, in Sample Basic, any query that includes the shared
member 100-20 would return its fully qualified name, [Diet].[100-20].
l Use of UniqueName as part of the member fields selection automatically includes
ShareOption as part of the field selection.
904
l EssOtlQueryMemberExArray() takes an outline handle and returns an array of member
handles specified by pszMemberSelection.
l The caller should call EssOtlFreeMembers() when the returned pphMembers member array
l Each member handle element of the array can only be used in calls that are listed in
EssOtlOpenOutlineQuery(). For example, a returned member handle cannot be used to
call EssOtlGetSibling().
l The syntax of pszFieldSelection is the following:
QueryString ==: <SelectMbrInfo ( FieldName {, FieldName}, ... )
where FieldName is one of the following:
MemberName /* Member name */

MemberLevel /* Member level number */
MemberGeneration /* Member generation number */
Cosolidation /* Whether this member is consolidated */
TwoPass /* Whether this member undergoes a two pass operation
*/
Expense /* Whether this is an expense member */
CurrencyConvType /* Currency conversion type */
CurrencyMember /* Whether this is a currency member */
TimeBalance /* Time balance measure */
SkipOption /* Whether this member skips the time balance
operation */
ShareOption /* Whether this is a shared member*/
StorageType /* Dimension's storage type */
DimensionCategory /* Dimension category: accounts, time, currency, etc.
*/
DimensionStorageCategory /* Dimension storage category: time, units, scenario,
etc. */
Comment /* Member comment */
ChildrenCount /* Number of children */
MemberNumber /* Member number */
DimensionName /* Dimension name */
DimensionNumber /* Dimension number */
MemberAliasName /* Alias for this member */
ParentMemberName /* Parent's name */
ChildMemberName /* Child's name */
PreviousMemberName /* Left sibling's name */
NextMemberName /* Right sibling's name */
CurrencyConversionDatabase /* Whether this database has currency conversion */
MemberStatus /* Member status */
UDAList /* List of UDAs attached to this member */
MemberFormula /* Formula for this member */
MemberValidity /* Whether this member is valid */
Attributes /* All attribute fields. If the member is not
attributed, then attribute name is set to NULL */
UniqueName /* If the member is duplicate, its fully qualified,
unique name. */
Note: There is no leading '<' character for the individual fieldnames.
905
Return Value
Example
The following code snippet returns the name, consolidation and formula for each member that
is a child of Market and for each member that is a child of Product in two separate member
arrays. It combines what would have been two queries in EssOtlQueryMembersEx into just one
call to EssOtlQueryMembersExArray. Note that the member fields returned will be the same for
all queries in the array, and that the size of all arrays must match queryCount.
Upon return, MaxCountArray[i] contains the number of members returned in each query, and
phMemberArrayArray[i] contains the array of handles for the set of members returned for each
query. Further Outline API calls allow interrogation of the members using the returned array
of member handles in phMemberArrayArray[i].
member_fields = "<SelectMbrInfo ( MemberName, Consolidation, MemberFormula ) ";
queryCount = 2;
member_selectionArray[0] = "@ichild(Product)";
member_selectionArray[1] = "@ichild(Market)";
MaxCountArray[0] = -1;
MaxCountArray[1] = -1;
phMemberArrayArray[0] = ESS_NULL;
phMemberArrayArray[1] = ESS_NULL;
pqryErrorListArray[0] = ESS_NULL;
pqryErrorListArray[1] = ESS_NULL;
sts = EssOtlQueryMembersExArray(hOutline, member_fields, queryCount,

member_selectionArray, MaxCountArray, &phMemberArrayArray, pqryErrorListArray);
if (sts != 0) goto error_exit;
See Also
l EssOtlFreeMembers
l EssOtlGetMemberField
EssOtlQueryObjects
Returns an array of object handles of the specified type for the input object names, or if the
*pcount is zero, then it returns all the object handles.
Syntax
ESS_FUNC_M EssOtlQueryObjects(hOutline, objType, objNames, pcount, ppObjHandles)
906
hOutline ESS_HOUTLINE_T Outline handle (Query mode only)
objType ESS_OBJECT_TYPES Object type:

objNames ESS_PSTR_T Array of object names to be queried
pcount ESS_PULONG_T Count of object names. If pcount is zero, this contains the number of Text List
(SmartList) handles on execution.
ppObjHandles ESS_PPHOBJECT_T Array of object handles

This must be de allocated using EssOtlFreeObjectArray
Return Value
Returns:
l 0—If successful
pcount contains a value.
pcount is NULL.
Example
void TestFreeObjectArray()
{
ESS_STR_T objNames[1];
ESS_ULONG_T count;
ESS_PHOBJECT_T hObjHandles = ESS_NULL;

Object.hCtx = hCtx;
/* Set up */
count = 2;
/* Query objects */
sts = EssOtlQueryObjects(hOutline, objType,
objNames, &Count, &hObjHandles);
/* Free object array */
907
if(hObjHandles)
{
sts = EssOtlFreeObjectArray(hOutline, count, hObjHandles);
}
/* Close outline */
}
See Also
l EssOtlFindObject
l EssOtlListObjects
EssOtlQueryVaryingAttributes
Queries member information for a given attribute member or function, enabling specification
of the perspective for varying attributes.
Syntax
ESS_FUNC_M EssOtlQueryVaryingAttributes (hOutline, pAttrQuery, pPerspective,
pCount, pphMembers);
pAttrQuery ESS_PATTRIBUTEQUERY_T Pointer to the structure that defines the query.

l If pAttrQuery.bInputMemberIsHandle =
ESS_TRUE, make sure
pAttrQuery.uInputMember.hMember is assigned a
handle to a member.
l If pAttrQuery.bInputMemberIsHandle =
ESS_FALSE, make sure
pAttrQuery.uInputMember.szMember is assigned a
member name.
908
pPerspective ESS_PPERSPECTIVE_T Pointer to a collection of independent members used when querying the
client or server for associations.
pCount ESS_PMBRCOUNTS_T Pointer to the number of base members returned.
pphMembers ESS_PPHMEMBER_T Pointer to the array of attribute member handles.
Notes
Similar to EssOtlQueryAttributesEx, this function performs an attribute query. When the
query involves an input base member and output attribute members, or an input attribute
member and output base members, the given perspective is used to restrict the results based on
the associations that are valid in the perspective.
The structure ESS_VARYING_ATTRIBUTEQUERY_T is identical to
ESS_ATTRIBUTEQUERY_T, except that the varying version contains a field for the attribute
dimension.
Note that the perspective must specify discrete independent members individually.
If no perspective is specified, or if the perspective specifies a NULL set of independent members,
the routine will consider all associations that exist for any combination of independent members.
In this case, the returned validity sets may contain ranges for discrete independent members,
and it is the responsibility of the client to split this accordingly.
Return Value
Example
void TestEssOtlQueryVaryingAttributes()
{
ESS_USHORT_T i = 0;
ESS_HMEMBER_T hBaseMbr = ESS_NULL;
ESS_VARYING_ATTRIBUTEQUERY_T pAttrQuery;
ESS_HMEMBER_T hIndepMbrHandlesArray[4];
ESS_PERSPECTIVE_T Perspective;
ESS_PHMEMBER_T phMbrHandles;

Object.hCtx = hCtx;
909
printf("\n");
printf("EssOtlOpenOutlineQuery sts: %ld\n",sts);

Counts.ulStart = 0;
/* Get handles for independent members */

Predicate.ulQuery = ESS_SEARCH;
Predicate.ulOptions = ESS_MEMBERSONLY;
Predicate.pszDimension = "";
Predicate.pszString1 = "Jan";
Predicate.pszString2 = "";
&phMbrHandles);
&phMbrHandles);
&phMbrHandles);
/* Get handles for attribute member and dimension */

Predicate.pszString1 = "Type";
&phMbrHandles);
hAttrDim = phMbrHandles[0];
Predicate.pszString1 = "Contractor";
&phMbrHandles);
hAttrMbr = phMbrHandles[0];
memset(&Perspective, '\0', sizeof(ESS_PERSPECTIVE_T));

Perspective.usValiditySetType = ESS_VALIDITYSET_TYPE_MBRHDLS;
Perspective.countOfIndepDims = 2;
Perspective.countOfIndepRanges = 1;
Perspective.pIndepMbrs = hIndepMbrHandlesArray;
/* Query by handle with InputMemberType of ESS_ATTRIBUTE_MEMBER and OutputMemberType

of ESS_BASE_MEMBER*/
printf("\n*** Query by handle with InputMemberType of ESS_ATTRIBUTE_MEMBER and
OutputMemberType of ESS_BASE_MEMBER:\n");
memset(&pAttrQuery, '\0', sizeof(ESS_ATTRIBUTEQUERY_T));
pAttrQuery.bInputMemberIsHandle = ESS_TRUE;
pAttrQuery.uInputMember.hMember = hAttrMbr;
pAttrQuery.uAttributeDimension.hMember = hAttrDim;
pAttrQuery.usInputMemberType = ESS_ATTRIBUTE_MEMBER;
pAttrQuery.usOutputMemberType = ESS_BASE_MEMBER;
pAttrQuery.Attribute.usDataType = ESS_ATTRMBRDT_NONE;
910
pAttrQuery.usOperation = ESS_ALL;
sts = EssOtlQueryVaryingAttributes(hOutline, &pAttrQuery, &Perspective, &Counts,

&phMbrHandles);
printf("EssOtlQueryVaryingAttributes sts: %d\n", sts);
if (!sts)
{
if(phMbrHandles)
{
GetMemberInfo(hOutline, Counts, phMbrHandles);
if(Counts.ulReturnCount && phMbrHandles)
sts = EssOtlFreeMembers(hOutline, Counts.ulReturnCount, phMbrHandles);
}
else
printf("\tNo member returned.\n");
}

Object.FileName);
}
See Also
l EssOtlVaryingAssociateAttribute
l EssOtlVaryingAssociateAttributeDimension
l EssOtlVaryingDisassociateAttribute
l EssOtlVaryingGetAssociatedAttributes
l EssOtlVaryingGetAttributeIndepDims
EssOtlRenameAliasTable
Renames an existing alias table.
Syntax
ESS_FUNC_M EssOtlRenameAliasTable (hOutline, pszAliasTable, pszNewAliasTable);
pszAliasTable ESS_STR_T Name of alias table to rename.
pszNewAliasTable ESS_STR_T New name for alias table.
Notes
l The default alias table cannot be renamed from "Default".
l When renaming an alias table, language codes associated with the alias table are preserved
in the renamed alias table.
911
Return Value
l OTLAPI_ERR_RENAMEDEFALIAS
l OTLAPI_ERR_ALIASTABLENAME
l OTLAPI_ERR_ALIASTABLEEXISTS
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlRenameAliasTable(hOutline,
"Alias Table 2","2nd alias table");
}
See Also
EssOtlRenameMember
Renames a member.
Syntax
ESS_FUNC_M EssOtlRenameMember (hOutline, hMember, pszNewMember);
912
hMember ESS_HMEMBER_T Handle of member to rename
pszNewMember ESS_STR_T New member name
Notes
l All shared members are also renamed.
l This call fails if the hMember parameter points to a shared member.
l Renaming a zero-level (leaf node) attribute member that is not of type
ESS_ATTRMBRDT_STRING resets the following:
m the attribute value
m the member's long name, using the specifications for the outline in the
“ESS_ATTRSPECS_T” on page 113 structure
l Renaming an ancestor may affect the long name of a zero-level attribute member.
Return Value
l OTLAPI_BAD_RENAMESHARE
l OTLAPI_ERR_RENAMENAMEUSED
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

913
if (!sts)
{
&hMemberJan);
}

{
sts = EssOtlRenameMember(hOutline, hMemberJan,
"January prelim");
}
See Also
l EssOtlFindMember
l EssOtlMoveMember
l EssOtlAddMember
EssOtlRestructure
Restructures an outline on the server. This is an asynchronous call.
Syntax
ESS_FUNC_M EssOtlRestructure (hCtx, usRestructType);
hCtx ESS_HCTX_T Server login context handle. This must be the server on which the outline was saved
using EssOtlWriteOutline().
usRestructType ESS_USHORT_T Type of restructuring to do. This can be one of the following values:
l ESS_DOR_ALLDATA
l ESS_DOR_INDATA
l ESS_DOR_LOWDATA
l ESS_DOR_NODATA
l ESS_DOR_FORCE_ALLDATA
Notes
l You must save the outline using EssOtlWriteOutline() before calling this function.
l This call is valid only for outlines saved to the server.
l This call is asynchronous. You should call EssGetProcessState() after making this call until
EssGetProcessState() returns a status indicating the restructure operation is complete.
l In order for data to be properly restructured (saving data), the outline must have been
opened using EssOtlOpenOutline() with the fKeepTrans flag set to ESS_TRUE.
Return Value
Returns 0 if successful; otherwise returns OTLAPI_BAD_RESTRUCTTYPE structure.
914
Access
and/or database to contain the outline object. To restructure the outline object, you must have
Application Designer or Database Designer privilege (ESS_PRIV_APPDESIGN or
ESS_PRIV_DBDESIGN) for the specified application or database containing the outline.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HCTX_T hCtx;

Object.hCtx = hCtx;

/* body of code */
/* write outline to server using */
/* EssOtlWriteOutline() */
if (!sts)
{
}
/* need to call EssGetProcessState() */

/* to check for completion before proceeding */
See Also
l EssOtlOpenOutline
l EssOtlNewOutline
915
EssOtlSetAggLevelUsage
Applies view selection properties to stored hierarchies.
Syntax
ESS_FUNC_M EssOtlSetAggLevelUsage (hOutline, hMember, sAgglevelUsage);
hOutline ESS_HOUTLINE_T Outline context handle (input)

Value
hMember ESS_HMEMBER_T A hierarchy member (input).

0
sAgglevelUsage ESS_SHORT_T One of the Level Usage Constants (input).
Constant Value Description
ESS_AGGLEVELUSAGE_ 11 On primary hierarchies, consider all

DEFAULT levels. Do not aggregate secondary
hierarchies unless alternate rollups are
enabled.
ESS_AGGLEVELUSAGE_ALL 12 Consider all levels for aggregation. This is

same as default for primary hierarchies,
but not for secondary hierarchies.
ESS_AGGLEVELUSAGE_ 13 Do not aggregate along this hierarchy. All

NOAGGREGATION views selected are at the input level.
ESS_AGGLEVELUSAGE_ 14 Applies only to secondary hierarchies.

BOTTOMONLY Consider only lowest level of this hierarchy
for aggregation.
ESS_ AGGLEVELUSAGE_ 15 Applies only to primary hierarchies.

TOPONLY Consider only topmost level of this
hierarchy for aggregation.
ESS_ AGGLEVELUSAGE_ 16 Applies to primary hierarchies. Select top

BOTTOMTOP and bottom levels only.
Notes
l Use this function to apply view selection properties to stored hierarchies to restrict Essbase
from choosing certain levels for aggregation.
Return Value
916
Example
ESS_SHORT_T sAggLevelUsage = 0;

/* code to assign sAggLevelUsage variable omitted */

{
sts = EssOtlSetAggLevelUsage (hOutline, hMember, sAggLevelUsage);
if (sts)
printf("Error (%ld) setting AggLevelUsage\n", sts);
}
else
{
if (!hOutline)
if (!hMember)
printf("Member not provided\n");
}
See Also
l EssOtlGetAggLevelUsage
EssOtlSetAliasTableLanguage
Sets a language code for the specified alias table.
By setting alias table language codes, when an application running in an ApplCore session
accesses an Essbase database, the correct alias table is automatically selected on application
selection.
Syntax
ESS_FUNC_M EssOtlSetAliasTableLanguage (hOutline, pszAliasTable, pszLanguageCode);
pszAliasTable ESS_STR_T Name of the alias table for which to set a language code.
pszLanguageCode ESS_STR_T A language code to assign to the alias table specified in pszAliasTable.
The language code should be a middle-tier language tag from an ApplCore
session. Language codes are not case-sensitive.
Notes
l You cannot set a language code on the default alias table.
917
l Any number of language codes can be assigned to an alias table. To set multiple language
codes, call this function for each language code.
l Setting a new language code does not override language codes currently assigned to the alias
table.
l The same language code must not be assigned to another alias table within the same database.
Return Value
l If unsuccessful, returns one of the following errors:
m OTLAPI_BAD_ALIASTABLE (invalid alias table)
m OTLAPI_ERR_DUP_LANGCODE (the language code is assigned to another alias table
within the same database)
Access
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

if (!sts)
{
}
if (!sts)
{
}
if (!sts)
{
}
if (!sts)
{
&pLangs);
918
{
{
if (pLangs[i])
{
}
}
}
}
if (!sts)
{
}
See Also
l EssOtlGetAliasTableLanguages
l EssOtlClearAliasTableLanguages
EssOtlSetAltHierarchyEnabled
Sets a dimension to be multiple-hierarchy enabled.
Syntax
ESS_FUNC_M EssOtlSetAltHierarchyEnabled(hOutline, hDimMember, cEnabled);
hDimMember ESS_HMEMBER_T A dimension member (input).
cEnabled ESS_BOOL_T If TRUE, the dimension is set to enable multiple hierarchies. If FALSE, the
dimension is set to a single, stored hierarchy.
Return Value
l 0—If successful
l Returns error OTLAPI_ERR_BADDIM if hDimMember is not a dimension member.
See Also
919
EssOtlSetASOCompressionDimension
Tags an aggregate storage dimension as Compression.
Syntax
ESS_FUNC_M EssOtlSetASOCompressionDimension (hOutline, hDim);
hDim ESS_HMEMBER_T Dimension handle (input).
Notes
l By default, the compression dimension in aggregate storage databases is the Accounts
dimension.To get the current compression dimension, use
EssOtlGetASOCompressionDimension. Changing the compression dimension triggers a
full restructure of the database.
l Only one dimension can be the compressed dimension at any time. The API will
automatically unset any previous dimension when a new one is set. Attribute dimensions
cannot be compression dimensions.
l It is legal for an outline to not have any dimension selected as the compressed dimension.
Calling this function with hDim set to NULL will unset the current compression dimension.
l Essbase requires the compression dimension to be a single, dynamic hierarchy. If the
dimension has a different hierarchy setting, such as multiple hierarchies, it will be set to
single dynamic hierarchy automatically. The original hierarchy setting is lost (setting a
different dimension as compression does not return the original hierarchy setting).
l The choice of compression dimension can significantly affect performance. Large
dimensions are never good choices for compression dimensions.
Return Value
Example

if (hOutline)
{
sts = EssOtlSetASOCompressionDimension(hOutline, hMember);
if (sts)
printf("Error (%ld) setting compression dimension\n", sts);
else
if (hMember)
printf("Compression dimension set\n");
920
else
printf("Compression dimension cleared\n");
}
else
{
}
See Also
l EssOtlGetASOCompressionDimension
EssOtlSetAttributeSpecifications
Sets attribute specifications for the outline.
Syntax
pAttrSpecs; “ESS_ATTRSPECS_T” on page 113 Attribute specifications
Notes

used with it
l If you do not set attribute specifications, the outline uses the default attribute specifications.
l Changing attribute specifications may cause a restructure.
Return Value
If renaming attribute members fails, OTLAPI_ERR_ATTRRENAMENAMEUSED error is
returned.
Example
void ESS_OtlSetAttributeSpecifications()
{
ESS_ATTRSPECS_T AttrSpecs;
ESS_CHAR_T buffer[8][20];
921
int test;

Object.hCtx = hCtx;
printf("\n\nEnter the NUMBERS for the appropriate choices that follow.");

printf("\n\nEnter GenNameBy:\n\t\t0. ESS_GENNAMEBY_PREFIX\n\t\t1. ESS_GENNAMEBY_SUFFIX
\n\nChoice: ");
test = atoi(gets(buffer[0]));
switch (test)
{
case 0:
AttrSpecs.usGenNameBy=ESS_GENNAMEBY_PREFIX;
break;
case 1:
AttrSpecs.usGenNameBy=ESS_GENNAMEBY_SUFFIX;
break;
default:
printf("\n\nInvalid choice.\n\n");
}
printf("\n\nEnter UseNameOf:\n\t\t0. ESS_USENAMEOF_NONE\n\t\t1.

ESS_USENAMEOF_PARENT");
printf("\n\t\t2. ESS_USENAMEOF_GRANDPARENTANDPARENT\n\t\t3.
ESS_USENAMEOF_ALLANCESTORS");
printf("\n\t\t4. ESS_USENAMEOF_DIMENSION\n\nChoice: ");
switch (test)
{
case 0:
AttrSpecs.usUseNameOf=ESS_USENAMEOF_NONE;
break;
case 1:
AttrSpecs.usUseNameOf=ESS_USENAMEOF_PARENT;
break;
case 2:
AttrSpecs.usUseNameOf=ESS_USENAMEOF_GRANDPARENTANDPARENT;
break;
case 3:
AttrSpecs.usUseNameOf=ESS_USENAMEOF_ALLANCESTORS;
break;
case 4:
AttrSpecs.usUseNameOf=ESS_USENAMEOF_DIMENSION;
break;
default:
922
}
printf("Enter Delimiter:\n\t\t0. ESS_DELIMITER_UNDERSCORE\n\t\t1.

ESS_DELIMITER_PIPE");
printf("\n\t\t2. ESS_DELIMITER_CARET\n\nChoice: ");
switch (test)
{
case 0:
AttrSpecs.cDelimiter=ESS_DELIMITER_UNDERSCORE;
break;
case 1:
AttrSpecs.cDelimiter=ESS_DELIMITER_PIPE;
break;
case 2:
AttrSpecs.cDelimiter=ESS_DELIMITER_CARET;
break;
default:
}
printf("Enter DateFormat:\n\t\t0. ESS_DATEFORMAT_MMDDYYYY\n\t\t1.

ESS_DATEFORMAT_DDMMYYYY\n\nChoice: ");
switch (test)
{
case 0:
AttrSpecs.usDateFormat=ESS_DATEFORMAT_MMDDYYYY;
break;
case 1:
AttrSpecs.usDateFormat=ESS_DATEFORMAT_DDMMYYYY;
break;
default:
}
printf("Enter BucketingType:\n\t\t0. ESS_UPPERBOUNDINCLUSIVE\n\t\t1.

ESS_LOWERBOUNDINCLUSIVE");
printf("\n\t\t2. ESS_UPPERBOUNDNONINCLUSIVE\n\t\t3. ESS_LOWERBOUNDNONINCLUSIVE\n
\nChoice: ");
switch (test)
{
case 0:
AttrSpecs.usBucketingType=ESS_UPPERBOUNDINCLUSIVE;
break;
case 1:
AttrSpecs.usBucketingType=ESS_LOWERBOUNDINCLUSIVE;
break;
default:
}
printf("\nEnter a word for your default true string (or 'ESS_DEFAULT_TRUESTRING'):

\n");
923
gets(buffer[0]);
if (buffer[0] == "ESS_DEFAULT_TRUESTRING")
AttrSpecs.pszDefaultTrueString = "";
else
AttrSpecs.pszDefaultTrueString=buffer[0];
printf("\nEnter your default false string (or 'ESS_DEFAULT_FALSESTRING'):\n");

gets(buffer[1]);
if (buffer[1] == "ESS_DEFAULT_FALSESTRING")
AttrSpecs.pszDefaultFalseString = "";
else
AttrSpecs.pszDefaultFalseString=buffer[1];
printf("\nEnter your default attribute calculation dimension name (or

'ESS_DEFAULT_ATTRIBUTECALCULATIONS'):\n");
gets(buffer[2]);
if (buffer[2] == "ESS_DEFAULT_ATTRIBUTECALULATIONS")
AttrSpecs.pszDefaultAttrCalcDimName="";
else
AttrSpecs.pszDefaultAttrCalcDimName=buffer[2];
printf("\nEnter your default sum member name (or 'ESS_DEFAULT_SUM'):\n");

gets(buffer[3]);
if (buffer[3] == "ESS_DEFAULT_SUM")
AttrSpecs.pszDefaultSumMbrName = "";
else
AttrSpecs.pszDefaultSumMbrName=buffer[3];
printf("\nEnter your default count member name (or 'ESS_DEFAULT_COUNT'):\n");

gets(buffer[4]);
if (buffer[4] == "ESS_DEFAULT_COUNT")
AttrSpecs.pszDefaultCountMbrName = "";
else
AttrSpecs.pszDefaultCountMbrName=buffer[4];
printf("\nEnter your default average member name (or 'ESS_DEFAULT_AVERAGE'):\n");

gets(buffer[5]);
if (buffer[5] == "ESS_DEFAULT_AVERAGE")
AttrSpecs.pszDefaultAverageMbrName = "";
else
AttrSpecs.pszDefaultAverageMbrName=buffer[5];
printf("\nEnter your default minimum member name (or 'ESS_DEFAULT_MIN'):\n");

gets(buffer[6]);
if (buffer[6] == "ESS_DEFAULT_MIN")
AttrSpecs.pszDefaultMinMbrName = "";
else
AttrSpecs.pszDefaultMinMbrName=buffer[6];
printf("\nEnter your default maximum member name (or 'ESS_DEFAULT_MAX'):\n");

gets(buffer[7]);
if (buffer[7] == "ESS_DEFAULT_MAX")
AttrSpecs.pszDefaultMaxMbrName = "";
else
AttrSpecs.pszDefaultMaxMbrName=buffer[7];
sts = EssOtlSetAttributeSpecifications(hOutline, &AttrSpecs);
924
printf("EssOtlSetAttributeSpecifications() sts: %ld\n",sts);


if (!sts)
{
}
}
See Also
l EssFreeStructure
EssOtlSetDateFormatString
This function sets the outline property date format String.
Syntax
ESS_FUNC_M EssOtlSetDateFormatString(
ESS_STR_T formatString)
hOutline ESS_HOUTLINE_T Outline for the Smartlist.
formatString ESS_STR_T Returns the outline date format string to this argument.
925
Return Value
Returns:
l 0—If successful
formatString constains a date format string.
Example
{

Object.hCtx = hCtx;


printf("\n");

{
pformatStrings[i]);
&dateFormatString);
926
}
See Also
l EssOtlGetServerDateFormats
l EssOtlGetDateFormatString
EssOtlSetDimensionNameUniqueness
Sets the dimension to prohibit duplicate (non-unique) member names.
Syntax
ESS_FUNC_M EssOtlSetDimensionNameUniqueness (hOutline, hMember, bNameUnique);
hMember ESS_HMEMBER_T Member handle of the dimension root member (input).
bNameUnique ESS_BOOL_T The dimension member-name uniqueness setting (input). If set to TRUE, then
the dimension cannot have duplicate member names.
Notes
Call EssOtlFindMember to set up the ESS_HMEMBER_T (hDim) variable.
Return Value
Example
ESS_FUNC_M ESS_GetSetDimNameUniq()
{
ESS_STS_T sts = 0;

Object.hCtx = hCtx;
927

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Year",&hDim);
if (sts)
}
/*Get the dimension's, Year, member-name uniqueness setting */

if (!sts)
{
sts = EssOtlGetDimensionNameUniqueness (hOutline, hDim, &pbNameUnique);
if (sts)
printf("EssOtlGetDimensionNameUniqueness failed sts %ld\n",sts);
else
printf("Dimension Year has Member Name Uniqueness value: %ld\n", pbNameUnique);
}
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Product",&hDim);
if (sts)
}
if (!sts)
{
/*set Product to prohibit duplicate (non-unique) member names*/
pbNameUnique = ESS_TRUE;
sts = EssOtlSetDimensionNameUniqueness (hOutline, hDim, pbNameUnique);
if (sts)
printf("EssOtlSetDimensionNameUniqueness failed sts %ld\n",sts);
else
printf("Dimension Product has Member Name Uniqueness value: %ld\n", pbNameUnique);
}
return sts;
See Also
l EssOtlGetDimensionNameUniqueness
928
EssOtlSetDimensionSolveOrder
Sets the solve order of a dimension.
Syntax
ESS_FUNC_M EssOtlSetDimensionSolveOrder (hOutline, hMember, cOrder);
hMember ESS_HMEMBER_T Dimension handle (input).
cOrder ESS_UCHAR_T Solve order (input). 0 - 127
Notes
Return Value
Example

/* code to assign ucOrder variable omitted */

{
if (ucOrder > 127)
{
printf("Solveorder must be less than 128\n");
{
else
{
sts = EssOtlSetDimensionSolveOrder(hOutline, hMember, ucOrder);
if (sts)
else
}
929
}
else
See Also
l EssOtlGetDimensionSolveOrder
l EssOtlSetMemberSolveOrder
EssOtlSetDTSMemberAlias
Sets an alias name for a Dynamic Time Series (DTS) member.
Syntax
ESS_STS_T EssOtlSetDTSMemberAlias (hOutline, pszDTSMember, pszAlias, pszAliasTable);
pszAlias ESS_STR_T Pointer to a C string containing the alias name for the DTS member.
pzsAliasTable ESS_STR_T Name of the alias table which provides the alias. If NULL, the default alias table
is used.
Return Value
l OTLAPI_ERR_ILLEGALALIASSTRING
l OTLAPI_ERR_DUPLICATEALIAS
Example
#include "essapi.h"
#include "essotl.h"
ESS_STS_T ESS_OtlSetDTSMemberAlias(ESS_HCTX_T hCtx, ESS_HINST_T hInst)

{
ESS_CHAR_T pszAlias[ESS_ALIASNAMELEN];
930
strcpy(pszAlias, "QuarterToDate");

Object.hCtx = hCtx;
if(sts)
{
return sts;
}
sts = EssOtlSetDTSMemberAlias(hOutline, pszDTSMember, pszAlias , pszAliasTable);
if(sts)
{
printf("Could not set DTS member alias. Error is %d\n", sts);
}

if(sts)
{
return sts;
}

if(sts)
{
return sts;
}

{
while ((sts == ESS_STS_NOERR ) && (pState.State != ESS_STATE_DONE))
{
}
}
sts = EssUnlockObject(hCtx, ESS_OBJTYPE_OUTLINE, szAppName, szDbName,
931
szFileName);
if (sts)
{
printf("Could not unlock outline\n");
return sts;
}
return sts;
}
See Also
EssOtlSetGenName
Sets the name for a specific generation within a dimension.
Syntax
ESS_FUNC_M EssOtlSetGenName (hOutline, pszDimension, usGen, pszName);
usGen ESS_USHORT_T Number of generation for which to set a name. The dimension itself is generation
1.
pszName ESS_STR_T Name to give the generation.
Notes
l The generation name must be unique across the entire member name space. It cannot
duplicate any other generation, level, member name, or alias. Attempting to add a duplicate
generation name generates an error.
l Each specific dimension and generation must have only one name.
Return Value
l OTLAPI_BAD_GENLEVELNAME
l OTLAPI_ERR_GENLEVELNAMEEXISTS
l OTLAPI_ERR_GENLEVELEXISTS
l OTLAPI_ERR_GENLEVELVALUE
932
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T GenName;

Object.hCtx = hCtx;

/************ Set Generation Name ************/

Dimension = "Year";
GenNum = 2;
GenName = "Qtr123";
if (!sts)
{
sts = EssOtlSetGenName(hOutline, Dimension,
GenNum, GenName);
}
See Also
EssOtlSetGenNameEx
Sets the generation name and member uniqueness setting for the specified generation number.
Syntax
ESS_FUNC_M EssOtlSetGenNameEx (hOutline, pszDimension, usGen, pszName, bUniqueName);
933
pszDimension ESS_STR_T Dimension name.
usGen ESS_USHORT_T The number of the generation for which to set a name.
pszName ESS_STR_T The name to give the generation.
bUniqueName ESS_BOOL_T If TRUE, members at generation usGen in dimension pszDimension cannot have
duplicate names.
Notes
l This function sets the name of a generation as well as the uniqueness property of a generation.
If you only want to set the name, use EssOtlSetGenName.
l If you only want to set the uniqueness property, but not change the name, you must still
pass in the name. To do so, call EssOtlGetGenName and pass its value to this function as
usGen.
l Do not pass null for the usGen parameter.
Return Value
Example
void ESS_GetGenNameEx()
ESS_STS_T sts = 0;
ESS_STR_T GenName;

Object.hCtx = hCtx;

934
/*************** Set and Get GenName **************/
Dimension = "Year";
GenNum = 1;
GenName = "Gen 1 Year";
//SetGenNameEx() so that Gen 1 members of Year cannot be non-unique

if (!sts)
{
sts = EssOtlSetGenNameEx(hOutline, Dimension,
GenNum, GenName, ESS_TRUE);
}
// GetGenNameEx() to see if the gen is able to be non-unique

if (!sts)
{
sts = EssOtlGetGenNameEx(hOutline, Dimension,
GenNum, &GenName, &bUnique);
printf("Generation 1 members of Year have bUnique value of %ld\n", bUnique);
printf("EssOtlGetGenNameEx sts: %ld\n",sts);
}

{
}
See Also
l EssOtlSetGenName
l EssFree
l EssOtlGetGenNameEx
EssOtlSetHierarchyType
Sets the dimension's hierarchy type designation: Multiple hierarchies enabled, dynamic
hierarchy, or stored hierarchy.
Syntax
ESS_FUNC_M EssOtlSetHierarchyType(hOutline, hMember, cType);
hMember ESS_HMEMBER_T A dimension member (input).
935
cType ESS_UCHAR_T If hMember is a dimension member, one of the following values (input):
l ESS_STORED_HIERARCHY—The dimension is a single, stored hierarchy.
l ESS_DYNAMIC_HIERARCHY—The dimension is a single, dynamic hierarchy.
l ESS_MULTIPLE_HIERARCHY_IS_ENABLED—The dimension is multiple-
hierarchy enabled (same as using EssOtlSetAltHierarchyEnabled).
See Notes.
Notes
Once the dimension is multiple-hierarchy enabled, the hierarchy types are determined by the
generation 2 members. If hMember is a generation 2 member, cType can have the following
values:
l ESS_STORED_HIERARCHY—The hierarchy with hMember as top is a single, stored
hierarchy.
l ESS_DYNAMIC_HIERARCHY—The hierarchy with hMember as top is a single, dynamic
hierarchy.
Return Value
See Also
EssOtlSetImpliedShare
Changes the Implied Share setting of an outline.
Syntax
ESS_FUNC_M EssOtlSetImpliedShare(hOutline, impliedShareSetting);
impliedShareSetting ESS_USHORT The implied share setting value. See “Implied Share Setting (C)” on page
97.
Return Value
l 0—If successful
936
See Also
l EssOtlGetImpliedShare
EssOtlSetLevelName
Sets the name for a specific level within a dimension.
Syntax
ESS_FUNC_M EssOtlSetLevelName (hOutline, pszDimension, usLevel, pszName);
pszDimension ESS_STR_T Name of dimension that contains the level.
usLevel ESS_USHORT_T Number of level for which to set a name. Leaf members are level 0.
pszName ESS_STR_T Name to give the level.
Notes
l The level name follows the same rules as a member name and must be unique across the
entire member name space. It cannot duplicate any other generation, level, member name,
or alias. Attempting to add a duplicate name generates an error.
l Each specific dimension and level must have only one name.
Return Value
l OTLAPI_BAD_GENLEVELNAME
l OTLAPI_ERR_GENLEVELNAMEEXISTS
l OTLAPI_ERR_GENLEVELEXISTS
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0 ;
937
Object.hCtx = hCtx;

/************* Set Level Name **************/

Dimension = "Year";
LevelNum = 1;
LevelName = "Qtr 1 2 3";
if (!sts)
{
sts = EssOtlSetLevelName(hOutline, Dimension,
LevelNum, LevelName);
}
See Also
l EssOtlDeleteLevelName
EssOtlSetLevelNameEx
Sets whether members in a certain dimension at a certain level are prohibited from having
duplicate names.
Syntax
ESS_FUNC_M EssOtlSetLevelNameEx (hOutline, pszDimension, usLevel, pszName, bUniqueName);
pszDimension ESS_STR_T Name of dimension that contains the level.
usLevel ESS_USHORT_T Number of level for which to set a name. Leaf members are level 0.
pszName ESS_STR_T Name to give the level.
bUniqueName ESS_BOOL_T If TRUE, members at level uslevel in dimension pszDimension cannot have
duplicate names. If FALSE, duplicate names are allowed.
938
Notes
l The level name must be unique across the entire member name space. It cannot duplicate
any other generation, level, member name, or alias. Attempting to add a duplicate level name
generates an error.
l This function sets the name of a level as well as the uniqueness property of a level. If you
only want to set the name, use EssOtlSetLevelName.
l If you only want to set the uniqueness property, but not change the name, you must still
pass in the name. To do so, call EssOtlGetLevelName and pass its value to this function
as usLevel.
l Do not pass null for the usLevel parameter.
Return Value
Example
ESS_FUNC_M
ESS_GetLevelNameEx()
{
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

/*************** Set and Get Level Name **************/

Dimension = "Year";
LevelNum = 0;
LevelName = "Level 0 Year";
//SetLevelNameEx() so that level 0 member of Year cannot be non-unique

if (!sts)
{
sts = EssOtlSetLevelNameEx(hOutline, Dimension,
LevelNum, LevelName, ESS_TRUE);
939
}
// GetLevelNameEx() to see if the level is able to be non-unique

if (!sts)
{
sts = EssOtlGetLevelNameEx(hOutline, Dimension,
LevelNum, &LevelName, &bUnique);
printf("Level 0 members of Year have bUnique value of %ld\n", bUnique);

{
}
return (sts);
}
See Also
l EssOtlGetLevelNameEx
EssOtlSetMemberAlias
Sets the default member alias for the specified member in the specified alias table.
Syntax
ESS_FUNC_M EssOtlSetMemberAlias (hOutline, hMember, pszAliasTable, pszAlias);
hMember ESS_HMEMBER_T Handle of member to set the alias for.
pszAliasTable ESS_STR_T Alias table to set the alias for. If this parameter is ESS_NULL, the default alias table
is used.
pszAlias ESS_STR_T Alias.
Notes
Use EssOtlDeleteMemberAlias() to remove an alias.
Return Value
Returns 0 if successful; otherwise one of the following::
l OTLAPI_ERR_ILLEGALDEFALIAS
l OTLAPI_ERR_ILLEGALCOMBOALIAS
l OTLAPI_ERR_ILLEGALALIASSTRING
940
l OTLAPI_ERR_DUPLICATEALIAS
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Year",
&hMember);
}

{
sts = EssOtlSetMemberAlias(hOutline,
hMember, ESS_NULL, "Time Dimension");
}
See Also
l EssOtlDeleteMemberAlias
EssOtlSetMemberCommentEx
Sets the extended comment for the specified member.
Syntax
ESS_FUNC_M EssOtlSetMemberCommentEx (hOutline, hMember, pszCommentEx);
941
pszCommentEx ESS_STR_T Buffer containing the extended comment.
Notes
To delete an extended comment, call this function with an empty string or a null pointer.
Return Value
Returns 0 if successful; OTLAPI_ERR_MBRCOMMENTEXLEN if the comment is too long.
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T pszCommentEx;

Object.hCtx = hCtx;
/************ Set Extended Member Comment *************/

pszCommentEx = "EXTENDED MEMBER COMMENT";
if (!sts)
{
sts = EssOtlFindMember(hOutline, "Variance",&hMember);
}

{
sts = EssOtlSetMemberCommentEx(hOutline, hMember, pszCommentEx);
}
See Also
l EssFree
l EssOtlOpenOutline
942
EssOtlSetMemberFormula
Sets the formula for the specified member.
Syntax
ESS_FUNC_M EssOtlSetMemberFormula (hOutline, hMember, pszFormula);
pszFormula ESS_STR_T Buffer containing the member formula.
Notes
Use EssOtlDeleteMemberFormula() to remove a member formula.
Return Value
l OTLAPI_ERR_SHAREDMEMBERFORMULA
l OTLAPI_ERR_MEMBERCALC
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T pszFormula;

Object.hCtx = hCtx;

/************ Set Member Formula *************/

pszFormula = "@VAR(Budget, Actual);";
if (!sts)
{
943
sts = EssOtlFindMember(hOutline,
"Variance",&hMember);
}

{
sts = EssOtlSetMemberFormula(hOutline, hMember,
pszFormula);
}
See Also
EssOtlSetMemberInfo
Sets member attribute information.
Syntax
ESS_FUNC_M EssOtlSetMemberInfo (hOutline, hMember, pInfo);
hMember ESS_HMEMBER_T Handle to member to set attributes for
pInfo “ESS_MBRINFO_T” on page 709 Member information structure
Notes
Attributes
l Three fields of the ESS_MBRINFO_T structure are for attributes only:
ESS_BOOL_T fAttributed Indicates whether a base member has attributes associated with it: either ESS_TRUE or
ESS_FALSE.
944
ESS_USHORT_T Attribute.usDataType For an attribute dimension or zero-level (leaf node) attribute member, one of the following
data types:
For any attribute member, but not an attribute dimension:

m ESS_ATTRMBRDT_NONE
m ESS_ATTRMBRDT_AUTO
Note: Use ESS_ATTRMBRDT_AUTO only when adding a member. See Notes on
Adding an Attribute Member.
union Attribute.value One of the following attribute member values:

ESS_BOOL_T bData m Boolean value
ESS_STR_T strData m String value
ESS_DATETIME_T dtData m Date and time value

Double value
ESS_DOUBLE_T dblData
m
l Values for two fields of the ESS_MBRINFO_T structure are for attributes only:
ESS_USHORT_T usCategory One of the following dimension categories:

m ESS_CAT_ATTRIBUTE
m ESS_CAT_ATTRCALC (for internal use only)
ESS_USHORT_T usStorageCategory One of the following dimension storage categories:

m ESS_STORECAT_ATTRIBUTE
m ESS_STORECAT_ATTRCALC (for internal use only)
Return Value
l OTLAPI_BAD_CONSOL
l OTLAPI_BAD_MEMBER
l OTLAPI_ERR_ADDNAMEUSED
945
l OTLAPI_ERR_ILLEGALNAME
l OTLAPI_ERR_SHARENOTLEVEL0
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
&hMemberJan);
}

{
hMemberJan, &pMbrInfo);
946
}
if (!sts && pMbrInfo)

{
pMbrInfo->usConsolidation = ESS_UCALC_SUB;
pMbrInfo->fTwoPass = ESS_TRUE;
pMbrInfo->fExpense = ESS_TRUE;
sts = EssOtlSetMemberInfo(hOutline,
hMemberJan, pMbrInfo);
}
if (pMbrInfo)
{
EssOtlFreeStructure(hOutline, count, structId, structPtr);
}
See Also
l EssOtlFindMember
EssOtlSetMemberSolveOrder
Sets the solve order of a member.
Syntax
ESS_FUNC_M EssOtlSetMemberSolveOrder (hOutline, hMember, cOrder);
hMember ESS_HMEMBER_T Dimension handle (input).
cOrder ESS_UCHAR_T Solve order (input). 0 - 127
Notes
l Solve order is applicable only to aggregate storage databases.
Return Value
Example
947

/* code to assign ucOrder variable omitted */

{
if (ucOrder > 127)
{
printf("Solveorder must be less than 128\n");
{
else
{
sts = EssOtlSetMemberSolveOrder(hOutline, hMember, ucOrder);
if (sts)
else
}
}
else
See Also
l EssOtlSetDimensionSolveOrder
l EssOtlGetDimensionSolveOrder
EssOtlSetMemberType
Sets the member type of the input outline member.
Syntax
ESS_FUNC_M EssOtlSetMemberType(hOutline, hMember, usType)
usType ESS_USHORT_T Type of the outline member:

l ESS_MEMBERTYPE_NUMERIC
Member type is a numeric.
l ESS_MEMBERTYPE_DATE
Member type is date typed.
948
Notes
Does not allow setting the type to ESS_MEMBERTYPE_SMARTLIST. Instead, use
EssOtlSetMemberTypeToSmartList.
Return Value
Returns:
l 0—If successful
Example
void TestGetSetMemberType()
{
ESS_USHORT_T usMemberType;

Object.hCtx = hCtx;
/* Open outline */
/* Find a member */
sts = EssOtlFindMember(hOutline, "Original Price", &hMember);
/* Get Member Type of an outline that is not member

type enabled */
DisplayMemberType(usMemberType); /* a display function */

/* Set type to SmartList */

usMemberType = ESS_MEMBERTYPE_SMARTLIST;
/* Set type to DATE */

usMemberType = ESS_MEMBERTYPE_DATE;
/* Get Member Type of an outline that is member
949
type enabled */
EnableSmartList(hOutline);

/* Set type to DATE */

usMemberType = ESS_MEMBERTYPE_DATE;



/* Clean up */
/* Close outline */
}
See Also
l EssOtlFindObject
l EssOtlListObjects
950
EssOtlSetMemberTypeToSmartList
Sets the input outline member as ESS_MEMBERTYPE_SMARTLIST and associates the input
Text List (SmartList object with it.
Syntax
ESS_FUNC_M EssOtlSetMemberTypeToSmartList(hOutline, hMember, hSmartList)
hSmartList ESS_HSMARTLIST_T SmarList handle to be associated with.
Return Value
Returns:
l 0—If successful
Example
void TestSetMemberTypeToSmartList()
{
ESS_STR_T objName;
ESS_HOBJECT_T hObjHandle1, hObjHandle2;
//ESS_USHORT_T usVerifyType;

Object.hCtx = hCtx;
/* Open outline */
/* Find a member */
sts = EssOtlFindMember(hOutline, "Original Price",
&hMember);
/* Get original SmartList association */

sts = EssOtlGetMemberSmartList(hOutline, hMember,
&hSmartList);
951
/* Set member type to SmartList */
hSmartList = (ESS_HSMARTLIST_T)hObjHandle1;
sts = EssOtlSetMemberTypeToSmartList(hOutline,
hMember, hSmartList);
/* Unlock */
/* Close outline */
}
See Also
l EssOtlFindObject
l EssOtlListObjects
EssOtlSetOriginalMember
Sets a member as an extended shared member.
Syntax
ESS_FUNC_M EssOtlSetOriginalMember (hOutline, hMember, pszOriginalMbr);
hMember ESS_HMEMBER_T Member name (input). This member will be set as extended shared.
pszOriginalMbr ESS_STR_T The original member name intended to share with (input).
Notes
l If hMember is not shared already, it will be marked as extended shared.
952
l If you use this function on an outline in which all member names are unique, it will have
no effect.
l Before you call this function, call EssOtlOpenOutline to open the outline in editing mode.
l Given the following hierarchy, if you pass to this function the member handle (hMember)
corresponding to [Diet].[100-10], and the original member (pszOriginalMbr) as
[200].[100-10], then [Diet].[100-10] becomes an extended shared member of
[200].[100-10].
100
100-10
200
100-10 (duplicate)
Diet
100-10 (shared with [200.100-10])
Return Value
Example
ESS_FUNC_M ESS_SetOrigMember()
{
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "[Diet].[100-10]", &hMember);
}

{
953
sts = EssOtlSetOriginalMember (hOutline, hMember, "[100].[100-10]");
}
return sts;
}
See Also
l EssOtlGetOriginalMember
EssOtlSetOutlineInfo
Sets outline information.
Syntax
ESS_FUNC_M EssOtlSetOutlineInfo (hOutline, pInfo);
pInfo “ESS_OUTLINEINFO_T” on page 716 Pointer to a structure allocated by the caller to store outline
information.
Notes
l Only some of the fields of the “ESS_OUTLINEINFO_T” on page 716 structure are used to
set information. See the structure description for more information.
l If the fCaseSensitive flag in the ESS_OUTLINEINFO_T structure is being changed from
ESS_TRUE to ESS_FALSE, and this causes duplicate member names, the call will fail. If your
outline is a duplicate member name outline, use EssOtlSetOutlineInfoEx instead of
this function.
Return Value
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_FALSE = 0;
ESS_TRUE = 1;

Object.hCtx = hCtx;
954

&hOutline);
if (!sts)
{
}
if (!sts && Info)

{
pInfo->fCaseSensitive = ESS_FALSE;
sts = EssOtlSetOutlineInfo(hOutline, pInfo);
}
if (pInfo)
{
}
See Also
l EssOtlSetOutlineInfoEx
EssOtlSetOutlineInfoEx
Converts a unique-member-name outline to an outline that allows duplicate names.
When pInfo ->fNonUniqueName is set to TRUE, this function converts a unique member name
outline to an outline allowing duplicate member names. You cannot convert an outline allowing
duplicate member names back to a unique member name outline.
Syntax
ESS_FUNC_M EssOtlSetOutlineInfoEx (hOutline, pInfo);
pInfo “ESS_OUTLINEINFO_T” on page 716 Pointer to a structure allocated by the caller to store outline
information (input).
Notes
Only some of the fields of the “ESS_OUTLINEINFO_T” on page 716 structure are used to set
information. See the structure description for more information.
955
Return Value
Returns 0 if successful; otherwise, see the Outline API “C Outline API Error Return Values” on
page 695.
Example
void SetOutlineInfoEx()
{
ESS_STS_T sts = 0;

Object.hCtx = hCtx;

if (!sts)
{
}
if (!sts && pInfo)

{
pInfo->fNonUniqueName = ESS_TRUE;
sts = EssOtlSetOutlineInfoEx(hOutline, pInfo);
}
if (!sts)
{
}
if (!sts)
{
}
if (pInfo)
{
956
}
See Also
EssOtlSetQueryHint
Changes the contents (pMemberArray) of an existing query hint; applies only to Release 9.3 or
higher aggregate storage databases.
Syntax
ESS_FUNC_M EssOtlSetQueryHint (hOutline, hintNum, numMembers, pMemberArray);
numMembers ESS_SHORT_T Number of members in the array provided - usually the number of real
dimensions in the outline (input).
array needs to be allocated. (Input)
Notes
l Level usage constraints override query hints whenever a conflict occurs (see
SetAggLevelUsage).
l Hints may not contain dynamic, label-only, or shared members.
l Hints may become invalid when the outline changes. Invalid hints result in a warning
message.
l Hints enable you to influence normal view selection by informing Essbase about the profile
of common queries.
l Hints are written as MDX tuples, with no more than one member from each dimension
specified.
l Each member used in the query hint is considered a representative member. Essbase Server
interprets representative members as "this member or any member at the similar level of
aggregation." For example, using a query hint of (Qtr1, Sales, 100, East,
Actual) on Sample Basic means that quarterly, actual profit margin measures for level 1
products at level 1 markets is a common type of query.
l For any given dimension, Essbase interprets the omission of representative members to
mean that any member from the dimension may be used in a query. For example, using a
query hint of (Sales, 100, East) on Sample Basic means that profit margin measures
for level 1 products at level 1 markets is a common type of query, regardless of Year and
957
Scenario dimensions, which were omitted. The hint (Sales, 100, East) is treated as
identical to (NULL, Sales, 100, East, NULL).
Return Value
Example
/* clear array just to be safe */

memset(hMember, 0x00, 10*sizeof(ESS_HMEMBER_T));

/* Code to assign hintNum variable omitted */

if (hintNum <= nmHints)

{
sts = EssOtlGetQueryHint(hOutline, hintNum, 10, hMember);
for (j = 0; j < 10; j++)

{
/* Code to inspect and change hMember[j] omitted */
}
sts = EssOtlSetQueryHint(hOutline, hintNum, 10, hMember);

printf("Query-Hint number: (%d) updated\n", hintNum);
}
else
{
printf("Query-Hint number: (%d) does not exist\n", hintNum);
}
See Also
EssOtlSetUserAttribute
Sets a user-defined attribute for a member.
958
Syntax
ESS_FUNC_M EssOtlSetUserAttribute (hOutline, hMember, pszString);
hMember ESS_HMEMBER_T Handle of member for which to set the user-defined attribute.
pszString ESS_STR_T User-defined attribute to set.
Notes
l A caller can set any number of user-defined attributes for a member. The string passed in
uniquely defines each attribute and follows the same conventions as user names. See
EssOtlGetUserAttributes.
l Attempting to set a user attribute for a shared member generates an error.
Return Value
l OTLAPI_BAD_USERATTR
l OTLAPI_ERR_SHAREUDA
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_STR_T AttributeList;

Object.hCtx = hCtx;

/*********** Set User Attributes ************/

AttributeList = "Read Write";
if (!sts)
959
{
&hMember);
}

{
sts = EssOtlSetUserAttribute(hOutline, hMember,
AttributeList);
}
See Also
l EssOtlDeleteUserAttribute
l EssOtlGetUserAttributes
EssOtlSortChildren
Sorts the children of an outline member.
Syntax
ESS_FUNC_M EssOtlSortChildren (hOutline, hParent, usType, fpCompare, pUserData);
hParent ESS_HMEMBER_T Handle of parent of the children to sort. If this is ESS_NULL, the dimensions
are sorted.
usType ESS_USHORT_T Sort type. This can be one of the following:

l ESS_SORT_ASCENDING
l ESS_SORT_DESCENDING
l ESS_SORT_USERDEFINED
fpCompare ESS_POTLSORTFUNC_T Pointer to user-defined comparison function. This is only used if the usType
parameter is ESS_SORT_USERDEFINED. It points to a function defined as
follows:
(ESS_INTFUNC_M Compare
ESS_HMEMBER_T mbr1,
ESS_HMEMBER_T mbr2,
ESS_PVOID_T pUserData);
The function accepts handles for two members and should return the
following:
l < 0 if mbr1 goes before mbr2.
l = 0 if mbr1 is equivalent to mbr2.
l > 0 if mbr1 goes after mbr2.
pUserData ESS_PVOID_T Pointer to any user-specified data. This is only used if the usType parameter
is ESS_SORT_USERDEFINED. Each time the comparison function is called,
the value of this parameter is passed into the comparison function.
960
Notes
During the callback function, you should not call any outline functions that might change the
outline. Only EssOtlGetMemberInfo(), EssOtlGetMemberFormula(), and
EssOtlGetMemberAlias() can be called.
Return Value
l OTLAPI_BAD_SORTTYPE
l OTLAPI_BAD_SORTCOMPAREFUNC
l OTLAPI_SORT_TOOMANY
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_HMEMBER_T hMeasures;
FARPROC pfnSort;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlFindMember(hOutline, "Measures",
&hMeasures);
}
if (!sts)
{
sts = EssOtlSortChildren(hOutline, hMeasures,
ESS_SORT_USERDEFINED,
(ESS_POTLSORTFUNC_T)pfnSort,
(ESS_PVOID_T)hOutline);
}
/***********************************************/
int ESS_INTFUNCT_M SortCompare (
961
ESS_HMEMBER_T hMember1,
ESS_HMEMBER_T hMember2,
ESS_PVOID_T pData)
{
int nRet = 0;
int nLen1;
int nLen2;
ESS_STS_T sts = 0;
ESS_PMBRINFO_T pMbrInfo1 = ESS_NULL;
ESS_PMBRINFO_T pMbrInfo2 = ESS_NULL;
ESS_HOUTLINE_T hOutline =
(ESS_HOUTLINE_T)pData;
sts = EssOtlGetMemberInfo(hOutline, hMember1,

&pMbrInfo1);
if (!sts && pMbrInfo1)

hMember2, &pMbrInfo2);
if (!sts && pMbrInfo2)

{
nLen1 = strlen(pMbrInfo1->szMember);
nLen2 = strlen(pMbrInfo2->szMember);
if (nLen1 < nLen2)
nRet = -1;
else if (nLen1 > nLen2)
nRet = 1;
}
if (pMbrInfo1)
{
EssFree(hInst, pMbrInfo1);
}
if (pMbrInfo2)
{
EssFree(hInst, pMbrInfo2);
}
return (nRet);
}
See Also
l EssOtlFindMember
EssOtlVaryingAssociateAttribute
Associates an attribute member to a base member, with the validity of the associations specified
by the given validity set.
Syntax
ESS_FUNC_M EssOtlVaryingAssociateAttribute (hOutline, hBaseMember, hAttrMember, mode,
pValiditySet);
962
hBaseMember ESS_HMEMBER_T Handle to the base member
hAttrMember ESS_HMEMBER_T Handle to the attribute member
mode ESS_INT_T Association mode. Possible values:

l MODE_OVERWRITE
l MODE_NOOVERWRITE
pValiditySet “ESS_VALIDITYSET_T” on page Pointer to the validity set that defines the independent dimension
720 for which the association is valid
Notes
l When a full range is specified, the association is made as specified.
l Association mode determines how to handle open-ended situations when only the starting
tuple is specified instead of a full range. (For these description examples, assume the
following associations of the Ounces attribute members associated with product 100-10
prior to association):
Jan Feb Mar Apr May
12 12 16 16 20
m MODE_OVERWRITE—Association starts from the specified member through all

members that follow it. Example: Associating 12 starting with Mar.
Result: Mar and all members after it are associated with 12. Conflicting associations are
overwritten:
Jan Feb Mar Apr May
12 12 12 12 12
m MODE_NOOVERWRITE—Association starts at the specified tuple and continues until
the existing associated attribute member is different. Example: Associating 12 starting
with Mar.
Result: Both Mar and Apr had the same attribute so association continues until May
where it was different:
Jan Feb Mar Apr May
12 12 12 12 20
Return Value
Example
void TestEssOtlVaryingAssociateAttribute()
{
ESS_HMEMBER_T hBaseMbr, hAttrMbr, hBaseDim, hAttrDim, hIndDim = ESS_NULL;
963
ESS_INT_T mode;
ESS_VALIDITYSET_T ValiditySet;
ESS_HMEMBER_T IndDimsArray[2];
ESS_STR_T IndepMbrsArray[4];
ESS_INT32_T countOfIndDims;
ESS_UCHAR_T pucIndependentTypes[2];

Object.hCtx = hCtx;
printf("\n");
/* Disassociate base dimension from attribute dimension before test.*/

printf("\nDisassociate base dimension from attribute dimension before test:");
sts = EssOtlFindMember(hOutline, "Entities", &hBaseDim);
printf("\nEssOtlFindMember sts: %d\n", sts);
sts = EssOtlFindMember(hOutline, "Type", &hAttrDim);
printf("EssOtlFindMember sts: %d\n", sts);
sts = EssOtlDisassociateAttributeDimension(hOutline, hBaseDim, hAttrDim);
printf("EssOtlDisassociateAttributeDimension sts: %d\n", sts);
/* Get handle for base member*/

printf("\nGet handle for base member:\n");
sts = EssOtlFindMember(hOutline, "Doe,Jane", &hBaseMbr);
/* Get handle for indep dimensions*/

printf("\nGet handle for indep dimensions:\n");
sts = EssOtlFindMember(hOutline, "Time Periods", &IndDimsArray[0]);
sts = EssOtlFindMember(hOutline, "Years", &IndDimsArray[1]);
/* Associate the dimension Entities and Type*/

printf("\nAssociate the dimensions:\n");
countOfIndDims = 2;
pucIndependentTypes[0] = ESS_ASSOCIATE_TYPE_DISCRETE;
pucIndependentTypes[1] = ESS_ASSOCIATE_TYPE_CONTINUOUS;
sts = EssOtlVaryingAssociateAttributeDimension(hOutline, hBaseDim, hAttrDim,
countOfIndDims, IndDimsArray, pucIndependentTypes);
printf("EssOtlVaryingAssociateAttributeDimension sts: %d\n", sts);
/* Initial valid case with ValiditySetType of member handles*/

printf("\n*** Initial valid case with ValiditySetType of member handles ***\n");
printf("\nGet handle for attribute member:\n");
sts = EssOtlFindMember(hOutline, "Regular", &hAttrMbr);
sts = EssOtlFindMember(hOutline, "Jan", &hIndepMbrsArray[0]);
964
sts = EssOtlFindMember(hOutline, "FY03", &hIndepMbrsArray[1]);
memset(&ValiditySet, '\0', sizeof(ValiditySet));

ValiditySet.countOfIndepDims = 2;
ValiditySet.usValiditySetType = ESS_VALIDITYSET_TYPE_MBRHDLS;
ValiditySet.countOfIndepRanges = 1;
ValiditySet.pIndepMbrs = hIndepMbrsArray;
printf("\nBefore association:");
DisplayVaryingAttributes(hOutline, hBaseMbr, hAttrDim, ESS_NULL, usValiditySetType);
mode = ESS_ASSOCIATE_MODE_NOOVERWRITE;
sts = EssOtlVaryingAssociateAttribute(hOutline, hBaseMbr, hAttrMbr, mode,
&ValiditySet);
printf("EssOtlVaryingAssociateAttribute sts: %d\n", sts);
/* Restructure and save outline */


Object.FileName);
}
See Also
EssOtlVaryingAssociateAttributeDimension
Associates a base dimension with an attribute dimension and defines the base dimension as
having varying attributes. Member attribute associations vary depending on the level-0 members
of the given independent dimensions, of types specified in pucIndependentTypes.
Continuous independent dimensions must be specified last.
Syntax
ESS_FUNC_M EssOtlVaryingAssociateAttributeDimension (hOutline, hBaseDim, hAttrDim,
countOfIndepDims, *pIndepDims, *pucIndependentTypes);
hBaseDim ESS_HMEMBER_T Base dimension handle
965
hAttrDim ESS_HMEMBER_T Attribute dimension handle
countOfIndepDims ESS_INT32_T The number of independent dimensions that control the varying
attribute
*pIndepDims ESS_HMEMBER_T Pointer to an array of member handles for the independent dimensions
*pucIndependentTypes ESS_UCHAR_T Pointer to an array of independent types contained in

*pIndepDims.
The independent types supported are:
l ESS_ASSOCIATE_TYPE_DISCRETE
l ESS_ASSOCIATE_TYPE_CONTINUOUS
Return Value
Example
void TestEssOtlVaryingAssociateAttributeDimenion()
{
ESS_HMEMBER_T hBaseDim = ESS_NULL;
ESS_HMEMBER_T hAttrDimArray[9];
ESS_OUTLINEINFO_T *pOutlineInfo;
ESS_MBRINFO_T *pMemberInfo;
int i;

Object.hCtx = hCtx;
/* Open the outline.*/

printf("\n");
SetupTest(hOutline);
/* Enable Varying Attributes - optional if already enabled */

sts = EssOtlGetOutlineInfo(hOutline, &pOutlineInfo);
pOutlineInfo->fEnableVaryingAttrs = ESS_TRUE;
sts = EssOtlSetOutlineInfo(hOutline, pOutlineInfo);
966
/* Assign independent dimension array, identifying independent dims */
/* Get handles to base and attribute dimensions for test.*/

sts = EssOtlFindMember(hOutline, "Type", &hAttrDimArray[0]);

sts = EssOtlFindMember(hOutline, "FT/PT", &hAttrDimArray[1]);
/* Set independent dimensions. Optional if already set */

sts = EssOtlGetMemberInfo(hOutline, hAttrDimArray[0], &pMemberInfo);
pMemberInfo->fIndependentDim = ESS_TRUE;
sts = EssOtlSetMemberInfo(hOutline, hAttrDimArray[0], pMemberInfo);
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1, pMemberInfo);
sts = EssOtlGetMemberInfo(hOutline, hAttrDimArray[1], &pMemberInfo);

pMemberInfo->fIndependentDim = ESS_TRUE;
sts = EssOtlSetMemberInfo(hOutline, hAttrDimArray[1], pMemberInfo);
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1, pMemberInfo);
/* Disassociate current association before tests.*/

for (i = 0; i < 2; i++)
{
sts = EssOtlDisassociateAttributeDimension(hOutline, hBaseDim,
hAttrDimArray[i]);
}
/* Associate the dimension Entities to Type */

printf("\nValid case: Associate the dimension Entities and Type:\n");
countOfIndDims = 2;
sts = EssOtlVaryingAssociateAttributeDimension(hOutline, hBaseDim, hAttrDimArray[0],

Object.FileName);
/* Close the outline */

}
See Also
967
EssOtlVaryingDisassociateAttribute
Disassociates the attribute members in the given attribute dimension from the specified base
member. The given validity set specifies where the disassociations should occur.
Syntax
ESS_FUNC_M EssOtlVaryingDisassociateAttribute (hOutline, hBaseMember, hAttrDim, mode,
pValiditySet);
hBaseMember ESS_HMEMBER_T Base member handle
hAttrDim ESS_HMEMBER_T Attribute member handle
mode ESS_INT_T Association mode. Possible values:

l MODE_OVERWRITE
l MODE_NOOVERWRITE
l MODE_EXTEND
pValiditySet “ESS_VALIDITYSET_T” on page Pointer to the set of independent members where the
720 disassociation occurs
Notes
l This function removes attribute associations from the specified base members.
l When a full range is specified, the disassociation is made as specified.
l Association mode determines how to handle situations when only the starting tuple is
specified instead of a full range. (For these description examples, assume the following
associations of members of the Ounces attribute dimension with product 100-10 prior to
disassociation):
Jan Feb Mar Apr May
12 12 16 16 12
m MODE_OVERWRITE: Disassociation starts from the specified member through all

members that follow it. Example: Disassociation starting with Feb.
Result: Associations are removed from Feb and all members after it:
Jan Feb Mar Apr May
12
m MODE_NOOVERWRITE: Disassociation starts at the specified tuple and continues
until the existing associated attribute member is different. Example: Disassociation
starting with Mar.
968
Result: Since Mar also has attribute 16, both the Apr and Mar associations are removed:
Jan Feb Mar Apr May
12 12 12
m MODE_EXTEND: Similar to MODE_NOOVERWRITE except that the association
immediately ahead of the start tuple is extended over the disassociated member.
Example: Disassociation starting with Mar
Result: The Mar and Apr associations are removed; they assume the association of the
previous month, Feb.
Jan Feb Mar Apr May
12 12 12 12 12
Return Value
Example
void TestEssOtlVaryingDisassociateAttribute()
{
ESS_HMEMBER_T hBaseMbr, hAttrMbr, hBaseDim, hAttrDim, hIndDim = ESS_NULL;
ESS_INT_T mode;
ESS_VALIDITYSET_T ValiditySet;
ESS_HMEMBER_T hIndepMbrsArray[4];
ESS_STR_T IndepMbrsArray[4];

Object.hCtx = hCtx;
printf("\n");
/* Disassociate base dimension from attribute dimension before test.*/

printf("\nDisassociate base dimension from attribute dimension before test:");
sts = EssOtlFindMember(hOutline, "Type", &hAttrDim);
sts = EssOtlDisassociateAttributeDimension(hOutline, hBaseDim, hAttrDim);
/* Get handle for base member*/

printf("\nGet handle for base member:\n");
969
sts = EssOtlFindMember(hOutline, "Doe,Jane", &hBaseMbr);
/* Get handle for indep dimensions*/

printf("\nGet handle for indep dimensions:\n");
/* Associate the dimension Entities and Type*/

printf("\nAssociate the dimensions:\n");
countOfIndDims = 2;
sts = EssOtlVaryingAssociateAttributeDimension(hOutline, hBaseDim, hAttrDim,
/* Initial valid case with ValiditySetType of member handles*/

printf("\n*** Initial valid case with ValiditySetType of member handles ***\n");
printf("\nGet handle for attribute member:\n");
sts = EssOtlFindMember(hOutline, "Regular", &hAttrMbr);


ValiditySet.usValiditySetType = ESS_VALIDITYSET_TYPE_MBRHDLS;
ValiditySet.pIndepMbrs = hIndepMbrsArray;
printf("\nBefore association:");
DisplayVaryingAttributes(hOutline, hBaseMbr, hAttrDim, ESS_NULL, usValiditySetType);
mode = ESS_ASSOCIATE_MODE_NOOVERWRITE;
sts = EssOtlVaryingAssociateAttribute(hOutline, hBaseMbr, hAttrMbr, mode,
&ValiditySet);
printf("EssOtlVaryingAssociateAttribute sts: %d\n", sts);
/* Disassociation */
IndepMbrsArray[0]= "";
ValiditySet.usValiditySetType = ESS_VALIDITYSET_TYPE_MBRNAMS;
ValiditySet.pIndepMbrs = IndepMbrsArray;
970
mode = ESS_DISASSOCIATE_MODE_NOOVERWRITE;
sts = EssOtlVaryingDisassociateAttribute(hOutline, hBaseMbr, hAttrDim, mode,
&ValiditySet);
printf("EssOtlVaryingDisassociateAttribute sts: %d\n", sts);
/* Restructure and save outline */


Object.FileName);
}
See Also
EssOtlVaryingGetAssociatedAttributes
Returns the attribute members in the specified attribute dimension associated with the given
base member where the association validity includes at least one of the tuples in the given
perspective.
For each qualifying attribute member, the full validity set of its association to the base member
can be optionally returned (by specifying a non-null value for pppValiditySets).
pphMembers and pppValiditySets will contain the array of member handles and array of
validity set pointers, respectively.
The type of validity set desired is indicated using usValiditySetType.
Note that the perspective must specify discrete independent members individually.
If no perspective is specified, or if the perspective specifies a NULL set of independent members,
the routine will consider all associations that exist for any combination of independent members.
In this case, the returned validity sets may contain ranges for discrete independent members,
and it is the responsibility of the client to split these accordingly.
Syntax
ESS_FUNC_M EssOtlVaryingGetAssociatedAttributes (hOutline, hBaseMember, hAttrDim,
pPerspective, pusCount,
pphMembers, usValiditySetType, **pppValiditySets);
971
hBaseMember ESS_HMEMBER_T Handle to the member of the base dimension
hAttrDim ESS_HMEMBER_T Attribute member handle
pPerspective “ESS_PERSPECTIVE_T” on Pointer to the collection of independent members used when

page 718 querying the client or server for associations
pusCount ESS_PUSHORT_T Pointer to the number of varying attribute members returned
pphMembers ESS_PPHMEMBER_T Pointer to the array of attribute member handles
usValiditySetType ESS_USHORT_T Type of validity set assigned to independent members:

l ESS_VALIDITYSET_TYPE_MBRHDLS—As an XRange of
member handles. For example, Mar 2003-Feb 2004 consists of
ten months of 2003 (starting with March) and the first two
months of 2004 (ending with February).
l ESS_VALIDITYSET_TYPE_MBRNAMS—As an XRange of
member names
**pppValiditySets “ESS_VALIDITYSET_T” on A collection of independent members for which an association is true

page 720
Return Value
Example
void DisplayVaryingAttributes(ESS_HOUTLINE_T hOutline, ESS_HMEMBER_T hBaseMbr,
ESS_HMEMBER_T hAttrDim,
ESS_PERSPECTIVE_T *pPerspective,
ESS_USHORT_T usValiditySetType)
{
ESS_USHORT_T Count, i, j, totalIndMbrs;
ESS_PHMEMBER_T phAttrMbrs;
ESS_PVALIDITYSET_T *ppValiditySets;
ESS_PMBRINFO_T pMemberInfo1, pMemberInfo2;
sts = EssOtlVaryingGetAssociatedAttributes(hOutline,
hBaseMbr,
hAttrDim,
pPerspective,
&Count,
&phAttrMbrs,
usValiditySetType,
&ppValiditySets);
printf("\nEssOtlVaryingGetAssociatedAttributes sts: %d", sts);
if(!sts)
{
if(Count)
{
for (i = 0; i < Count ;++i)
{
sts = EssOtlGetMemberInfo(hOutline, phAttrMbrs[i], &pMemberInfo1);
972
printf("\n\t%s", pMemberInfo1->szMember);
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1, pMemberInfo1);
if(ppValiditySets[i])
{
totalIndMbrs = (ESS_SHORT_T)(ppValiditySets[i]->countOfIndepRanges)
* 4;
printf("\n\t\tValidity Type: %d - ", ppValiditySets[i]-
>usValiditySetType);
switch(ppValiditySets[i]->usValiditySetType)
{
case ESS_VALIDITYSET_TYPE_MBRHDLS:
printf("Member Handles");
for(j = 0; j < totalIndMbrs; j++)

{
if(j >= 3)
if(j%4 == 0)
printf("\n");
sts = EssOtlGetMemberInfo(hOutline, ppValiditySets[i]-
>pIndepMbrs[j], &pMemberInfo2);
printf("\n\t\tValidity independent member: %s",
pMemberInfo2->szMember);
EssOtlFreeStructure(hOutline, ESS_DT_STRUCT_MBRINFO, 1,
pMemberInfo2);
}
break;
case ESS_VALIDITYSET_TYPE_MBRNAMS:
printf("Member Names");
for(j = 0; j < totalIndMbrs; j++)

{
if(j >= 3)
if(j%4 == 0)
printf("\n");
printf("\n\t\tValidity independent member: %s",
ppValiditySets[i]->pIndepMbrs[j]);
}
break;
default:
printf("Unrecognized");
}
printf("\n\t\tValidity count of Indep Dims: %d", ppValiditySets[i]-
>countOfIndepDims);
printf("\n\t\tValidity count of Indep Ranges: %d", ppValiditySets[i]-
>countOfIndepRanges);
printf("\n");
}
EssFree(hInst, ppValiditySets[i]);
}
printf("\n");
}
else
printf("\n\tNo member returned.\n");
}
printf("\n");
EssFree(hInst,ppValiditySets);
973
}
See Also
EssOtlVaryingGetAttributeIndepDims
Returns the independent dimensions, if any, for the given attribute member.
Syntax
ESS_FUNC_M EssOtlVaryingGetAttributeIndepDims (hOutline, hAttrMember,
*pCountOfIndepDims, **ppIndepDims, **ppucIndependentTypes);
hAttrMember ESS_HMEMBER_T Attribute member handle
*pCountOfIndepDims ESS_INT32_T Pointer to the number of independent dimensions that control the
varying attributes
**ppIndepDims ESS_HMEMBER_T Pointer to an array of member handles for the independent

dimensions
**ppucIndependentTypes ESS_UCHAR_T Pointer to an array of independent types contained in

*pIndepDims
Notes
An independent dimension is a dimension the values of which identify where the attribute
associations may change. Independent dimensions are selected when attribute dimensions are
associated with a base dimension. VaryingGetAttributeIndepDims returns a list of independent
dimensions associated with the dimension of the specified attribute.
Return Value
Example
void TestEssOtlVaryingGetAttributeIndepDims()
{
ESS_STR_T attrMbr, attrDim, baseMbr, baseDim;
ESS_USHORT_T i;
974
ESS_HMEMBER_T hBaseDim;
ESS_INT32_T pCountOfIndepDims;
ESS_HMEMBER_T *ppIndepDims;
ESS_PMBRINFO_T pMemberInfo;
ESS_UCHAR_T *pucIndependentTypes;

Object.hCtx = hCtx;
printf("\n");
printf("\nGet handles of members for tests:\n");

attrMbr = "Contractor";
sts = EssOtlFindMember(hOutline, attrMbr, &hAttrMbr);
attrDim = "Type";
sts = EssOtlFindMember(hOutline, attrDim, &hAttrDim);
baseMbr = "Doe,Jane";
sts = EssOtlFindMember(hOutline, baseMbr, &hBaseMbr);
baseDim = "Entities";
sts = EssOtlFindMember(hOutline, baseDim, &hBaseDim);
/* Valid case with a valid attribute member handle. */

printf("\nValid case with a valid attribute member handle:\n");
sts = EssOtlVaryingGetAttributeIndepDims(hOutline, hAttrMbr, &pCountOfIndepDims,
&ppIndepDims, &pucIndependentTypes);
printf("EssOtlVaryingGetAttributeIndepDims sts: %d\n", sts);
if(pCountOfIndepDims)
{
printf("Independent dimension(s) for attribute member %s:", attrMbr);
for (i = 0; i < pCountOfIndepDims; i++)
{
sts = EssOtlGetMemberInfo(hOutline, ppIndepDims[i], &pMemberInfo);
printf("\n\t%s", pMemberInfo->szMember);
switch(pucIndependentTypes[i])
{
case ESS_ASSOCIATE_TYPE_CONTINUOUS:
printf(" - (Continuous)");
break;
case ESS_ASSOCIATE_TYPE_DISCRETE:
printf(" - (Discrete)");
break;
}
}
printf("\n");
975
}
else
printf("\tAttribute member %s has no independent dimension.\n", attrMbr);

Object.FileName);
}
See Also
EssOtlVerifyFormula
Verifies that an outline is correct. This function returns both global outline errors and errors for
each incorrect member. This function is called by EssOtlVerifyOutlineEx, but can also be
called directly from a client program.
Syntax
ESS_FUNC_M EssOtlVerifyFormula (hOutline, hCtx, FormulaString, pErrorNumber, pErrorLine,
MemberName, ErrorBufferLength, ErrorMessage);
hCtx ESS_HCTX_T API context handle. If the outline is a local outline, it is necessary to also
provide this separate hCtx to a running server, because formula checking only
is done on the server, and outlines from the file system do not have a server
connected to them. This parameter should normally be NULL.
FormulaString ESS_STR_T The syntactic formula expression.
pErrorNumber ESS_PULONG_T Pointer to the count of errors.
pErrorLine ESS_PULONG_T Pointer to the error line number.
MemberName ESS_STR_T Name of member that has the formula. This is an optional field. Supplying it
will enhance the error message, especially if EssOtlVerifyFormula() is called
within a loop.
ErrorBufferLength ESS_ULONG_T The size of the error buffer.
ErrorMessage ESS_STR_T The error message contained in the error buffer. This is a pre-allocated string
which contains a descriptive message of any error (including error number,
line number, and member name). It should be set to a length of at least 400
bytes.
976
Notes
l The return value is normally zero, even if the formula has errors. A non zero return value
means serious code-level error.
l This function is called by EssOtlVerifyOutlineEx, but can also be called directly from
a client program.
Return Value
This function returns zero if successful, otherwise it returns an error code of either
OTLAPI_ERR_HOUTLINE or OTLAPI_NULL_ARG. The return value can be zero even in the
case of minor errors in the formula. A non-zero return value indicates a serious code-level error.
Any formula error is returned in the pErrorNumber and pErrorLine variables.
A non-zero return value indicates a serious code-level error in which case the error checking has
been interrupted and pErrorNumber and pErrorLine both are set to zero.
See Also
l EssVerifyFilter
l EssVerifyRulesFile
EssOtlVerifyOutline
Verifies that an outline is correct. The function returns both global outline errors and errors for
each incorrect member.
Syntax
ESS_FUNC_M EssOtlVerifyOutline (hOutline, pulErrors, pulCount, pMbrErrors);
pulErrors ESS_PULONG_T Pointer to bitmask destination for global outline errors. Currently, this field
has only one value:
ESS_OUTERROR_CURTOOMANYDIMS
pulCount ESS_PULONG_T Count of members with errors. This defines the number of elements of the
pMbrErrors array.
pMbrErrors “ESS_OUTERROR_T” on Pointer to an array with *pulCount members. Each element of the array
page 713 contains the errors for a single member.
Notes
l This function checks for:
m Duplicate user attributes in shared members
m Duplicate level or generation names or aliases
m Restrictions on adding and associating attributes
977
l Saving the outline to the server succeeds only when the outline is free of errors (*pulErrors
== 0 and *pulCount == 0).
l Use EssFree() to free the pMbrErrors array.
Return Value
l ESS_OUTERROR_SHAREUDA
l ESS_OUTERROR_DUPGENLEVNAME
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
ESS_POUTERROR_T pMbrErrors = ESS_NULL;

Object.hCtx = hCtx;

if (!sts)
{
sts = EssOtlVerifyOutline(hOutline, &ulErrors,
&ulCount, &pMbrErrors);
}
if (pMbrErrors)
{
EssFree(hInst, pMbrErrors);
}
See Also
l EssOtlNewOutline
l EssOtlOpenOutline
978
EssOtlVerifyOutlineEx
Verifies that the specified outline is correct and builds an array of the errors found in that outline.
The function returns both global outline errors and errors for each incorrect member.
Syntax
ESS_FUNC_M EssOtlVerifyOutlineEx (hOutline, pulErrors, pulCount, pMbrErrors);
pulErrors ESS_PULONG_T Pointer to bitmask destination for global outline errors. If the outline had
formula errors the only field with a value is:
ESS_OUTERROREX_OUTLINEHASFORMULAERROR
pulCount ESS_PULONG_T Count of members with errors. This defines the number of elements of the
pMbrErrors array. The errors will be bitmasks if the outline had errors. If the
outline had only formula errors the pMbrError fields comprise error numbers
(ulErrors) and line numbers (ulErrors2). In that case pulErrors is set to
ESS_OUTERROREX_OUTLINEHASFORMULAERROR.
pMbrErrors “ESS_OUTERROR_T” Pointer to an array with *pulCount members. Each element of the array contains
on page 713 the errors for a single member.
Notes
l This function calls EssOtlVerifyOutline. If that call is successful, this function then calls
EssOtlVerifyFormula for each member that has a formula and includes any formula
errors in the output error array. If the call to EssOtlVerifyOutline() in not successful, this
function operates exactly like EssOtlVerifyOutline().
m Duplicate user attributes in shared members.
m Duplicate level or generation names or aliases.
m Restrictions on adding and associating attributes.
l Use EssFree() to free the pMbrErrors array.
Return Value
l OTLAPI_ERR_OPENMODE
l OTLAPI_BAD_HOUTLINE OTLAPI_NULL_ARG
Example
ESS_STS_T TestVerifyOtlEx(ADT_CMDCTX_T *cmdctxp)
{
ESS_STS_T sts2 = ESS_STS_NOERR;
ESS_SHORT_T hOutline;
979
ESS_POUTERROR_T pMbrErrors;
ESS_ULONG_T ind;
ESS_PMBRINFO_T ppMbrInfo;
if (cmdctxp->cmdbuf.argn < 2)
{
hOutlineChoice = ishOutlineMenu(cmdctxp);
}
else
{
hOutlineChoice = atoi(*(cmdctxp->cmdbuf.args + 1));
}
sts = EssOtlVerifyOutlineEx(cmdctxp->hOutline[hOutlineChoice], &ulErrors,

&ulCount, &pMbrErrors);
{
fprintf(cmdctxp->output, "\n------Global Errors------\n");
if (ulErrors & ESS_OUTERROR_CURTOOMANYDIMS)

{
fprintf(cmdctxp->output, "Too many dimensions in currency outline\n");
}
else if(ulErrors & ESS_OUTERROR2_ATTRCALCABSENT)
{
fprintf(cmdctxp->output, "Attribute calculations dimension is absent\n");
}
else if(ulErrors & ESS_OUTERROREX_OUTLINEHASFORMULAERROR)
{
fprintf(cmdctxp->output, "Outline has formula error\n");
}
else if (ulErrors == 0)
{
fprintf(cmdctxp->output, "No errors\n");
}
else
{
fprintf(cmdctxp->output, "Unknown error\n");
}
fprintf(cmdctxp->output, "\n------Member Errors------\n");
if(ulErrors != ESS_OUTERROREX_OUTLINEHASFORMULAERROR)
{
for (ind = 0; ind < ulCount; ind++)
{
sts2 = EssOtlGetMemberInfo(cmdctxp-
>hOutline[hOutlineChoice],
pMbrE
rrors[ind].hMember, &ppMbrInfo);
if (sts2 == ESS_STS_NOERR)
{
fprintf(cmdctxp->output, "Member: %s\n",
ppMbrInfo->szMember);
EssFree(cmdctxp->hInst, ppMbrInfo);
980
}
else
{
fprintf(cmdctxp->output, "Member: Unknown member
\n");
}
if (pMbrErrors[ind].ulErrors &
ESS_OUTERROR_ILLEGALNAME)
{
fprintf(cmdctxp->output, "
ESS_OUTERROR_ILLEGALNAME\n");
}
ESS_OUTERROR_DUPLICATENAME)
{
ESS_OUTERROR_DUPLICATENAME\n");
}
ESS_OUTERROR_ILLEGALCURRENCY)
{
ESS_OUTERROR_ILLEGALCURRENCY\n");
}
ESS_OUTERROR_ILLEGALDEFALIAS)
{
ESS_OUTERROR_ILLEGALDEFALIAS\n");
}
ESS_OUTERROR_ILLEGALCOMBOALIAS)
{
ESS_OUTERROR_ILLEGALCOMBOALIAS\n");
}
ESS_OUTERROR_ILLEGALALIASSTRING)
{
ESS_OUTERROR_ILLEGALALIASSTRING\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_ILLEGALTAG)

{
fprintf(cmdctxp->output,"
ESS_OUTERROR_ILLEGALTAG\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_NOTIMEDIM)

{
981
ESS_OUTERROR_NOTIMEDIM\n");
}
ESS_OUTERROR_DUPLICATEALIAS)
{
ESS_OUTERROR_DUPLICATEALIAS\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_MEMBERCALC)

{
ESS_OUTERROR_MEMBERCALC\n");
}
ESS_OUTERROR_SHARENOTLEVEL0)
{
ESS_OUTERROR_SHARENOTLEVEL0\n");
}
ESS_OUTERROR_NOSHAREPROTO)
{
ESS_OUTERROR_NOSHAREPROTO\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_TIMESPARSE)

{
ESS_OUTERROR_TIMESPARSE\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_LEAFLABEL)

{
ESS_OUTERROR_LEAFLABEL\n");
}
ESS_OUTERROR_ALIASSHARED)
{
ESS_OUTERROR_ALIASSHARED\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADTIMEBAL)

{
ESS_OUTERROR_BADTIMEBAL\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADSKIP)
982
{
fprintf(cmdctxp->output," ESS_OUTERROR_BADSKIP
\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADSHARE)

{
fprintf(cmdctxp->output," ESS_OUTERROR_BADSHARE
\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADSTORAGE)

{
ESS_OUTERROR_BADSTORAGE\n");
}
ESS_OUTERROR_BADCATEGORY)
{
ESS_OUTERROR_BADCATEGORY\n");
}
ESS_OUTERROR_BADSTORAGECATEGORY)
{
ESS_OUTERROR_BADSTORAGECATEGORY\n");
}
ESS_OUTERROR_SHAREDMEMBERFORMULA)
{
ESS_OUTERROR_SHAREDMEMBERFORMULA\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_SHAREUDA)

{
fprintf(cmdctxp->output," ESS_OUTERROR_SHAREUDA
\n");
}
ESS_OUTERROR_DUPGENLEVNAME)
{
ESS_OUTERROR_DUPGENLEVNAME\n");
}
ESS_OUTERROR_VIRTLEV0NOFORMULA)
{
ESS_OUTERROR_VIRTLEV0NOFORMULA\n");
}
983
ESS_OUTERROR_VIRTBADPARENT)
{
ESS_OUTERROR_VIRTBADPARENT\n");
}
ESS_OUTERROR_VIRTBADCHILD)
{
ESS_OUTERROR_VIRTBADCHILD\n");
}
ESS_OUTERROR_VIRTWHOLEDIMVIRTUAL)
{
ESS_OUTERROR_VIRTWHOLEDIMVIRTUAL\n");
}
if (pMbrErrors[ind].ulErrors2 &
ESS_OUTERROR2_NOTLEVEL0)
{
ESS_OUTERROR2_NOTLEVEL0\n");
}
ESS_OUTERROR2_LEVELMISMATCH)
{
ESS_OUTERROR2_LEVELMISMATCH\n");
}
ESS_OUTERROR2_ILLEGALORDER)
{
ESS_OUTERROR2_ILLEGALORDER\n");
}
ESS_OUTERROR2_ILLEGALDATATYPE)
{
}
ESS_OUTERROR2_DATATYPEMISMATCH)
{
ESS_OUTERROR2_DATATYPEMISMATCH\n");
}
ESS_OUTERROR2_ILLEGALATTRIBUTEPARENT)
{
ESS_OUTERROR2_ILLEGALATTRIBUTEPARENT\n");
984
}
ESS_OUTERROR2_ATTRDIMNOTASSOCIATED)
{
ESS_OUTERROR2_ATTRDIMNOTASSOCIATED\n");
}
ESS_OUTERROR2_ILLEGALUDA)
{
ESS_OUTERROR2_ILLEGALUDA\n");
}
ESS_OUTERROR2_CHILDCOUNT)
{
ESS_OUTERROR2_CHILDCOUNT\n");
}
ESS_OUTERROR2_ILLEGALATTRCALC)
{
ESS_OUTERROR2_ILLEGALATTRCALC\n");
}
ESS_OUTERROR2_DUPLICATEATTRCALC)
{
ESS_OUTERROR2_DUPLICATEATTRCALC\n");
}
ESS_OUTERROR2_ILLEGALATTRSET)
{
ESS_OUTERROR2_ILLEGALATTRSET\n");
}
ESS_OUTERROR2_ILLEGALATTRCALCSET)
{
ESS_OUTERROR2_ILLEGALATTRCALCSET\n");
}
ESS_OUTERROR2_NOTATTRIBUTE)
{
ESS_OUTERROR2_NOTATTRIBUTE\n");
}
ESS_OUTERROR2_ATTRCALCABSENT)
{
ESS_OUTERROR2_ATTRCALCABSENT\n");
}
ESS_OUTERROR2_ILLEGALATTRVALUE)
985
{
ESS_OUTERROR2_ILLEGALATTRVALUE\n");
}
}
}
if(ulErrors == ESS_OUTERROREX_OUTLINEHASFORMULAERROR)
{
{
sts2 = EssOtlGetMemberInfo(cmdctxp->hOutline[hOutlineChoice],
pMbrErrors[ind].hMember,
&ppMbrInfo);
{
fprintf(cmdctxp->output, "Member: %s\n", ppMbrInfo-
>szMember);
}
else
{
fprintf(cmdctxp->output, "Member: Unknown member\n");
}
fprintf(cmdctxp->output, "Error %d at line %d\n",

pMbrErrors[ind].ulErrors, pMbrErrors[ind].ulErrors2);
}
}
if (ulCount == 0)
{
}
EssFree(cmdctxp->hInst, pMbrErrors);
}
fprintf(cmdctxp->output, "\nsts: %ld\n\n", sts);
return(sts);
}
See Also
l EssOtlNewOutline
l EssOtlOpenOutline
l EssOtlVerifyOutlineEx3
986
EssOtlVerifyOutlineEx3
Verifies that the specified outline is correct, and builds two arrays of errors. The function returns
member errors in ppMbrErrors, and formula errors in ppFormulaErrors.
Syntax
ESS_FUNC_M EssOtlVerifyOutlineEx3 (hOutline, pulErrors, pulCount, ppMbrErrors,
pulFormulaCount, ppFormulaErrors);
pulErrors ESS_PULONG_T Pointer to bitmask destination for global outline errors. If the outline had
formula errors the only field with a value is:
ESS_OUTERROREX_OUTLINEHASFORMULAERROR
pulCount ESS_PULONG_T Count of members with errors. This defines the number of elements of
the pMbrErrors array. The errors will be bitmasks.
ppMbrErrors ESS_PPOUTERROR_T Pointer to an array with *pulCount members. Each element of the array
contains the errors for a single member.
pulFormulaCount ESS_PULONG_T Count of members with formula errors. This defines the number of
elements of the pFormulaErrors array.
ppFormulaErrors ESS_PPOUTERROR_T Pointer to an array with *pulFormulaCount members. Each element

of the array contains the errors for a single formula.
Notes
l This function differs from EssOtlVerifyOutlineEx in that it provides both member warnings
and formula errors.
m Duplicate user attributes in shared members.
m Duplicate level or generation names or aliases.
m Restrictions on adding and associating attributes.
m Formula errors (however, if there are verification errors, this function does not display
formula errors).
l Use EssFree() to free the pMbrErrors array and the pFormulaErrors array.
Return Value
l OTLAPI_ERR_OPENMODE
l OTLAPI_BAD_HOUTLINE OTLAPI_NULL_ARG
Example
ESS_STS_T TestVerifyOtlEx3(ADT_CMDCTX_T *cmdctxp)
{
987
ESS_STS_T sts2 = ESS_STS_NOERR;
ESS_SHORT_T hOutline;
ESS_POUTERROR_T pMbrErrors;
ESS_ULONG_T ulFormulaCount;
ESS_POUTERROR_T pFormulaErrors;
ESS_ULONG_T ind;
ESS_PMBRINFO_T ppMbrInfo;
if (cmdctxp->cmdbuf.argn < 2)
{
hOutlineChoice = ishOutlineMenu(cmdctxp);
}
else
{
hOutlineChoice = atoi(*(cmdctxp->cmdbuf.args + 1));
}
sts = EssOtlVerifyOutlineEx3(cmdctxp->hOutline[hOutlineChoice], &ulErrors,

&ulCount, &pMbrErrors, &ulFormulaCount, &pFormulaErrors);
{
fprintf(cmdctxp->output, "\n------Global Errors------\n");
if (ulErrors & ESS_OUTERROR_CURTOOMANYDIMS)

{
fprintf(cmdctxp->output, "Too many dimensions in currency outline\n");
}
else if(ulErrors & ESS_OUTERROR2_ATTRCALCABSENT)
{
fprintf(cmdctxp->output, "Attribute calculations dimension is absent\n");
}
else if(ulErrors & ESS_OUTERROREX_OUTLINEHASFORMULAERROR)
{
fprintf(cmdctxp->output, "Outline has formula error\n");
}
else if (ulErrors == 0)
{
}
else
{
fprintf(cmdctxp->output, "Unknown error\n");
}
fprintf(cmdctxp->output, "\n------Member Errors------\n");
if(ulErrors != ESS_OUTERROREX_OUTLINEHASFORMULAERROR)
{
{
sts2 = EssOtlGetMemberInfo(cmdctxp-
>hOutline[hOutlineChoice],
988
pMbrE
rrors[ind].hMember, &ppMbrInfo);
{
fprintf(cmdctxp->output, "Member: %s\n",
ppMbrInfo->szMember);
}
else
{
fprintf(cmdctxp->output, "Member: Unknown member
\n");
}
ESS_OUTERROR_ILLEGALNAME)
{
ESS_OUTERROR_ILLEGALNAME\n");
}
ESS_OUTERROR_DUPLICATENAME)
{
ESS_OUTERROR_DUPLICATENAME\n");
}
ESS_OUTERROR_ILLEGALCURRENCY)
{
ESS_OUTERROR_ILLEGALCURRENCY\n");
}
ESS_OUTERROR_ILLEGALDEFALIAS)
{
ESS_OUTERROR_ILLEGALDEFALIAS\n");
}
ESS_OUTERROR_ILLEGALCOMBOALIAS)
{
ESS_OUTERROR_ILLEGALCOMBOALIAS\n");
}
ESS_OUTERROR_ILLEGALALIASSTRING)
{
ESS_OUTERROR_ILLEGALALIASSTRING\n");
}
989
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_ILLEGALTAG)
{
ESS_OUTERROR_ILLEGALTAG\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_NOTIMEDIM)

{
ESS_OUTERROR_NOTIMEDIM\n");
}
ESS_OUTERROR_DUPLICATEALIAS)
{
ESS_OUTERROR_DUPLICATEALIAS\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_MEMBERCALC)

{
ESS_OUTERROR_MEMBERCALC\n");
}
ESS_OUTERROR_SHARENOTLEVEL0)
{
ESS_OUTERROR_SHARENOTLEVEL0\n");
}
ESS_OUTERROR_NOSHAREPROTO)
{
ESS_OUTERROR_NOSHAREPROTO\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_TIMESPARSE)

{
ESS_OUTERROR_TIMESPARSE\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_LEAFLABEL)

{
ESS_OUTERROR_LEAFLABEL\n");
}
ESS_OUTERROR_ALIASSHARED)
{
ESS_OUTERROR_ALIASSHARED\n");
}
990
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADTIMEBAL)
{
ESS_OUTERROR_BADTIMEBAL\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADSKIP)

{
fprintf(cmdctxp->output," ESS_OUTERROR_BADSKIP
\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADSHARE)

{
fprintf(cmdctxp->output," ESS_OUTERROR_BADSHARE
\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_BADSTORAGE)

{
ESS_OUTERROR_BADSTORAGE\n");
}
ESS_OUTERROR_BADCATEGORY)
{
ESS_OUTERROR_BADCATEGORY\n");
}
ESS_OUTERROR_BADSTORAGECATEGORY)
{
ESS_OUTERROR_BADSTORAGECATEGORY\n");
}
ESS_OUTERROR_SHAREDMEMBERFORMULA)
{
ESS_OUTERROR_SHAREDMEMBERFORMULA\n");
}
if (pMbrErrors[ind].ulErrors & ESS_OUTERROR_SHAREUDA)

{
fprintf(cmdctxp->output," ESS_OUTERROR_SHAREUDA
\n");
}
ESS_OUTERROR_DUPGENLEVNAME)
{
ESS_OUTERROR_DUPGENLEVNAME\n");
991
}
ESS_OUTERROR_VIRTLEV0NOFORMULA)
{
ESS_OUTERROR_VIRTLEV0NOFORMULA\n");
}
ESS_OUTERROR_VIRTBADPARENT)
{
ESS_OUTERROR_VIRTBADPARENT\n");
}
ESS_OUTERROR_VIRTBADCHILD)
{
ESS_OUTERROR_VIRTBADCHILD\n");
}
ESS_OUTERROR_VIRTWHOLEDIMVIRTUAL)
{
ESS_OUTERROR_VIRTWHOLEDIMVIRTUAL\n");
}
ESS_OUTERROR2_NOTLEVEL0)
{
ESS_OUTERROR2_NOTLEVEL0\n");
}
ESS_OUTERROR2_LEVELMISMATCH)
{
ESS_OUTERROR2_LEVELMISMATCH\n");
}
ESS_OUTERROR2_ILLEGALORDER)
{
}
ESS_OUTERROR2_ILLEGALDATATYPE)
{
}
ESS_OUTERROR2_DATATYPEMISMATCH)
{
992
ESS_OUTERROR2_DATATYPEMISMATCH\n");
}
ESS_OUTERROR2_ILLEGALATTRIBUTEPARENT)
{
ESS_OUTERROR2_ILLEGALATTRIBUTEPARENT\n");
}
ESS_OUTERROR2_ATTRDIMNOTASSOCIATED)
{
ESS_OUTERROR2_ATTRDIMNOTASSOCIATED\n");
}
ESS_OUTERROR2_ILLEGALUDA)
{
ESS_OUTERROR2_ILLEGALUDA\n");
}
ESS_OUTERROR2_CHILDCOUNT)
{
ESS_OUTERROR2_CHILDCOUNT\n");
}
ESS_OUTERROR2_ILLEGALATTRCALC)
{
ESS_OUTERROR2_ILLEGALATTRCALC\n");
}
ESS_OUTERROR2_DUPLICATEATTRCALC)
{
ESS_OUTERROR2_DUPLICATEATTRCALC\n");
}
ESS_OUTERROR2_ILLEGALATTRSET)
{
ESS_OUTERROR2_ILLEGALATTRSET\n");
}
ESS_OUTERROR2_ILLEGALATTRCALCSET)
{
ESS_OUTERROR2_ILLEGALATTRCALCSET\n");
}
ESS_OUTERROR2_NOTATTRIBUTE)
{
ESS_OUTERROR2_NOTATTRIBUTE\n");
}
993
ESS_OUTERROR2_ATTRCALCABSENT)
{
ESS_OUTERROR2_ATTRCALCABSENT\n");
}
ESS_OUTERROR2_ILLEGALATTRVALUE)
{
ESS_OUTERROR2_ILLEGALATTRVALUE\n");
}
}
}
if(ulErrors == ESS_OUTERROREX_OUTLINEHASFORMULAERROR)
{
for (ind = 0; ind < ulFormulaCount; ind++)
{
sts2 = EssOtlGetMemberInfo(cmdctxp->hOutline[hOutlineChoice],
pFormulaErrors
[ind].hMember, &ppMbrInfo);
{
fprintf(cmdctxp->output, "Member: %s\n", ppMbrInfo-
>szMember);
}
else
{
fprintf(cmdctxp->output, "Member: Unknown member\n");
}
fprintf(cmdctxp->output, "Error %d at line %d\n", pFormulaErrors

[ind].ulErrors, pFormulaErrors [ind].ulErrors2);
}
}
if (ulCount == 0)
{
}
EssFree(cmdctxp->hInst, pMbrErrors);
EssFree(cmdctxp->hInst, pFormulaErrors);
}
fprintf(cmdctxp->output, "\nsts: %ld\n\n", sts);
return(sts);
}
See Also
l EssOtlNewOutline
994
l EssOtlOpenOutline
EssOtlWriteOutline
Writes the existing outline information to disk.
Syntax
ESS_FUNC_M EssOtlWriteOutline (hOutline, pObject);
pObject ESS_POBJDEF_T Outline object to write.
Notes
l If you are saving the outline as a server object, the outline is initially saved as a .OTN file.
You should then call EssOtlRestructure() to create the actual .OTL file.
l If you are saving the outline as a server object, the object name must be the same as the
database name.
l The database must already exist if you are saving a server outline object, or a client outline
object to a local database.
l This call fails if the outline is not currently locked by the specified user (hCtx parameter in
the ESS_OBJDEF_T structure).
Return Value
l OTLAPI_ERR_NOTVERIFIED
Access
and/or database to contain the outline object. To write the outline object, you must have
Example
#include <essapi.h>
#include <essotl.h>
ESS_STS_T sts = 0;
995

Object.hCtx = hCtx;

/* body of code */
if (!sts)
{
}
/* restructure db using EssOtlRestructure() */
See Also
l EssOtlWriteOutlineEx
l EssOtlOpenOutline
l EssOtlNewOutline
l EssOtlRestructure
EssOtlWriteOutlineEx
Writes the existing outline information to disk, specifying whether to save in UTF-8 encoding
or in non-Unicode encoding..
Syntax
ESS_FUNC_M EssOtlWriteOutlineEx(hOutline, pObject, iOtlType);
pObject ESS_POBJDEF_T Outline object to write.
iOtlType Whether the outline is saved in Unicode mode or non-Unicode mode.

The valid values are:
l ESS_OUTLINE_UTF8 0x0002—Encoded in UTF-8.
l ESS_OUTLINE_NONUNICODE 0x0003—Not Unicode-encoded.
996
Notes
l If you are saving the outline as a server object, the outline is initially saved as a .OTN file.
You should then call EssOtlRestructure() to create the actual .OTL file.
l If you are saving the outline as a server object, the object name must be the same as the
database name.
l The database must already exist if you are saving a server outline object, or a client outline
object to a local database.
l This call fails if the outline is not currently locked by the specified user (hCtx parameter in
the ESS_OBJDEF_T structure).
Return Value
l OTLAPI_ERR_NOTVERIFIED
Access
and/or database to contain the outline object. To write the outline object, you must have
See Also
l EssOtlOpenOutlineEx
l EssOtlNewOutline
l EssOtlRestructure
997
998
C Outline API Examples
12
In This Chapter
Example of Traversing an Outline....................................................................... 999
Extended Member Query Code Example ............................................................. 1000
Example of Traversing an Outline

This example demonstrates the use of the outline tree. TraverseTree is a recursive algorithm that
traverses the outline tree to provide access to all outline members. It selects each member in
turn, allowing processing on each, until it reaches the last member. A comment in the code notes
the opportunity for added processing.
This algorithm incorporates several C Outline API commands.
l EssOtlGetFirstMember() returns a member handle to the first member (the first dimension
defined) in the outline.
l EssOtlGetMemberInfo() gets information for the specified member.
l EssOtlGetChild() returns the child of a member.
l EssOtlGetNextSibling() returns the next sibling of a member.
Before executing this code, initialize the API and open the outline. Following this code, close
the outline and terminate the API.
TraverseTree (ESS_HOUTLINE_T)
{
ESS_STS_T sts = 0;
sts = EssOtlGetFirstMember(hOutline, &hMember);

sts = TraverseTreeRecurse(hOutline, hMember);
}
TraverseTreeRecurse(ESS_HOUTLINE_T hOutline, ESS_HMEMBER_T hMember)

{
ESS_MEMBERINFO_T MbrInfo;
ESS_HMEMBER_T, hChild;
ESS_STS_T sts = 0;
while (!sts && hMember)

{
999
sts = EssOtlGetMemberInfo (hOutline, hMember, &MbrInfo);
/* ADD THE PROCESSING FOR EACH MEMBER HERE. */
if (!sts)
{
sts = EssOtlGetChild(hOutline, hMember, &hChild);
if (!sts && hChild)
{
sts = TraverseTreeRecurse(hOutline, hChild);
}
}
sts = EssOtlGetNextSibling(hOutline, hMember, &hMember);
}
return (sts);
}
Extended Member Query Code Example

#include <essapi.h>
#include <essotl.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#define AD_CHK_PRINTF_1(ARG1, ARG2)

do
{
printf(ARG1, (ARG2) ? (ARG2) : "NullValue");
}
while (0)
void PrintResult(ESS_HCTX_T hCtx,

ESS_HINST_T hInst,
ESS_HMEMBER_T hMbr)
{
ESS_PMBRINFO_T pMbrInfo = NULL;
ESS_STS_T sts;
int size;
ESS_STR_T pszFormula = NULL;
ESS_STR_T pszLastFormula = NULL;
ESS_STR_T pszCommentEx = NULL;
ESS_STR_T pszAlias = NULL;
ESS_STR_T pszAliasCombo = NULL;
ESS_PMBRNAME_T pUDAList = NULL;
ESS_USHORT_T iCount = 0;
ESS_STR_T pszPrev = NULL;
ESS_USHORT_T iIndex;
ESS_ULONG_T* pMemNum;
ESS_ULONG_T* pDimNum;
ESS_STR_T pDimName = NULL;
ESS_STR_T pAliasName = NULL;
1000
ESS_STR_T pNextName = NULL;
ESS_STR_T pPrevName = NULL;
ESS_STR_T pParentName = NULL;
ESS_STR_T pChildName = NULL;
ESS_BOOL_T* pCurrConv = NULL;
ESS_ULONG_T* pStatus = NULL;
sts = EssOtlGetMemberInfo(hOutline, hMbr, &pMbrInfo);

if (sts != 0) goto Error;
size = sizeof(ESS_MBRINFO_T);
printf("MbrInfo\n");
AD_CHK_PRINTF_1(" szMember --------------->(%s)\n", pMbrInfo->szMember);
printf(" usLevel --------------->(%hd)\n", pMbrInfo->usLevel);
printf(" usGen ----------------->(%hd)\n", pMbrInfo->usGen);
printf(" usConsolidation ------->(%hd)\n", pMbrInfo->usConsolidation);
printf(" fTwoPass -------------->(%hd)\n", pMbrInfo->fTwoPass);
printf(" fExpense -------------->(%hd)\n", pMbrInfo->fExpense);
printf(" usConversion ----------->(%hd)\n", pMbrInfo->usConversion);
AD_CHK_PRINTF_1(" szCurMember ------------>(%s)\n", pMbrInfo->szCurMember);
printf(" usTimeBalance ---------->(%hd)\n", pMbrInfo->usTimeBalance);
printf(" usSkip ----------------->(%hd)\n", pMbrInfo->usSkip);
printf(" usShare ---------------->(%hd)\n", pMbrInfo->usShare);
printf(" usStorage -------------->(%hd)\n", pMbrInfo->usStorage);
printf(" usCategory ------------->(%hd)\n", pMbrInfo->usCategory);
printf(" usStorageCategory ------>(%hd)\n", pMbrInfo->usStorageCategory);
AD_CHK_PRINTF_1(" szComment -------------->(%s)\n", pMbrInfo->szComment);
printf(" ulChildCount ----------->(%ld)\n", pMbrInfo->ulChildCount);
sts = EssOtlGetMemberFormula(hOutline, hMbr, &pszFormula);

if (sts) printf("sts=%d ", sts);
AD_CHK_PRINTF_1("szFormula ------------------>(%s)\n", pszFormula);
sts = EssOtlGetMemberLastFormula(hOutline, hMbr, &pszLastFormula);

AD_CHK_PRINTF_1("szLastFormula -------------->(%s)\n", pszLastFormula);
sts = EssOtlGetMemberCommentEx(hOutline, hMbr, &pszCommentEx);

AD_CHK_PRINTF_1("szCommentEx ---------------->(%s)\n", pszCommentEx);
sts = EssOtlGetMemberAlias(hOutline, hMbr, ESS_NULL, &pszAlias);

AD_CHK_PRINTF_1("szAlias (Default)----------->(%s)\n", pszAlias);
sts = EssOtlGetNextAliasCombination(hOutline, hMbr, ESS_NULL, "\0", &pszAliasCombo);

printf("szAliasCombo ::\n" );
pszPrev = pszAliasCombo;
while (sts && pszAliasCombo)
{
AD_CHK_PRINTF_1("\t(%s)\n", pszAliasCombo);
sts = EssOtlGetNextAliasCombination(hOutline, hMbr, ESS_NULL, pszPrev,
&pszAliasCombo);
EssFree(hInst, pszPrev);
1001
pszPrev = pszAliasCombo;
}
sts = EssOtlGetUserAttributes(hOutline, hMbr, &iCount, &pUDAList);

printf("User Defined Attributes ::\n");

for(iIndex = 0; iIndex < iCount; iIndex++)
AD_CHK_PRINTF_1("\t(%s)\n", pUDAList[iIndex]);
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_NUMBER, (ESS_PPVOID_T)

&pMemNum);
if (sts)
{
printf("sts=%d ", sts);
}
else
{
printf("Member Number ------------------>(%ld)\n", *pMemNum);
EssFree(hInst, pMemNum);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_DIMNUMBER, (ESS_PPVOID_T)

&pDimNum);
if (sts)
{
}
else
{
printf("Dimension Number ---------------->(%ld)\n", *pDimNum);
EssFree(hInst, pDimNum);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_DIMNAME, (ESS_PPVOID_T)

&pDimName);
if (sts)
{
}
else
{
AD_CHK_PRINTF_1("Dimension Name ------------------>(%s)\n", pDimName);
EssFree(hInst, pDimName);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_ALIASNAME, (ESS_PPVOID_T)

&pAliasName);
if (sts)
{
}
else
{
AD_CHK_PRINTF_1("Alias Name ------------------>(%s)\n", pAliasName);
EssFree(hInst, pAliasName);
}
1002
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_NEXTNAME, (ESS_PPVOID_T)
&pNextName);
if (sts)
{
}
else
{
AD_CHK_PRINTF_1("Next Mbr Name ------------------>(%s)\n", pNextName);
EssFree(hInst, pNextName);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_PREVNAME, (ESS_PPVOID_T)

&pPrevName);
if (sts)
{
}
else
{
AD_CHK_PRINTF_1("Prev Mbr Name ------------------>(%s)\n", pPrevName);
EssFree(hInst, pPrevName);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_PARENTNAME, (ESS_PPVOID_T)

&pParentName);
if (sts)
{
}
else
{
AD_CHK_PRINTF_1("Parent MbrName ------------------>(%s)\n", pParentName);
EssFree(hInst, pParentName);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_CHILDNAME, (ESS_PPVOID_T)

&pChildName);
if (sts)
{
}
else
{
AD_CHK_PRINTF_1("Child Mbr Name ------------------>(%s)\n", pChildName);
EssFree(hInst, pChildName);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_CURRENCYCONVDB,

(ESS_PPVOID_T) &pCurrConv);
if (sts)
{
printf("sts=%d ", sts); printf("Curr Conv Type ------------------>\n");
}
else
{
1003
AD_CHK_PRINTF_1("Curr Conv Type ------------------>(%ld)\n", *pCurrConv);
EssFree(hInst, pCurrConv);
}
sts = EssOtlGetMemberField(hOutline, hMbr, ESS_OTLQRYMBR_STATUS, (ESS_PPVOID_T)

&pStatus);
if (sts)
{ printf("sts=%d ", sts); printf("Status ------------------>\n"); }
else
{
printf("Status ------------------>(%hd)\n", *pStatus);
EssFree(hInst, pStatus);
}
EssFree(hInst, pMbrInfo);
EssFree(hInst, pszLastFormula);
EssFree(hInst, pszCommentEx);
EssFree(hInst, pszAlias);
EssFree(hInst, pszAliasCombo);
return;
Error:
printf("******************* Error *************************");
}
int TestCode_EssOtlQueryMembersEx(ESS_HCTX_T hCtx,

ESS_HINST_T hInst)
{
ESS_HMEMBER_T hMember = 0;
ESS_ULONG_T i;
unsigned long MaxCount = -1;
ESS_STR_T member_fields;
ESS_STR_T member_selection;
/* query string to get level numbers of all markets members */

member_fields = "<SelectMbrInfo ( MemberName, MemberLevel,Consolidation,
MemberFormula ) ";
member_selection = "@ichild(Product), @ichild(Market)";
Object.hCtx = hCtx;
Object.AppName = "Basic";
Object.DbName = "Demo";
Object.FileName = "Demo";

if (sts) goto exit;
if(!sts)
{
ESS_POTLQUERYERRORLIST_T pqryErrorList;
1004
sts = EssOtlQueryMembersEx(hOutline, member_fields, member_selection, &MaxCount,
&phMemberArray, &pqryErrorList);
if (sts) goto exit;
if (phMemberArray)
for (i = 0; i< MaxCount; i++)
PrintResult(hOutline, phMemberArray[i]);
}
if(MaxCount && phMemberArray)

{
sts = EssOtlFreeMembers(hOutline, MaxCount, phMemberArray);
if (sts)
printf("EssOtlFreeMembers sts = %d\n",sts);
}
exit:
return sts;
}
Return to EssOtlQueryMembersEx or EssOtlGetMemberField.
1005
1006
Part IV
C Grid API
In C Grid API:
l Using the C Grid API

l C Grid API Declarations
l C Grid API Function Reference
l C Grid API Examples
l C Grid API Error Codes
1007
1008
Using the C Grid API
13
In This Chapter
General Information on the C Grid API ............................................................... 1009
Overview of C Grid API Architecture .................................................................. 1010
C Grid API Supported Platforms and Compilers..................................................... 1010
Files to Include in C Grid API Programs .............................................................. 1011
C Grid API Initialization and Setup ................................................................... 1011
C Grid API Memory Management..................................................................... 1011
C Grid API Versioning .................................................................................. 1011
Using the C Grid API Functions ....................................................................... 1012
Using the C Main API Functions ...................................................................... 1012
C Grid API Coordinate Systems ....................................................................... 1013
General Information on the C Grid API

Use the Essbase Application Programming Interface (API) to create custom interfaces to Essbase
Server.
The Grid API functions interact with the Essbase Server in a grid paradigm. Use the Grid API
functions to extract data from an Essbase database in order to display the data in a grid-based
reporting interface or a chart.
The Grid API functions contain all the functionality of Smart View and other automated grid
tools. These functions include querying, drill-down, keep-only, and pivots. The Grid API can
also launch report specifications and display the resulting data in grid form.
The Essbase Grid API offers significant advantages for developers currently building reporting
applications using the Essbase API and report script commands. Some of the benefits are as
follows:
l The Grid API is optimized for grid-based data retrieval. It is significantly faster than report
script retrieval, providing improved query performance for your application.
l The Grid API makes it easy to add robust interactive update capabilities to your existing
applications. Coupled with the intelligent calculator in Essbase, the Grid API has the
potential to provide tremendous additional functionality with relatively little effort on your
part.
1009
l With the Grid API programs do not need to parse the returned data from Essbase. The Grid
API automatically places it in a two dimensional binary form that informs you of the type
and value of each individual cell member.
l Most Oracle Smart View for Office commands, such as Zoom In, Zoom Out, Pivot, and so
on, are available through the Grid API. You can build custom user interfaces using your
own or third-party grid controls.
l The Grid API also provides access to member attributes, such as Shared (implicit or explicit),
Parent, or Child. You can customize the look and feel of Essbase data using these attributes.
Overview of C Grid API Architecture

The Essbase Grid API functions use a common grid layer to communicate with the Essbase
Server.
The Grid API functions perform their actions on a grid. The result of any action is also a grid.
It is the responsibility of the caller to supply the Grid API functions with the two-dimensional
data for each call, and to render any returned data. It is also the responsibility of the caller to
handle notifications, such as an error message dialog box, in a manner that ensures that the API
application’s connection does not time out.
C Grid API Supported Platforms and Compilers

For a list of platforms on which the Essbase API is supported, see the Oracle Enterprise
Performance Management System Certification Matrix. For a list of specific compiler releases
which are supported by the Essbase API, see “Supported Compilers” on page 27.
Function names and parameter order are the same for all platforms. However, you must link
different files for each platform. See “API Libraries” on page 40.
l If you are using an integrated C development environment, such as Microsoft Visual C++,
you should check the compiler and linker options carefully to ensure that the Essbase API
will work correctly. In particular, you must ensure that structure fields are one byte-aligned,
and that the correct libraries are used (using the large memory model on Intel X86
platforms). In addition, don't forget to include the appropriate Essbase API library in your
link process. See “API Libraries” on page 40.
l You must compile all Essbase API functions using single-byte structure alignment. If you
are using a Microsoft compiler, you can use a pragma:
#pragma pack(push, id, 1)
#include "essgapi.h"
#pragma pack(pop, id)
1010
Files to Include in C Grid API Programs
In order to use the Essbase API functions in your program, you must include the file that contains
Essbase API definitions.
To use the Grid API functions in your C program, you must include the Grid API header
definitions file (ESSGAPI.H) in the appropriate source modules. If, in addition to Grid API
functions, you are using regular API functions, you must also include the Main API definitions
file (ESSAPI.H) in the appropriate source modules.
Always include these definition files after any C run-time library header files. If you are
programming in the Windows environment, place ESSGAPI.H, and optionally ESSAPI.H, after
the Windows include file WINDOWS.H.
C Grid API Initialization and Setup

When you use Grid API functions, you must call the initialization function, EssGInit. This
function performs the following tasks:
l Passes information about your environment to the Grid API functions.
l Provides you with an instance handle that you use for future communication with the Grid
API functions.
Notes:
l When you call EssGInit, you get the Grid instance handle. If you want to use regular API
functions, you can use EssGGetAPIInstance to get the API instance handle and
EssGGetAPIContext to get the login context handle. See “Using the C Main API
l You cannot use Main API instance handles and login contexts in Grid API calls. See “Using
the C Main API Functions” on page 1012.
C Grid API Memory Management

You must free any memory you allocate and any memory allocated by Grid API functions for
your use. There are Grid API functions that free memory where necessary.
C Grid API Versioning

When you use EssGInit to initialize the API, you need to pass in the version number of the
API libraries that you used to compile the application. This allows older applications to use new
versions of the Grid API DLL and CSL DLL without your having to redistribute the applications.
A Grid API function reports the current release of the Grid API. You do not need to do any
initialization before you make this call.
1011
Using the C Grid API Functions
Many of the operations require a call to begin the operation. Other calls need to be made to
complete the operation and retrieve data. The following list shows the order in which you should
make these operational calls:
1. Call EssGBeginXxx to begin the operation.
2. Call EssGSendRows to send the rows. You can call this multiple times to send more data.
3. Call EssGPerformOperation to tell the API that all information has been passed in.
4. Call EssGGetResults to return information on the number of rows and columns that will
be returned.
5. Call EssGetRows until all data is retrieved.
6. Call EssGEndOperation to clean up any internal resources.
7. Optionally call EssGCancelOperation at any stage of this process to cancel the operation.
After EssGEndOperation, EssGCancelOperation, or another EssGBeginXxxx operation is

called, all information from the previous operation is lost.
Using the C Main API Functions

The Grid API functions are specific to the grid paradigm, and do not replace any of the
functionality of the main Essbase API functions. Because of this operational separation, cases
can arise where it is necessary to call Main API functions from within a Grid API program.
To call the Main API you need two pieces of information:
l Essbase instance handle
l Valid login context
If you have not called EssGConnect and EssGNewGrid, but have called EssGInit, you can get
the Essbase instance handle by calling EssGGetAPIInstance. This gives you access to the memory
calls EssAlloc, EssFree, EssRealloc, and to the login calls EssLogin and EssAutoLogin.
After you have a valid grid handle and have connected, you can call EssGGetAPIContext to get
a valid login context. You can then use this login context handle with any Essbase function that
takes a login context handle. Be careful NOT to use the login context from the Grid API in any
Essbase API functions that would change the login context. The functions that change the login
context are EssLogin, EssAutoLogin, EssSetActive, and EssClearActive.
Handles and login contexts acquired through the main Essbase API cannot be used in the Grid
API calls. If you want to use both the main Essbase API and the Grid API, you need to initialize
and connect through the Grid API and use the handles and login contexts from the Grid API
for the other Essbase functions.
1012
C Grid API Coordinate Systems
Assume a zero-based column and row numbering scheme in the range structure that you pass
into functions that expect a two dimensional array of data. The input and output data ranges
will be in the same relative coordinate system, while the data arrays are always zero-based.
For example, assume that your first data cell is in the third row and fourth column, and you
have three rows of five columns each. If you pass in the structure ESSG_RANGE_T, it would
contain ulStartRow = 2, ulStartColumn = 3, ulNumRows = 3, and ulNumColumns = 5.
The two-dimensional array of ESSG_DATA_T items would start at index [0][0] and end at index
[2][4].
1013
1014
C Grid API Declarations
14
In This Chapter
C Grid API Constants .................................................................................. 1015
C Grid API Data Types ................................................................................. 1022
C Grid API Structures .................................................................................. 1024
C Grid API Constants

The following constants are defined in the Essbase Grid API.
Returned on successful API call.
Constant Definition
ESSG_STS_NOERR 0
Defines the version of the EGAPI API. Changes each time the API is modified.
Constant Definition
ESSG_VERSION 0x00040000
Define the maximum number of rows and columns supported
Constant Definition
WINDOWS
ESSG_MAXROWS 0xFFFFFFFF / sizeof(ESSG_PDATA_T)
ESSG_MAXCOLUMNS 0xFFFFFFFF / sizeof(ESSG_DATA_T)
OTHER
ESSG_MAXROWS 0xFFFF / sizeof(ESSG_PDATA_T)
ESSG_MAXCOLUMNS 0xFFFF / sizeof(ESSG_DATA_T)
Used by the pAttributes member of the “ESSG_DATA_T” on page 1024 structure.
1015
Constant Definition
ESSG_CA_READONLY 0x00000001
ESSG_CA_READWRITE 0x00000002
ESSG_CA_LINKEDOBJ 0x00000004
ESSG_CA_LINKPARTITION 0x00000008
ESSG_CA_LINKCELLNOTE 0x00000010
ESSG_CA_LINKWINAPP 0x00000020
ESSG_CA_LINKURL 0x00000040
ESSG_CA_AISDT 0x00000080
ESSG_CA_GLDT 0X00000400
Used for the pAttributes for members in the “ESSG_DATA_T” on page 1024 structure.
Constant Definition
ESSG_MA_DIMTOP 0x00000001
ESSG_MA_ZOOMINABLE 0x00000002
ESSG_MA_NEVERSHARE 0x00000004
ESSG_MA_LABELONLY 0x00000008
ESSG_MA_STOREDATA 0x00000010
ESSG_MA_EXPSHARE 0x00000020
ESSG_MA_IMPSHARE 0x00000040
ESSG_MA_DYNCALC 0x00000080
ESSG_MA_FORMULA 0x00000100
ESSG_MA_ATTRIBUTE 0x00000200
ESSG_MA_DIMNUMBITS 0xF8000000 (the last 5 bits contain the dimension number)
Used by the usType member in the “ESSG_DATA_T” on page 1024 structure.
Constant Definition
ESSG_DT_UNUSED 0
ESSG_DT_STRING 1
ESSG_DT_LONG 2
1016
Constant Definition
ESSG_DT_DOUBLE 3
ESSG_DT_BLANK 4
ESSG_DT_RESERVED 5
ESSG_DT_ERROR 6
ESSG_DT_MISSING 7
ESSG_DT_ZERO 8
ESSG_DT_NOACCESS 9
ESSG_DT_MEMBER 10
ESSG_DT_FORMULA 11
ESSG_DT_ZEROwFORMULA 12
ESSG_DT_DOUBLEwFORMULA 13
ESSG_DT_BLANKwFORMULA 14
ESSG_DT_STRINGwFORMULA 15
ESSG_DT_MISSINGwFORMULA 16
ESSG_DT_NOACCESSwFORMULA 17
ESSG_DT_STRINGEX 18
ESSG_DT_MEMBEREX 19
ESSG_DT_STRINGEXwFORMULA 20
ESSG_DT_FORMULAEX 21
ESSG_DT_MEMBERwKEY (see “ESSG_DT_MEMBERwKEY Example” on page 1127) 23
ESSG_DT_SMARTLIST 24
ESSG_DT_MNGLESS 25
ESSG_DT_DATE 26
Note: When the usType field of the ESSG_DATA_T structure is set to

ESSG_DT_MEMBERwKEY, the pszStr field of Value(ESSG_DATA_VALUE) field is
interpreted as follows: <length of member name><the member-name><length of
key><the key> where the length elements are 2 bytes in size. Note that <the member-
name> is null-terminated.
Used by the ulOptions parameter of EssGBeginRetrieve
1017
Constant Definition
ESSG_RET_RETRIEVE 0
ESSG_RET_RETRIEVELOCK 1
ESSG_RET_LOCKONLY 2
Used by the ulOptions parameter of EssGBeginUpdate
Constant Definition
ESSG_RET_REQUIRELOCK 0
ESSG_RET_LOCKIFNEEDED 1
This bitmask contant is used by the ulOptions parameter of EssGBeginConditionalRetrieve,

EssGBeginConditionalZoomIn, EssGBeginReport, and EssGBeginReportFile
Constant Definition
ESSG_NOATTRIBUTES 0x00001000
These bitmask constants are used by the ulOptions parameter of EssGBeginZoomIn and
EssGBeginConditionalZoomIn
Constant Definition
ESSG_ZOOM_DOWN 0x00000080
ESSG_ZOOM_ACROSS 0x00000100
Describe the connect options
Constant Definition
ESSG_CONNECT_DEFAULT 0
ESSG_CONNECT_NODIALOG 1
Describe the various zoom levels
Constant Definition
ESSG_OPTIONS 0
ESSG_NEXTLEVEL 1
ESSG_ALLLEVELS 2
ESSG_BOTTOMLEVEL 3
1018
Constant Definition
ESSG_SIBLEVEL 4
ESSG_SAMELEVEL 5
ESSG_SAMEGENERATION 6
ESSG_CALCLEVEL 7
ESSG_PARENTLEVEL 8
ESSG_TOPLEVEL 9
Used for setting and retrieving grid options
Constant Definition
ESSG_OP_DRILLLEVEL 1
ESSG_OP_INCSEL 2
ESSG_OP_SELONLY 3
ESSG_OP_SELGROUP 4
ESSG_OP_INDENT 5
ESSG_OP_SUPMISSING 6
ESSG_OP_SUPZEROS 7
ESSG_OP_SUPUNDER 8
ESSG_OP_UPDATEMODE 9
ESSG_OP_ALIASNAMES 10
ESSG_OP_ALIASTABLE 11
ESSG_OP_USERGRIDDATA 12
ESSG_OP_RETAINTHREAD 20
ESSG_OP_EMPTYGRIDERROR 21
ESSG_OP_DRILLONLEAF 22
ESSG_OP_DATALESS 23
ESSG_OP_UNIQUENAMEONLY 32
ESSG_OP_MEMBERANDUNIQUENAME (see “ESSG_OP_MEMBERANDUNIQUENAME 33

Example” on page 1125)
1019
Constant Definition
ESSG_OP_GET_ME_CELLS 36
Return #ME (meaningless) value for cells

with no base member-attribute combination
Default: off
ESSG_OP_GET_FORMATTED_VALUE 38
Include formatting values for formatted cells

Default: Return only cell values
ESSG_OP_GET_VALUE 39
Requests original values for cells with non-

numeric types
Default: on
ESSG_OP_GET_FORMATTED_MISSING 40
Include formatting values for cells with

missing values
Default: off
ESSG_OP_GET_DRILLTHRU_URLS 41
Populates the drill through flag for cells
Describe the various indent styles
Constant Definition
ESSG_INDENTNONE 1
ESSG_INDENTSUBITEMS 2
ESSG_INDENTTOTALS 3
Used by get results calls to determine the process state
Constant Definition
ESSG_STATE_DONE 1
ESSG_STATE_INPROGRESS 2
Buffer length constants (including terminating null)
Constant Definition
ESSG_USERNAMELEN 31
ESSG_PASSWORDLEN 101
1020
Constant Definition
ESSG_SERVERLEN 31
ESSG_APPLICATIONLEN 9
ESSG_DATABASELEN 9
Constants used by Grid API Drill-Through functions (EssGDTxxx())
Constant Definition
ESSG_DESCRIPTION_LEN Maximum buffer length (255) used for report data
ESSG_DTINPUTOPTION_PROMPT_HISNAME uInputOption value in ESSG_DTINFO_T, meaning that users have all the default values
needed to connect to Essbase Studio and start a drill-through session
ESSG_DTINPUTOPTION_PROMPT_LOGIN uInputOption value in ESSG_DTINFO_T, meaning that users must set the password to
connect to Essbase Studio and start a drill-through session
ESSG_DTREPORT_NAME Maximum string length (80) used for drill-through
ESSG_ERR_INVALIDDTHANDLE Error message constant returned if the given drill-through instance handle is invalid
ESSG_ERR_NODTREPORTS Error message constant returned if no drill-through report is defined for the given drill-
through instance handle
ESSG_FIELDLEN Maximum string length (30) used for drill-through
ESSG_HISDT Value (5) used for drill-through entry
Used by LRO API calls in the structure ESSG_LRODESC_T
Constant Definition
ESSG_PARTITIONTYPE 1
ESSG_CELLNOTETYPE 2
ESSG_WINAPPTYPE 3
ESSG_URLTYPE 4
Grid Perspective Types

Used by EssGGetGridPerspective and EssGSetGridPerspective.
Constant Definition
ESSG_PERSP_EXPLICIT 0
Requires tuple specification
1021
Constant Definition
ESSG_PERSP_REALITY 1
Uses reality context for attribute dimension
Text List (SmartList) Types

Text List (SmartList) attributes.
Constant Definition
ESSG_CA_MISSINGCELL 0x00000100
Set for cells of type SmartList when the cell has a #Missing value. This occurs for SmartList cells where
#Missing values map to text values.
ESSG_CA_OUTOFRANGE 0x00000200
Set when a SmartList-type cell with a numeric value is out of range in the context of that text list
Unicode Mode Types

Used as values for usApiType field of ESSG_INIT_T for Unicode Mode.
ESSG_API_UTF8 0x0003 This value enables Essbase Server to create or migrate Unicode-mode applications.
ESSG_API_NONUNICODE 0x0002 This value disables the creation and migration of Unicode-mode applications on Essbase Server.
C Grid API Data Types

typedef char ESSG_APPLICATION_T[ESSG_APPLICATIONLEN]; ESSG_APPLICATION_T
typedef unsigned char ESSG_BOOL_T; ESSG_BOOL_T
typedef char ESSG_CHAR_T; ESSG_CHAR_T
typedef char ESSG_DATABASE_T[ESSG_DATABASELEN]; ESSG_DATABASE_T
typedef double ESSG_DOUBLE_T; ESSG_DOUBLE_T
typedef ESSG_PVOID_T ESSG_DTHINST_T, *ESSG_PDTHINST_T ESSG_DTHINST_T, ESSG_PDTHINST_T
typedef float ESSG_FLOAT_T; ESSG_FLOAT_T
typedef ESSG_PVOID_T ESSG_HANDLE_T, *ESSG_PHANDLE_T; ESSG_HANDLE_T, ESSG_PHANDLE_T
1022
typedef ESSG_PVOID_T ESSG_HGRID_T,*ESSG_PHGRID_T; ESSG_HGRID_T, ESSG_PHGRID_T
typedef long ESSG_LONG_T; ESSG_LONG_T
typedef char ESSG_PASSWORD_T[ESSG_PASSWORDLEN]; ESSG_PASSWORD_T
typedef char *ESSG_PSTR_T; ESSG_PSTR_T
typedef ESSG_VOID_T *ESSG_PVOID_T; ESSG_PVOID_T
typedef char ESSG_SERVER_T[ESSG_SERVERLEN]; ESSG_SERVER_T
typedef short ESSG_SHORT_T; ESSG_SHORT_T
typedef char *ESSG_STR_T; ESSG_STR_T
typedef long ESSG_STS_T; ESSG_STS_T
typedef unsigned char ESSG_UCHAR_T; ESSG_UCHAR_T
typedef unsigned long ESSG_ULONG_T; ESSG_ULONG_T
typedef char ESSG_USERNAME_T[ESSG_USERNAMELEN]; ESSG_USERNAME_T
typedef unsigned short ESSG_USHORT_T; ESSG_USHORT_T
typedef void ESSG_VOID_T; ESSG_VOID_T
typedef unsigned short ESSG_WORD_T; ESSG_WORD_T
ESSG_PFUNC_T, ESSG_PFUNC_M
These types define the prototype for a user's message callback function.
#ifdef WIN32
#define ESSG_CALLBACK _export
#define ESSG_FUNC_M ESSG_STS_T ESSG_CALLBACK /* for Win32 */
#else
#define ESSG_CALLBACK _export
#define ESSG_FUNC_M ESSG_STS_T ESSG_CALLBACK /* for other platforms */
#endif
#ifdef WIN32
/* function pointer (Win32) */
typedef
ESSG_STS_T (ESSG_CALLBACK *ESSG_PFUNC_T)(ESSG_PVOID_T,ESSG_LONG_T,
SSG_USHORT_T, ESSG_STR_T, ESSG_STR_T);
#else
/* function pointer (other) */
typedef
ESSG_STS_T (ESSG_CALLBACK *ESSG_PFUNC_T)(ESSG_PVOID_T, ESSG_LONG_T,
ESSG_USHORT_T, ESSG_STR_T, ESSG_STR_T);
#endif
1023
C Grid API Structures
This section describes the structures used by the Grid API. Click on one of the structure names
below to navigate to the description.
l “ESSG_CONNECTINFO_T” on page 1024
l “ESSG_DATA_T” on page 1024
l “ESSG_DRILLDATA_T” on page 1027
l “ESSG_DTDATA_T” on page 1027
l “ESSG_DTHEADER_T” on page 1027
l “ESSG_DTINFO_T” on page 1028
l “ESSG_DTREPORT_T” on page 1028
l “ESSG_INIT_T” on page 1029
l “ESSG_LRODESC_T” on page 1029
l “ESSG_LROINFO_T” on page 1030
l “ESSG_RANGE_T” on page 1030
ESSG_CONNECTINFO_T
Contains information about database connection for each linked partition. The fields are
described as follows:
typedef struct ESSG_CONNECTINFO_T
{
ESSG_SERVER_T Server;
ESSG_APPLICATION_T Application;
ESSG_DATABASE_T Database;
ESSG_USERNAME_T Username;
ESSG_PASSWORD_T Password;
} ESSG_CONNECTINFO_T, * ESSG_PCONNECTINFO_T, ** ESSG_PPCONNECTINFO_T;
ESSG_SERVER_T Server Name of the server
ESSG_APPLICATION_T Application Name of the application
ESSG_DATABASE_T DatabaseNNN Name of the Essbase database
ESSG_USERNAME_T Username User's name
ESSG_PASSWORD_T Password User's password
ESSG_DATA_T
Describes the format of the data to be sent and received by the Essbase Grid API. Note that calls
returning this structure will return member names in the Member structure. The caller can pass
1024
in the same structure back to the API using the Member structure instead of the pszStr field if
the type is ESSG_DT_MEMBER.
The ESSG_DATA_T data structure defines each cell sent or returned via the grid API. If this
structure is being returned to the caller, pszStr contains string data and dblData contains numeric
data. Use the usType field to determine whether the cell is a member, a number, or text.
Similarly, if the structure is being passed into the API, pszStr should contain a member name or
text and dblData should contain numeric data. Set the usType field to correspond to the data
type of the cell. If the cell data type is unknown, set it to text (ESSG_DT_STRING), and the
server determines whether it is a member.
typedef struct ESSG_DATA_T
{
ESSG_PVOID_T pAttributes;
ESSG_DATA_VALUE Value;
ESSG_USHORT_T usType;
ESSG_PVOID_T pCellProps;
} ESSG_DATA_T;
ESS_TSA_API_typedef(ESSG_DATA_T *, ESSG_PDATA_T);
ESS_TSA_API_typedef(ESSG_DATA_T **, ESSG_PPDATA_T);
ESSG_PVOID_T pAttributes One of the long integer constants listed below indicating the cell type or member type (OUT)
ESSG_DATA_VALUE_T Value The value of the returned grid string
ESSG_USHORT_T usType One of the tag constants listed below indicating the data type (IN/OUT)
ESSG_PVOID_T pCellProps Stores cell properties; for example, whether or not cell is associated with a drill-through URL
Long Member Names

To send a string that contains more than 255 characters, use ESSG_DT_STRINGEX instead of
ESSG_DT_STRING.
Constants for ESSG_DATA_T

For more information about these constants, see “C Grid API Constants” on page 1015.
The following constants are used by the pAttributes field of the ESSG_DATA_T structure for cell
data types:
ESSG_CA_READONLY
ESSG_CA_READWRITE
ESSG_CA_LINKEDOBJ
ESSG_CA_LINKPARTITION
ESSG_CA_LINKCELLNOTE
ESSG_CA_LINKWINAPP
ESSG_CA_LINKURL
ESSG_CA_AISDT
ESSG_CA_GLDT
1025
The following constants are used by the pAttributes field of the ESSG_DATA_T structure for
member data types:
ESSG_MA_DIMTOP
ESSG_MA_ZOOMINABLE
ESSG_MA_NEVERSHARE
ESSG_MA_LABELONLY
ESSG_MA_STOREDATA
ESSG_MA_EXPSHARE
ESSG_MA_IMPSHARE
ESSG_MA_DYNCALC
ESSG_MA_FORMULA
ESSG_MA_ATTRIBUTE
ESSG_MA_DIMNUMBITS
The following constants are used by the usType field of the ESSG_DATA_T structure:
ESSG_DT_UNUSED
ESSG_DT_STRING
ESSG_DT_LONG
ESSG_DT_DOUBLE
ESSG_DT_BLANK
ESSG_DT_RESERVED
ESSG_DT_ERROR
ESSG_DT_MISSING
ESSG_DT_ZERO
ESSG_DT_NOACCESS
ESSG_DT_MEMBER
ESSG_DT_FORMULA
ESSG_DT_ZEROwFORMULA
ESSG_DT_DOUBLEwFORMULA
ESSG_DT_BLANKwFORMULA
ESSG_DT_STRINGwFORMULA
ESSG_DT_MISSINGwFORMULA
ESSG_DT_NOACCESSwFORMULA
ESSG_DT_STRINGEX
ESSG_DT_MEMBEREX
ESSG_DT_STRINGEXwFORMULA
ESSG_DT_FORMULAEX
ESSG_DT_MEMBERwKEY
The following constants are additional values for the usType field, to work in Unicode mode.
ESSG_DT_STRINGEX 0x0018 This value specifies a string extended for Unicode mode and for long member names.
ESSG_DT_MEMBEREX 0x0019 This value specifies a member name extended for Unicode mode.
ESSG_DT_STRINGEXwFORMULA 0x0020 This value specifies a formula string extended for Unicode mode.
ESSG_DT_FORMULAEX 0x0021 This value specifies a formula extended for Unicode mode.
1026
ESSG_DRILLDATA_T
Contains information associating linked objects with specific cell addresses. The fields are
described as follows:
typedef struct ESSG_DRILLDATA_T
{
ESSG_HLRO_T hLRO;
ESSG_USHORT_T usLinkObjType;
ESSG_LINKOBJDESC Description;
ESSG_PSTR_T pMbrCombos;
ESSG_ULONG_T ulNumMbrCombos;
} ESSG_DRILLDATA_T, * ESSG_PDRILLDATA_T, ** ESSG_PPDRILLDATA_T;
ESSG_HLRO_T hLRO A unique handle to a linked object
ESSG_USHORT_T usLinkObjType Object type
ESSG_LINKOBJDESC Description)OOo Object description
ESSG_PSTR_T pMbrCombos An array of member names
ESSG_ULONG_T ulNumMbrCombos Number of member names in pMbrCombos
ESSG_DTDATA_T
typedef struct ESSG_DTDATA_T
{
ESSG_ULONG_T row;
ESSG_ULONG_T column;
ESSG_CHAR_T data[ESSG_DESCRIPTION_LEN + 1];
} ESSG_DTDATA_T, *ESSG_PDTDATA_T, **ESSG_PPDTDATA_T;
ESSG_ULONG_T row 0-indexed row number for the given data block
ESSG_ULONG_T column 0-indexed column number for the given data block
ESSG_CHAR_T data [ESSG_DESCRIPTION_LEN + 1] Data value for the given data block
ESSG_DTHEADER_T
typedef struct ESSG_DTHEADER_T
{
ESSG_ULONG_T colIndex;
ESSG_CHAR_T viewName[ESSG_DESCLEN + 1];
ESSG_CHAR_T data[ESSG_DESCLEN + 1];
1027
ESSGDTREPORTDATATYPE dataType;
} ESSG_DTHEADER_T, *ESSG_PDTHEADER_T, **ESSG_PPDTHEADER_T;
ESSG_ULONG_T colIndex 0-based index of the column position
ESSG_CHAR_T viewName[ESSG_DESCLEN_+ 1]
ESSG_CHAR_T data[ESSG_DESCLEN_+ 1] Heading text for the given column of data
ESSGDTREPORTDATATYPE dataType One of the constants listed below indicating the data type of the given
column of data
Constants for ESSG_DTHEADER_T

The following constants are used by thedataType field of the ESSG_DTHEADER_T structure:
ESSGDTINT
ESSGDTFLOAT
ESSGDTSTRING
ESSG_DTINFO_T
Defines the connection information for a range of data cells.
typedef struct ESSG_DTINFO_T
{
ESSG_CHAR_T hisName[ESSG_FIELDLEN + 1];
ESSG_CHAR_T dataSource[ESSG_FIELDLEN + 1];
ESSG_CHAR_T username[ESSG_FIELDLEN + 1];
ESSG_CHAR_T password[ESSG_FIELDLEN + 1];
ESSG_USHORT_T inputOption;
} ESSG_DTINFO_T, *ESSG_PDTINFO_T, **ESSG_PPDTINFO_T;
ESSG_CHAR_T hisName [ESSG_FIELDLEN + 1]
ESSG_CHAR_T dataSource [ESSG_FIELDLEN + 1] (read only)
ESSG_CHAR_T username [ESSG_FIELDLEN + 1]
ESSG_CHAR_T password [ESSG_FIELDLEN + 1] (write only)
ESSG_USHORT_T inputOption (read only)
ESSG_DTREPORT_T
Defines a report definition.
typedef struct ESSG_DTREPORT_T
{
ESSG_LONG_T reportId;
1028
ESSG_CHAR_T name[ESSG_DESCLEN + 1];
ESSG_LONG_T customize;
ESSG_LONG_T rowGoverner;
ESSG_LONG_T timeGoverner;
} ESSG_DTREPORT_T, *ESSG_PDTREPORT_T, **ESSG_PPDTREPORT_T;
ESSG_LONG_T reportId
ESSG_CHAR_T name [ESSG_DESCLEN + 1]
ESSG_LONG_T customize
ESSG_LONG_T rowGoverner
ESSG_LONG_T timeGoverner
ESSG_INIT_T
Describes the information to be passed into the call to EssGInit.
typedef struct
{
ESSG_ULONG_T ulVersion;
ESSG_ULONG_T ulMaxRows;
ESSG_ULONG_T ulMaxColumns;
ESSG_PFUNC_T pfnMessageFunc;
ESSG_PVOID_T pUserdata;
ESSG_USHORT_T usApiType;
} ESSG_INIT_T, *ESSG_PINIT_T;
ESSG_ULONG_T ulVersion This should be set to ESSG_VERSION
ESSG_ULONG_T ulMaxRows Maximum number of rows for the grid

Limit: 65535 rows
ESSG_ULONG_T ulMaxColumns Maximum number of columns for the grid

Limit: 256 columns
ESSG_PFUNC_T pfnMessageFunc Pointer to the user-defined message callback function
ESSG_PVOID_T pUserdata Pointer to user data passed to message callback
ESSG_UGSHORT_T usApiType Encoding type of the Grid API. For valid values, see “Unicode Mode Types” on page 1022.
ESSG_LRODESC_T
Contains information describing a specific object linked to a data cell in an Essbase database.
The fields are described as follows:
1029
typedef struct ESSG_LRODESC_T
{
ESSG_USHORT_T usLinkObjType;
ESSG_USERNAME_T Username;
ESSG_TIME_T LastUpdate;
union
{
ESSG_LROINFO_T lroInfo;
ESSG_CHAR_T Note[ESSG_LRONOTELEN];
} lro;
} ESSG_LRODESC_T, *ESSG_LPLRODESC_T;
ESSG_ULONG_T usLinkObjType Object type
ESSG_USERNAME_T userName Name of the last user to modify the object
ESSG_TIME_T LastUpdate Last date the object was modified

ESSG_TIME_T is defined as an unsigned long
ESSG_LROINFO_T lroInfo LRO information structure, associated by union
ESSG_CHAR_T Note[ESSG_LRONOTELEN] A cell note, associated by union

The default note length specified by ESSG_LRONOTELEN is 599.
ESSG_LROINFO_T
Contains information about a specific object linked to a data cell in an Essbase database. The
fields are described as follows:
typedef struct ESSG_LROINFO_T
{
ESSG_CHAR_T ObjName[ESSG_ONAMELEN];
ESSG_CHAR_T Desc[ESS_DESCLEN];
} ESSG_LROINFO_T, *ESSG_LPLROINFO_T;
ESSG_ objName[ESSG_ Source file name of object linked to a data cell

CHAR_T ONAMELEN]
ESSG_ONAMELEN specifies the maximum length of an object name; the default value is 511.
ESSG_ Desc[ESS_DESCLEN] Description of an object linked to a data cell

CHAR_T
ESS_DESCLEN specifies the maximum length of the description; the default value is 79.
ESSG_RANGE_T
Describes the extent of the data being sent or received.
typedef struct
{
ESSG_ULONG_T ulRowStart;
1030
ESSG_ULONG_T ulColumnStart;
ESSG_ULONG_T ulNumRows;
ESSG_ULONG_T ulNumColumns;
} ESSG_RANGE_T, *ESSG_PRANGE_T;
ESSG_ULONG_T ulRowStart First Row in the report (zero based)
ESSG_ULONG_T ulColumnStart First Column in the report (zero based)
ESSG_ULONG_T ulNumRows Number of rows in the report (maximum 16370)
ESSG_ULONG_T ulNumColumns Number of columns in the report (maximum 256)
1031
1032
C Grid API Function Reference
15
Consult the Contents pane for the alphabetical list of C Grid API functions, which are prefaced
with EssG.
EssGBeginConditionalRetrieve
Begins a conditional retrieval operation.
Syntax
ESSG_FUNC_M EssGBeginConditionalRetrieve (hGrid, pszConditions,
ulOptions);
hGrid ESSG_HGRID_T Handle passed back from EssGNewGrid.
pszConditions ESSG_STR_T String (no greater than 64K) containing Essbase report specification commands
relating to the conditions for the retrieval. Do not use Report Writer member/alias/
unique name handling formatting commands for the pszConditions parameter. Use
the options available in the EssGSetGridOption function.
ulOptions ESSG_ULONG_T A constant which describes the type of retrieval. One of the following values must
be used:
l ESSG_RET_RETRIEVE Retrieve Only
l ESSG_RET_RETRIEVELOCK Retrieve and Lock
l ESSG_RET_LOCKONLY Lock Only (No data is to be retrieved)
The following value may be added into ulOptions using bitwise OR (|):
ESSG_NOATTRIBUTES returns grid without pAttributes values.
Notes
l Conditions, as defined in a partial report specification, are applied to the provided grid.
l Attributes for returned cell values are obtained using a second server request. Passing
ESSG_NOATTRIBUTES in the ulOptions parameter will issue one less request of the server,
and could, in large resulting grids, be faster.
l In case of Type-enabled applications, such as applications with SmartList, Date, or Format
strings, you will get textual encoded data but without type information if you specify
ESSG_NOATTRIBUTES. Type information works like member attributes, so do not use
ESSG_NOATTRIBUTES if type information is required.
1033
Return Value
If successful, returns ESSG_STS_NOERR.
Access
None.
Example
ESSG_VOID_T ESSG_BeginConditionalRetrieve(ESSG_HGRID_T hGrid)
{
ESSG_STS_T sts = ESS_STS_NOERR;
ESSG_PPDATA_T ppDataIn;
ESSG_PPDATA_T ppDataOut;
ESSG_RANGE_T rDataRangeIn, rDataRangeOut;
ESSG_ULONG_T ulOptions;
ESSG_USHORT_T usState;
ESSG_STR_T pszConditions;
/* connect the grid to a database on the server */

sts = EssGConnect(hGrid, "Rainbow", "Admin",
"Password", "Demo", "Basic", ESSG_CONNECT_DEFAULT);
if(sts == 0)
{
ppDataIn = BuildTable(&rDataRangeIn);
ulOptions = ESSG_RET_RETRIEVE;
pszConditions = "<TOP(Scenario,3,@Datacol(3))";
/* start the conditional retrieve operation */
sts = EssGBeginConditionalRetrieve(hGrid,
pszConditions, ulOptions);
}
if(sts == 0)
{
/* send the entire grid to define the query */
sts = EssGSendRows(hGrid, &rDataRangeIn, pDataIn);
}
if(sts == 0)
{
/* perform the retrieval */
sts = EssGPerformOperation(hGrid, 0);
/* free the built data */

FreeTwoDim(ppDataIn, rDataRangeIn.ulNumRows);
}
if(sts == 0)
{
/* determine the results of the retrieve */
sts = EssGGetResults(hGrid, 0, &rDataRangeOut,
&usState);
}
if(sts ==0)
{
/* get all the data */
1034
sts = EssGGetRows(hGrid, 0, &rDataRangeOut,
&rDataRangeOut, &ppDataOut);
}
if(sts == 0)
{
/* display the results */
DisplayOutput(ppDataOut, rDataRangeOut);
/* free the returned data */
EssGFreeRows(hGrid, &rDataRangeOut, ppDataOut);
}
if(!sts)
{
EssGEndOperation(hGrid, 0);
EssGDisconnect(hGrid, 0);
}
}
See Also
l “Using the C Grid API Functions” on page 1012
l “C Grid API Structures” on page 1024
EssGBeginConditionalZoomIn
Begins a conditional zoom-in.
Syntax
ESSG_FUNC_M EssGBeginConditionalZoomIn (hGrid, pZoomCell,
pszConditions, ulOptions);
pZoomCell “ESSG_RANGE_T” Describes the cell to be zoomed in upon. This must be a single cell for
on page 1030 conditional zoomin.
pszConditions ESSG_STR_T String (no greater than 64K) containing Essbase report specification
commands relating to the conditions for the zoom-in.
Do not use Report Writer member/alias/unique name handling formatting
commands for the pszConditions parameter. Use the options available in
EssGSetGridOption.
1035
ulOptions ESSG_ULONG_T A bitmask which describes the type of zoom-in (across or down). The following
two values are mutually exclusive:
l ESSG_ZOOM_DOWN Any page/title dimensions selected will be
zoomed down
l ESSG_ZOOM_ACROSS Any page dimensions selected will be zoomed
across
The following option may be added into ulOptions using bitwise OR (|):
Notes
l The cell to be zoomed in upon is described by single range, the conditions to be applied are
passed as a string containing Essbase report specification commands.
ESSG_NOATTRIBUTES for the ulOptions parameter will issue one less request of the server,
l Conditional zoom-in will only work on one zoom cell at a time.
l There are only three valid zoom levels when doing a conditional ZoomIn -
ESSG_NEXTLEVEL, ESSG_BOTTOMLEVEL or ESSG_ALLLEVELS. The Zoom level for
conditional ZoomIn must be set via EssGSetGridOption to one of the three valid levels. If
a non-valid level is set when performing a conditional ZoomIn the API will default to
ESSG_NEXTLEVEL.
l If the zoom level is ESSG_BOTTOMLEVEL the resulting members are selected based on
the conditions from all Level zero members in the dimension being zoomed on. For example,
if the zoom cell contains East, from the Market dimension, and the zoom level is
ESS_BOTTOMLEVEL, the resulting members could be any of the leaf members of Market,
not just descendents of East.
l In case of Type-enabled applications, such as applications with SmartList, Date, or Format
strings, you will get textual encoded data but without type information if you specify
ESSG_NOATTRIBUTES. Type information works like member attributes, so do not use
ESSG_NOATTRIBUTES if type information is required.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginConditionalZoomIn(ESSG_HGRID_T hGrid)
{
ESSG_FUNC_M sts = ESS_STS_NOERR;
1036
ESSG_RANGE_T pZoomCells;
ESSG_STR_T pszConditions;

if(sts == 0)
{
ulOptions = ESSG_ZOOM_DOWN | ESSG_ALLLEVELS;
pZoomCells.ulRowStart = 0;
pZoomCells.ulColumnStart = 2;
pZoomCells.ulNumRows = 1;
pZoomCells.ulNumColumns = 1;
pszConditions = "<TOP("Scenario",3,@Datacol(3))";
/* start the conditional zoom-in operation */

sts = EssGBeginConditionalZoomIn(hGrid,
&pZoomCells, pszConditions, ulOptions);
}
if(sts == 0)
{
sts = EssGSendRows(hGrid, &rDataRangeIn,
ppDataIn);
}
if(sts == 0)
{
/* perform the conditional zoom-in */
/* Free the built data */

}
if(sts == 0)
{
/* determine the results of conditional zoom-in */
sts = EssGGetResults(hGrid, 0, &rDataRangeOut, &usState);
}
if(sts ==0)
{
}
if(sts == 0)
{
1037
}
if(sts == 0)
{
}
See Also
EssGBeginCreateLRO
Begins the operation of creating a linked object for a data cell in an Essbase database.
Syntax
ESSG_FUNC_M EssGBeginCreateLRO (hGrid, usCells, pCells, pLroDesc,
ulOption);
hGrid; ESSG_HGRID_T Grid handle returned by EssGNewGrid().
usCells; ESSG_USHORT_T The number of cell ranges specified in pCells.
pCells; “ESSG_RANGE_T” on page Array of cell ranges for which to create the link.
1030
pLroDesc; “ESSG_LRODESC_T” on LRO description information for the new object.

page 1029
ulOption; ESSG_ULONG_T Option specifying whether to store the object on the server. Use
ESS_STORE_OBJECT_API to store winapp and URL objects on the server.
Use ESS_NOSTORE_OBJECT_API to store cell notes off the server (and in
the index file).
Return Value
See Also
l EssGBeginDeleteLROs
l EssGBeginDrillOrLink
l EssGDeleteLRO
l EssGFreeCellLinkResults
1038
l EssGGetCellLinkResults
l EssGGetLRODesc
l EssGGetLRO
l EssGUpdateLRO
EssGBeginDataPoint
Begins a data point operation.
Syntax
ESSG_FUNC_M EssGBeginDataPoint (hGrid, ulRow, ulColumn, ulOptions);
ulRow ESSG_ULONG_T Row of the data point.
ulColumn ESSG_ULONG_T Column of the data point.
ulOptions ESSG_ULONG_T Reserved for future use. Should be set to zero.
Notes
l This function returns one member from each dimension describing the combination of
members for a particular cell in the grid.
l The caller should pass in (EssGSendRows) enough information for Essbase to determine
the members for the cell. It is safest to pass in all rows less than or equal to the ulRow
parameter and all columns. The ulRow and ulColumn values are zero-based.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginDataPoint(ESSG_HGRID_T hGrid)
{
ESSG_ULONG_T ulRow;
ESSG_ULONG_T ulColumn;
ESSG_RANGE_T rDataRangeIn;
ESSG_ULONG_T ulMembers, i;
ESSG_PSTR_T ppszMembers;
1039
if(sts == 0)
{
ulRow = 1;
ulColumn = 2;
ulOptions = 0;
/* start the data point operation */

sts = EssGBeginDataPoint(hGrid, ulRow, ulColumn, ulOptions);
}
if(sts == 0)
{
ppDataIn);
}
if(sts == 0)
{
/* perform the data point operation */

}
if(sts == 0)
{
/* determine the results of the data point operation */
sts = EssGGetDataPointResults(hGrid, &ulMembers,
&ppszMembers, &usState);
}
if(!sts && ulMembers)

{
printf("\nMembers:");
for (i = 0; i<ulMembers; i++)
printf("\n\t%s", ppszMembers[i]);
EssGFreeMemberInfo(hGrid, ulMembers, ppszMembers);

}
if(!sts)
{
}
}
See Also
1040
EssGBeginDeleteLROs
Begins the operation of deleting all objects linked to a data cell in an Essbase database.
Syntax
ESSG_FUNC_M EssGBeginDeleteLROs (hGrid, usCells, pCells);
usCells; ESSG_USHORT_T The number of cell ranges specified in pCells.
pCells; “ESSG_RANGE_T” on page 1030 Array of cell ranges for which to delete linked objects.
Notes
To delete a single LRO use EssGDeleteLRO.
Return Value
See Also
l EssGBeginCreateLRO
l EssGDeleteLRO
l EssGGetLRODesc
l EssGGetLRO
l EssGUpdateLRO
EssGBeginDrillAcross
Begins a drill-across to retrieve cells from a linked partition.
Syntax
ESSG_FUNC_M EssGBeginDrillAcross (hGrid, hDAGrid, hLRO, usCells,
pDrillCells, usOption);
hGrid; ESSG_HGRID_T Handle of the original grid returned by EssGNewGrid().
hDAGrid; ESSG_HGRID_T Handle of new grid to receive drill results.
hLRO; ESSG_HLRO_T Handle of the linked partition.
usCells; ESSG_USHORT_T The number of cell ranges specified in pDrillCells.
1041
pDrillCells; “ESSG_RANGE_T” on Array of cell ranges associated with the linked partition.
page 1030
ulOption; ESSG_ULONG_T Option specifying whether to return Zoom-In results if sent by the server. Use:
l ESSG_OPT_ZOOM to return Zoom-In results.
l ESSG_OPT_NOZOOM to suppress Zoom-In results.
Return Value
See Also
l EssGBeginRemoveOnly
EssGBeginDrillOrLink
Begins the operation of querying the links associated with one or more data cells in an Essbase
database.
Syntax
ESSG_FUNC_M EssGBeginDrillOrLink (hGrid, usCells, pDrillCells,
ulOptions);
usCells; ESSG_USHORT_T The number of cell ranges in the array of ranges specified in pDrillCells.
pDrillCells; “ESSG_RANGE_T” on Array of cell ranges to query for links.

page 1030
ulOptions; ESSG_ULONG_T Option specifying whether to return Zoom-In results if sent by the server. Use:
l ESSG_OPT_ZOOM to return Zoom-In results.
l ESSG_OPT_NOZOOM to suppress Zoom-In results.
Return Value
See Also
1042
l EssGBeginDrillAcross
EssGBeginKeepOnly
Begins a keep-only operation to isolate cells to keep, removing all others.
Syntax
ESSG_FUNC_M EssGBeginKeepOnly (hGrid, usCells, pKeepCells, ulOptions);
usCells ESSG_USHORT_T A count of the number of cell ranges in pKeepCells (the size of array).
pKeepCells “ESSG_RANGE_T” on Describes the cells to be kept. The members to be kept applies only to one
page 1030 dimension. That is, if the user decides to keep, for example, "Qtr1", then all other
members of the Time dimension will be removed and the only representative of
the Time dimension will be "Qtr1". All other dimensions in the report will be left
untouched. This is a one-dimensional array of cell ranges.
More than one member from a dimension may be specified. Also, multiple
dimensions may be specified.
Notes
The cells to be kept are described by a one-dimensional array of cell ranges. Items to be kept
apply on a per dimension basis.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginKeepOnly (ESSG_HGRID_T hGrid)
{
ESSG_USHORT_T usCells;
ESSG_RANGE_T pKeepCells;
1043
"Password", "Demo", "Basic",
ESSG_CONNECT_DEFAULT);
if(sts == 0)
{
pKeepCells.ulRowStart = 1;
pKeepCells.ulColumnStart = 0;
pKeepCells.ulNumRows = 1;
pKeepCells.ulNumColumns = 1;
ulOptions = 0;
usCells = 1;
/* start the keep-only operation */

sts = EssGBeginKeepOnly(hGrid, usCells,
&pKeepCells, ulOptions);
}
if(sts == 0)
{
ppDataIn);
}
if(sts == 0)
{
/* perform the keep-only operation */

}
if (sts == 0)
{
/* determine the results of the keep-only operation */
&usState);
}
if(sts ==0)
{
}
if(sts == 0)
{
/* Free the returned data */
}
if(!sts)
1044
{
}
}
See Also
EssGBeginLock
Locks blocks at the database.
Syntax
ESSG_FUNC_M EssGBeginLock (hGrid, ulOptions);
Notes
l This function is functionally identical to calling the EssGRetrieve function using
ESSG_RET_LOCKONLY for the ulOptions parameter.
l Returns no data to the caller.
l You do not need to retrieve any rows for this operation. It is sufficient to call
EssGSendRows and EssGPerformOperation.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginLock (ESSG_HGRID_T hGrid)
{

1045
if(sts == 0)
{
/* start the lock operation */

ulOptions = 0;
sts = EssGBeginLock(hGrid, ulOptions);
}
if(sts == 0)
{
ppDataIn);
}
if(sts == 0)
{
/* perform the lock operation */

}
if(!sts)
{
}
}
See Also
EssGBeginPivot
Begins a pivot.
Syntax
ESSG_FUNC_M EssGBeginPivot (hGrid, pStartCell, pEndCell, ulOptions);
pStartCell “ESSG_RANGE_T” on page Describes the cell where the pivot is to originate. The member in this cell
1030 describes the dimension to be pivoted. This parameter cannot be NULL.
pEndCell “ESSG_RANGE_T” on page Describes the cell where the dimension is to be placed. A NULL value for this
1030 parameter indicates a pivot from Row to Column, or Column to Row for the
dimension members.
1046
Notes
The caller supplies the starting cell and the destination cell for the pivot.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginPivot (ESSG_HGRID_T hGrid)
{
ESSG_RANGE_T pStartCell;
ESSG_RANGE_T pEndCell;

if(sts == 0)
{
pStartCell.ulRowStart = 0;
pStartCell.ulColumnStart = 3;
pStartCell.ulNumRows = 1;
pStartCell.ulNumColumns = 1;
pEndCell.ulRowStart = 1;
pEndCell.ulColumnStart = 1;
pEndCell.ulNumRows = 1;
pEndCell.ulNumColumns = 1;
ulOptions = 0;
/* start the pivot operation */

sts = EssGBeginPivot(hGrid,&pStartCell, &pEndCell, ulOptions);
}
if(sts == 0)
{
sts = EssGSendRows(hGrid, &rDataRangeIn ppDataIn);
1047
}
if(sts == 0)
{
/* perform the pivot operation */

}
if(sts == 0)
{
/* determine the results of the pivot operation */
}
if(sts ==0)
{
}
if(sts == 0)
{
}
if(!sts)
{
}
}
See Also
EssGBeginRemoveOnly
Begins a remove-only operation, isolating the cells to be removed.
Syntax
ESSG_FUNC_M EssGBeginRemoveOnly (hGrid, usCells, pRemoveCells, ulOptions);
usCells ESSG_USHORT_T A count of the number of cell ranges in pRemoveCells (the size of array).
1048
pRemoveCells “ESSG_RANGE_T” on Describes the cells to be removed. The members removed applies only to one
page 1030 dimension. That is, if the user decides to remove, for example, "Qtr1", then
all other members of the Time dimension will be kept. All other dimensions
in the report will be left untouched. This is a one-dimensional array of cell
ranges.
More than one member from a dimension may be specified. Also, multiple
dimensions may be specified.
Notes
The cells to be removed are described by a one-dimensional array of cell ranges. Items to be
removed apply on a per dimension basis.
Return Value
Example
ESSG_VOID_T ESSG_BeginRemoveOnly (ESSG_HGRID_T hGrid)
{
ESSG_RANGE_T pRemoveCells;

if(sts == 0)
{
pRemoveCells.ulRowStart = 1;
pRemoveCells.ulColumnStart = 0;
pRemoveCells.ulNumRows = 1;
pRemoveCells.ulNumColumns = 1;
ulOptions = 0;
usCells = 1;
/* start the remove-only operation */

sts = EssGBeginRemoveOnly(hGrid, usCells,
&pRemoveCells, ulOptions);
}
if(sts == 0)
1049
{
ppDataIn);
}
if(sts == 0)
{
/* perform the remove-only operation */

}
if (sts == 0)
{
/* determine the results of the remove-only operation */
&usState);
}
if(sts ==0)
{
}
if(sts == 0)
{
}
if(!sts)
{
}
}
See Also
1050
EssGBeginReport
Runs a report script at the server.
Syntax
ESSG_FUNC_M EssGBeginReport (hGrid, pszReportIn, ulOptions)
pszReportIn ESSG_STR_T String (no greater than 64K) containing an Essbase report specification.
ulOptions ESSG_ULONG_T A bitmask which describes returned grid options. Valid values are:
Notes
l Returns the results as a two-dimensional array of cells.
l You do not need to send any rows for this operation. It is sufficient to call
EssGPerformOperation, EssGGetResults, and EssGGetRows.
l Reports passed to the server via the Grid API should be sure to request a tab delimited report
format be returned {TABDELIM}. If a non-tab delimited report is returned, the Grid API
may be unable to convert the resulting report into a grid.
l If the report specification modifies the string used for #Missing aliases, then Missing cells
will be returned as string types (ESSG_DT_STRING) with the new #Missing alias as the text
and not as ESSG_DT_MISSING cells.
l Client programs that call EssGBeginReport() and other report functions need to take into
account new “C Grid API Structures” on page 1024 and “C Grid API Data Types” on page
1022 (specifically StringEx and MemberEx). Older programs should be revised in order to
work with the newer servers.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginReport (ESSG_HGRID_T hGrid)
{
ESSG_RANGE_T rDataRangeOut;
1051
ESSG_STR_T pszReportIn;

sts = EssGConnect(hGrid, "Rainbow", "Admin", "Password", "Demo", "Basic",
if(sts == 0)
{ pszReportIn = "{TabDelim}<idesc Year !";
ulOptions = ESSG_NOATTRIBUTES;
sts = EssGBeginReport(hGrid, pszReportIn,
ulOptions);
}
if(sts == 0)
{
/* perform the report */
}
if(sts == 0)
{
/* determine the results of the report */
&usState);
}
if(sts ==0)
{
}
if(sts == 0)
{
DisplayOutput (ppDataOut, rDataRangeOut);
}
if(!sts)
{
}
}
See Also
EssGBeginReportFile
Runs a report file at the server.
Syntax
ESSG_FUNC_M EssGBeginReportFile (hGrid, pszReportName, bLocal, ulOptions);
1052
pszReportName ESSG_STR_T Name of report to run. If this report resides on the server, then it should exist in
the APPLICATION\DATABASE directory. If this report resides locally, then this
string contains the absolute path name of the report.
bLocal ESSG_BOOL_T Boolean indicating whether the report exists locally or not. A TRUE value indicates
the report exists locally while a FALSE value indicates the report exists on the
server.
ulOptions ESSG_ULONG_T A bitmask which describes returned grid options. Valid values are:
ESSG_NOATTRIBUTES returns grid without pAttributes values
Notes
l Returns the results as a two-dimensional array of cells.
l You do not need to send any rows for this operation. It is sufficient to call
EssGPerformOperation, EssGGetResults, and EssGGetRows.
l Reports passed to the server via the Grid API should be sure to request a tab delimited report
format be returned {TABDELIM}. If a non-tab delimited report is returned, the Grid API
may be unable to convert the resulting report into a grid.
l If the report spec modifies the string used for #Missing aliases, then Missing cells will be
returned as string types (ESSG_DT_STRING) with the new #Missing alias as the text and
not as ESSG_DT_MISSING cells.
l For non-local (Server-based) report file objects, no file extension should be used in the
pszReportName parameter.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginReportFile (ESSG_HGRID_T hGrid)
{
ESSG_RANGE_T rDataRangeOut;
ESSG_STR_T pszReportName;
ESSG_BOOL_T bLocal;
1053
if(sts == 0)
{
pszReportName = "DescYear";
bLocal = ESSG_FALSE;
/*start the report file operation */

sts = EssGBeginReportFile(hGrid,
pszReportName,bLocal, ulOptions);
}
if(sts == 0)
{
/* perform the report operation */
}
if (sts == 0)
{
/* determine the results of the report operation */
}
if(sts ==0)
{
}
if(sts == 0)
{
}
if(!sts)
{
}
}
See Also
1054
EssGBeginRetrieve
Begins the basic retrieval operation.
Syntax
ESSG_FUNC_M EssGBeginRetrieve (hGrid, ulOptions);
ulOptions ESSG_ULONG_T A constant which describes the type of retrieval. One of the following values must be
used:
l ESSG_RET_RETRIEVE Retrieve Only
l ESSG_RET_RETRIEVELOCK Retrieve and Lock
l ESSG_RET_LOCKONLY Lock Only (No data is to be retrieved)
Notes
l Optionally locks blocks at the server for later update as the rows are passed in via
EssGSendRows.
l You can do a retrieval without sending any rows in order to get a default grid with the only
the dimension names used as members.
Return Value
Access
None.
Example
#include <essapin.h>
#include <essgapin.h>
ESSG_VOID_T ESSG_BeginRetrieve(ESSG_HGRID_T hGrid)

{
ESSG_PPDATA_T pDataIn;

"Password", "Demo", "Basic", ESSG_CONNECT_NODIALOG);
if(sts == 0)
{
ulOptions = ESSG_RET_RETRIEVE;
/* start the retrieve operation */
1055
sts = EssGBeginRetrieve(hGrid, ulOptions);
}
if(sts == 0)
{
sts = EssGSendRows(hGrid, &rDataRangeIn, ppDataIn);
}
if(sts == 0)
{
/* perform the retrieval */

}
if(sts == 0)
{
/* determine the results of the retrieve */
}
if(!sts && usState == ESSG_STATE_DONE)

{
sts = EssGGetRows(hGrid, 0, &rDataRangeOut, &rDataRangeOut,
&ppDataOut);
}
if(sts == 0)
{
DisplayOutput (ppDataOut, rDataRangeOut);
}
if(!sts)
{
}
}
See Also
EssGBeginSamplingZoomIn
Begins a random sampled zoom-in operation.
1056
Syntax
ESSG_FUNC_M EssGBeginSamplingZoomIn (hGrid, usCells, pZoomCells, ulSamplingPercentage,
ulOptions);
usCells ESSG_USHORT_T A count of the number of cell ranges in pZoomCells (the size of array).
pZoomCells “ESSG_RANGE_T” Describes the cells to be zoomed in upon. This is a one-dimensional array
on page 1030 of cell ranges.
ulSamplingPercentage ESSG_ULONG_T The percentage sampling rate. This number is an integer between 1 and
100, inclusive. A depth of 100 percent will retrieve all members of the
dimension. This effectively turns sampling off and retrieves all members.
A ulSamplingPercentage of 50 will retrieve half the members.
ulOptions ESSG_ULONG_T A bitmask which describes the type of zoom-in (across or down) and the
level of the zoom. The following two values are mutually exclusive:
l ESSG_ZOOM_DOWN Any page/title dimensions selected will be
zoomed down
l ESSG_ZOOM_ACROSS Any page dimensions selected will be
zoomed across
The following level values for ulOptions are themselves mutually

exclusive:
l ESSG_NEXTLEVEL Children
l ESSG_ALLLEVELS All members
l ESSG_BOTTOMLEVEL Bottom level
l ESSG_SIBLEVEL Sibling level
l ESSG_SAMELEVEL Same level
l ESSG_SAMEGENERATION Same generation
l ESSG_CALCLEVEL Calculation
l ESSG_OPTIONS Use setting for grid options
Use bitwise OR (|) to specify the ulOptions; for example,

ESSG_ZOOM_DOWN | ESSG_NEXTLEVEL
Notes
l The cells to be zoomed in upon are described by a one-dimensional array of cell ranges.
l This function differs from the standard grid Zoom-In function, EssGBeginZoomIn(). This
function has an argument that sets the sampling depth in terms of a percentage. A depth of
100 percent will retrieve all members of the dimension and a depth of 50 percent will retrieve
half the members. This function is especially useful for zooming in on large or very dense
dimensions.
Return Value
1057
Access
None.
See Also
l EssGBeginZoomIn
l EssGBeginConditionalZoomIn
l EssGBeginConditionalZoomIn
EssGBeginUpdate
Begins an update of data at the server. This function returns no data to the caller.
Syntax
ESSG_FUNC_M EssGBeginUpdate (hGrid, ulOptions);
ulOptions ESSG_ULONG_T A constant which indicates whether the blocks must be previously locked or not prior
to update. One of the following mutually exclusive values must be used:
l ESSG_REQUIRELOCK If the blocks haven't been previously locked, disallow the
update.
l ESSG_LOCKIFNEEDED If the blocks haven't been previously locked, lock them
and allow the update.
Notes
The blocks are unlocked after the operation is complete, when you have called
EssGPerformOperation. If you want the blocks to remain locked, set the Update Mode option
to TRUE in EssGSetGridOptions. You do not need to retrieve any rows for this operation; it is
suffcient to call EssGSendRows and EssGPerformOperation.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginUpdate (ESSG_HGRID_T hGrid)
{
1058
"Password", "Demo", "Basic", ESSG_CONNECT_NODIALOG);
if(sts == 0)
{
ppDataIn = BuildTable (&rDataRangeIn);
ulOptions = ESSG_LOCKIFNEEDED;
/* start the update operation */
sts = EssGBeginUpdate(hGrid, ulOptions);
}
if(sts == 0)
{
}
if(sts == 0)
{
/* perform the update */

}
if(!sts)
{
}
}
See Also
EssGBeginZoomIn
Begins a zoom-in.
Syntax
ESSG_FUNC_M EssGBeginZoomIn (hGrid, usCells, pZoomCells, ulOptions);
1059
pZoomCells “ESSG_RANGE_T” Describes the cells to be zoomed in upon. This is a one-dimensional array of cell
on page 1030 ranges.
ulOptions ESSG_ULONG_T A bitmask which describes the type of zoom-in (across or down) and the level of
the zoom. The following two values are mutually exclusive:
l ESSG_ZOOM_DOWN—Any page/title dimensions selected will be zoomed
down
l ESSG_ZOOM_ACROSS—Any page dimensions selected will be zoomed
across
The following level values for ulOptions are themselves mutually exclusive:
l ESSG_NEXTLEVEL—Children
l ESSG_ALLLEVELS—All members
l ESSG_BOTTOMLEVEL—Bottom level
l ESSG_SIBLEVEL—Sibling level
l ESSG_SAMELEVEL—Same level
l ESSG_SAMEGENERATION—Same generation
l ESSG_CALCLEVEL—Calculation
l ESSG_OPTIONS—Use setting for grid options
Use bitwise OR (|) to specify the ulOptions; for example, ESSG_ZOOM_DOWN

| ESSG_NEXTLEVEL
Notes
The cells to be zoomed in upon are described by a one-dimensional array of cell ranges.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginZoomIn (ESSG_HGRID_T hGrid)
{

1060
if(sts == 0)
{
ulOptions = ESSG_ZOOM_DOWN | ESSG_ALLLEVELS;
usCells = 1;
/* start the zoom in operation */

sts = EssGBeginZoomIn(hGrid, usCells, &pZoomCells, ulOptions);
}
if(sts == 0)
{
ppDataIn);
}
if(sts == 0)
{
/* perform the zoom-in */

}
if (sts == 0)
{
/* determine the results of the zoom-in */
&usState);
}
if(sts ==0)
{
}
if(sts == 0)
{
}
if( !sts)
{
1061
}
}
See Also
EssGBeginZoomOut
Begins a zoom-out.
Syntax
ESSG_FUNC_M EssGBeginZoomOut (hGrid, usCells, pZoomCells, ulOptions);
pZoomCells “ESSG_RANGE_T” on page Describes the cells to be zoomed out upon. This is a one-dimensional array
1030 of cell ranges.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_BeginZoomOut (ESSG_HGRID_T hGrid)
{

if(sts == 0)
{
1062
ulOptions = 0;
usCells = 1;
/* start the zoom out operation */

sts = EssGBeginZoomOut(hGrid, usCells,
&pZoomCells, ulOptions);
}
if(sts == 0)
{
ppDataIn);
}
if(sts == 0)
{
/* perform the zoom-out */

}
if (sts == 0)
{
/* determine the results of the zoom-out */
&usState);
}
if(sts ==0)
{
}
if(sts == 0)
{
}
if(!sts)
{
}
}
See Also
1063
EssGCancelOperation
Cancels an operation at any stage during an operation.
Syntax
ESSG_FUNC_M EssGCancelOperation (hGrid, ulOptions);
Notes
l You can make this call at any time after EssGBeginXxx has been called.
l The current operation is cancelled, and all resources are freed.
Return Value
Access
None.
Example
ESSG_VOID_T EssGCancelOperation (ESSG_HGRID_T hGrid)
{
ESSG_STR_T pszReportIn;

if(sts == 0)
{
pszReportIn = "{TabDelim}<idesc Year !";
sts = EssGBeginReport(hGrid, pszReportIn,
ulOptions);
}
if(sts == 0)
{
ulOptions = 0;
sts = EssGCancelOperation(hGrid, ulOptions);
}
1064
if(!sts)
{
}
}
See Also
EssGCell
Retrieves from the server a singular value representing a solitary datapoint.
Syntax
ESSG_FUNC_M EssGCell (hGrid, usCount, pszMbrs, pDataCell);
usCount ESSG_USHORT_T Number of members being sent in. The maximum number of dimensions
that EssGCell can report is 20.
pszMbrs ESSG_PSTR_T Array of member names to query. No more than one representative per
dimension is allowed.
pDataCell “ESSG_DATA_T” on page Value returned by server.

1024
Notes
l You can specify a maximum of:
m 20 members.
m One member per dimension.
l If you do not specify a member for a dimension, the top level (dimension) member is used
as the default.
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_Cell (ESSG_HGRID_T hGrid)
{
1065
ESSG_USHORT_T usCount;
ESSG_DATA_T DataCell;
ESSG_CHAR_T *pszMbrs[5] = { "Actual", "Jan",
"West", "Audio",
"Sales"};

ESSG_CONNECT_NODIALOG);
/* retrieve cell value */

usCount = 5;
if(sts == 0)
sts = EssGCell(hGrid, usCount, pszMbrs,&DataCell);
if(!sts)
{
switch(DataCell.usType)
{
case(ESSG_DT_STRING):
printf("%s", DataCell.Value.pszStr+1);
break;
case(ESSG_DT_LONG):
printf("%ld", DataCell.Value.lData);
break;
case(ESSG_DT_DOUBLE):
printf("%g", DataCell.Value.dblData);
break;
case(ESSG_DT_BLANK):
break;
case(ESSG_DT_RESERVED):
printf("#Reserved");
break;
case(ESSG_DT_ERROR):
printf("#Error");
break;
case(ESSG_DT_MISSING):
printf("#Missing");
break;
case(ESSG_DT_ZERO):
printf("%ld", DataCell.Value.lData);
break;
case(ESSG_DT_NOACCESS):
printf("#NoAccess");
break;
case(ESSG_DT_MEMBER):
printf("%s", DataCell.Value.pszStr+1);
break;
default:
break;
}
}
if(!sts)
}
1066
See Also
EssGCreateMemberwKeyStr
Creates a combined string using the member name and member key as input. A key is a value
generated by Essbase that uniquely identifies a member name in the outline.
Syntax
ESSG_FUNC_M EssGCreateMemberwKeyStr (pszMember, pszKey, *pszOutStr);
pszMember ESSG_STR_T Member name (input).
pszKey ESSG_STR_T Member key (input).
*pszOutStr ESSG_STR_T Output string of the format:

<member-name length><member-name><key length ><key>
where the length elements are 2 bytes in size. Note that <member-name> is null-
terminated.
Notes
You must free the string *pszOutStr using EssGFreeMemberwKeyStr.
Example
ESSG_VOID_T ESSG_BeginZoomIn(ESSG_HGRID_T hGrid)
{
ESSG_DATA_T **ppDataIn;
ESSG_DATA_T **ppDataOut;
ESSG_USHORT_T usMember2Len, usKey2Len;
ESSG_SHORT_T sOption, sOptionGet;
ESSG_SHORT_T tmpShort, tmpShortGet, i;
ESSG_PVOID_T pOption, pOptionGet;
ESSG_STR_T pMember, pKey, pOutStr;
ESSG_STR_T pMember2, pKey2;

sts = EssGConnect(hGrid, server, "essexer", pwd, app, db, ESSG_CONNECT_NODIALOG);
/* set grid option*/

tmpShort = ESSG_TRUE;
sOption = ESSG_OP_MEMBERANDUNIQUENAME ;
1067
pOption = (ESSG_PVOID_T)tmpShort; // pOption holds the actual value not a pointer
sts = EssGSetGridOption(hGrid, sOption, pOption);

printf("EssGSetGridOption sts %ld\n",sts);
sOptionGet = ESSG_OP_MEMBERANDUNIQUENAME ;
pOptionGet = &tmpShortGet;
if(!sts)
{
sts = EssGGetGridOption(hGrid, sOptionGet, pOptionGet);
printf("EssGGetGridOption sts %ld\n",sts);
printf("EssGSetGridOption set ESSG_OP_MEMBERANDUNIQUENAME TO %d\n",
(int)tmpShortGet);
}
if(sts == 0)
{
ulOptions = ESSG_ZOOM_DOWN | ESSG_NEXTLEVEL;
usCells = 1;

printf("EssGBeginZoomIn sts: %ld\n",sts);
}
//Display Input
DisplayOutput(ppDataIn, rDataRangeIn);
printf("\n\n");
if(sts == 0)
if(sts == 0)
{

}
if (sts == 0)
{
}
if(sts ==0)
{
sts = EssGGetRows(hGrid, 0, &rDataRangeOut, &rDataRangeOut, &ppDataOut);
1068
}
if(sts == 0)
{
/* Retreive member and key from cell */

sts = EssGGetFromMemberwKey (((ppDataOut[1][0]).Value).pszStr, &pMember, &pKey);
printf("After EssGGetFromMemberwKey\n Member: %s, Key: %s \n\n",
pMember+2,
pKey+2);
//Member is "Qtr1", Key is "[2004].[Qtr1]", pOutStr is in the format

//nn<member-name>nn<'key> - where nn is string length
usMember2Len = strlen("Qtr1");
pMember2 = malloc(usMember2Len+3);
memset(pMember2, 0, usMember2Len+3);
usKey2Len = strlen("[2004].[Qtr1]");
pKey2 = malloc(usKey2Len+3);
memset(pKey2, 0, usKey2Len+3);
memcpy(pMember2, &usMember2Len, 2);

memcpy(pMember2+2, "Qtr1", usMember2Len);
memcpy(pKey2, &usKey2Len, 2);

memcpy(pKey2+2, "[2004].[Qtr1]", usKey2Len);
sts = EssGCreateMemberwKeyStr(pMember2, pKey2, &pOutStr);
/*Note: because not all elements in pOutStr are actual characters,

e.g. the 2 bytes for the size of Member and size of Key, plus the
\0 ending characters, the printf below does not display the actual
contents of the array */
for (i=0;i < usMember2Len + usKey2Len + 4 + 2; ++i)
printf("%c", pOutStr[i]);

sts = EssGFreeMemberwKeyStr (pOutStr);
if( sts == 0)
{
}
}
See Also
l EssGFreeMemberwKeyStr
l EssGGetFromMemberwKey
1069
EssGConnect
Connects a grid to an Essbase database.
Syntax
ESSG_FUNC_M EssGConnect (hGrid, Server, Username, Password, Application,
Database, ulOptions);
Server ESSG_SERVER_T Network server name string.

The server name can be expressed as hostname or hostname:port.
Username ESSG_USERNAME_T Name of valid user at server.
Password ESSG_PASSWORD_T Password of user.
Application ESSG_APPLICATION_T Name of a valid application on server.
Database ESSG_DATABASE_T Name of a valid database for application on server.
ulOptions ESSG_ULONG_T Options flag. Values are ESSG_CONNECT_NODIALOG, which attempts to

login and connect without displaying dialog, using the default/passed setting;
or ESSG_CONNECT_DEFAULT which will display the login and selection
dialog.
Notes
l Calls EssAutoLogin, therefore all rules that apply to EssAutoLogin apply to this function.
For example, none of the parameters are case-sensitive.
l If ulOptions is set to ESSG_CONNECT_NODIALOG, none of the connection related
parameters can be NULL or empty. When ulOptions is set to
ESSG_CONNECT_DEFAULT, and a buffer is passed for the connect parameters, the user's
selections from the dialog will be returned in these buffers.
l All security information is utilitized. Therefore, if the user connects to a database to which
he or she does not have read access, all read operations will fail.
Return Value
Access
None.
Example

ESSG_INIT_T InitStruct;
ESSG_HANDLE_T Handle;
1070
ESSG_USERNAME_T UserName;
ESSG_APPLICATION_T Application;
ESSG_DATABASE_T Database;
ESSG_HGRID_T hGrid;
InitStruct.ulVersion = ESSG_VERSION;
InitStruct.ulMaxRows = 1000;
InitStruct.ulMaxColumns = 200;
InitStruct.pfnMessageFunc = ESS_NULL;
InitStruct.pUserdata = ESS_NULL;
/* initializes EGAPI */
sts = EssGInit(&InitStruct, &Handle);
/* initializes a specific grid */

if(!sts)
sts = EssGNewGrid(Handle, &hGrid);
strcpy(Server, "Rainbow");
strcpy(UserName, "Admin");
strcpy(Password, "Password");
strcpy(Application, "Demo");
strcpy(Database, "Basic");
ulOptions = ESSG_CONNECT_NODIALOG;
/* connects the grid to a database on the server */

if(!sts)
sts = EssGConnect(hGrid, Server, UserName, Password, Application,
Database, ulOptions);
}
See Also
EssGConnectEx
Connects a grid to an Essbase database using a user authentication token rather than a username
and password.
Syntax
ESSG_FUNC_M EssGConnectEx (hGrid, Server, Token, Application, Database, ulOptions);
Server ESSG_SERVER_T Network server name string.

The server name can be expressed as hostname or hostname:port.
1071
Token ESSG_TOKEN_T The token representing the username and password of an authenticated user.
Username ESSG_USERNAME_T Name of valid user at server.
Password ESSG_PASSWORD_T Password of user.
Application ESSG_APPLICATION_T Name of a valid application on server.
Database ESSG_DATABASE_T Name of a valid database for application on server.
ulOptions ESSG_ULONG_T Options flag. Values are ESSG_CONNECT_NODIALOG, which attempts to

login and connect without displaying dialog, using the default/passed setting;
or ESSG_CONNECT_DEFAULT which will display the login and selection
dialog.
Notes
l If this function fails, the corresponding EssGConnect() function is automatically called in
order to try to verify a username and password for the user.
l Calls EssAutoLogin, therefore all rules that apply to EssAutoLogin apply to this function.
For example, none of the parameters are case-sensitive.
l If ulOptions is set to ESSG_CONNECT_NODIALOG, none of the connection related
parameters can be NULL or empty. When ulOptions is set to
ESSG_CONNECT_DEFAULT, and a buffer is passed for the connect parameters, the user's
selections from the dialog will be returned in these buffers.
l All security information is utilitized. Therefore, if the user connects to a database to which
he or she does not have read access, all read operations will fail.
Return Value
Access
None.
See Also
l EssGConnect
EssGDeleteLRO
Deletes a specified LRO from an Essbase database.
Syntax
ESSG_FUNC_M EssGDeleteLRO (hGrid, hLRO);
1072
hLRO; ESSG_HLRO_T Handle to the linked object (returned in a DRILLDATA structure by the
EssGGetCellLinkResults() function).
Notes
To delete all objects linked to a particular range of cells, use EssGBeginDeleteLROs.
Return Value
See Also
l EssGGetLRODesc
l EssGGetLRO
l EssGUpdateLRO
EssGDestroyGrid
Destroys a grid instance.
Syntax
ESSG_FUNC_M EssGDestroyGrid (hGrid)
Notes
Frees any memory associated with the passed grid handle, and makes the handle invalid.
Return Value
Access
None.
Example
1073
ESSG_HGRID_T hGrid;

if(!sts)
/* destroys a grid instance */

if(!sts)
sts = EssGDestroyGrid(hGrid);
See Also
l EssGNewGrid
EssGDisconnect
Disconnects a grid from a database at the server.
Syntax
ESSG_FUNC_M EssGDisconnect (hGrid, ulOptions);
Return Value
Example

ESSG_ULONG_T ulOptions = 0;
1074
ESSG_HGRID_T hGrid;

if(!sts)
sts = EssGNewGrid(&Handle, &hGrid);

if(!sts)
/* disconnects a grid from database at server */

if(!sts)
sts = EssGDisconnect(hGrid, ulOptions);
/* terminate the EGAPI */

if(!sts)
sts = EssGTerm(Handle);
}
See Also
EssGDTBeginDrillThrough
Returns the drill-through instance handle for the given data cell range(s).
Syntax
ESSG_FUNC_M EssGDTBeginDrillThrough (hGrid, usCells, pCells, ppDTInst);
usCells; ESSG_USHORT_T Number of cell ranges in the pCells array.
pCells; “ESSG_RANGE_T” on page 1030 Array of cell ranges selected to receive drill-through report data.
ppDTInst; ESSG_PPDTHINST_T Drill-through instance handle returned for the given data cell range(s).
See Also
l “C Grid API Constants” on page 1015
1075
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTGetReportData
l EssGInit
l EssGDTListReports
l EssGDTReportCount
EssGDTConnect
Takes drill-through connection information for a given drill-through handle, and connects to
Oracle Essbase Studio.
Syntax
ESSG_FUNC_M EssGDTConnect (pDTInst);
pDTInst; ESSG_PDTHINST_T Initialized drill-through instance handle
Example
For a code example, see “C Grid API Drill-Through Example” on page 1123.
See Also
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
l EssGDTSetInfo
EssGDTEndDrillThrough
Ends the drill-through session and frees up memory for the given drill-through instance handle.
Syntax
ESSG_FUNC_M EssGDTEndDrillThrough (pDTInst);
1076
pDTInst; ESSG_PDTHINST_T Initialized drill-through instance handle for the given data cell range.
Example
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
l EssGDTSetInfo
EssGDTExecuteReport
Executes the report identified by its index to an array of report structures.
Syntax
ESSG_FUNC_M EssGDTExecuteReport (pDTInst, Index);
Index; ESSG_ULONG_T Index of the report to be executed
Example
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
l EssGDTSetInfo
1077
EssGDTGetData
Retrieves an array of report data for the given drill-through instance handle.
Syntax
ESSG_FUNC_M EssGDTGetData (pDTInst, ppData, pulCount);
pDTInst; ESSG_PDTHINST_T Initialized drill-through instance handle.
ppData; “ESSG_DTDATA_T” on page 1027 Array of report data structures for given data cells.
pulCount; ESSG_PULONG_T Count of data blocks in the ppData array.
Notes
l Call EssGDTGetData() until pulCount is 0 (zero).
l Free memory for ppData (ESSG_DTDATA_T) with EssFree() after you call
EssGDTGetData().
Example
For a code example , see “C Grid API Drill-Through Example” on page 1123.
See Also
l EssGDTConnect
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
l EssGDTSetInfo
l EssFree
EssGDTGetHeader
Retrieves the report data header information for the given drill-through instance handle.
Syntax
ESSG_FUNC_M EssGDTGetHeader (pDTInst, ppHeader, pulCount);
pDTInst; ESSG_PDTHINST_T Initialized drill-through instance handle.
ppHeader; “ESSG_DTHEADER_T” on page 1027 Array of header information structures for given columns.
1078
pulCount; ESSG_PULONG_T Count of data blocks in the ppHeader header information array.
Notes
Free memory for ppHeader (ESSG_DTHEADER_T) with EssFree() after you call
EssGDTGetHeader().
Example
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetInfo
l EssGDTListReports
l EssGDTSetInfo
l EssFree
EssGDTGetInfo
Retrieves drill-through connection information for a given drill-through handle.
Syntax
ESSG_FUNC_M EssGDTGetInfo (pDTInst, pDTInfo);
pDTInfo; “ESSG_DTINFO_T” on page 1028 Pointer to a structure of connection information for a given range of
data cells
Notes
l Allocate memory for ESSG_DTINFO_T before you call EssGDTGetInfo().
l password is not returned in pDTInfo; that is, the password field in ESSG_DTINFO_T is not
returned.
Example
1079
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetHeader
l EssGDTListReports
l EssGDTSetInfo
EssGDTGetReportData
Executes the predefined default drill-through report for the given data cell range, and returns
report data via the given grid handle hDAGrid.
Syntax
ESSG_FUNC_M EssGDTGetReportData (hGrid, hDAGrid, usCells, pCells);
hDAGrid; ESSG_HGRID_T Handle of the new grid to receive drill-through report data.
See Also
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGInit
l EssGDTListReports
l EssGDTReportCount
EssGDTListReports
Returns an array of report structures for the given drill-through instance handle.
1080
Syntax
ESSG_FUNC_M EssGDTListReports (pDTInst, ppReports, pulCount);
ppReports; “ESSG_DTREPORT_T” on page An array of report structures for the given drill-through instance
1028 handle
pulCount; ESSG_PULONG_T Number of blocks in the ppReports header information array
Example
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTSetInfo
EssGDTReportCount
Returns the number of reports defined for the given data cell range(s).
Syntax
ESSG_FUNC_M EssGDTReportCount (hGrid, usCells, pCells, uspReportNum);
uspReportNum; ESSG_PUSHORT_T Number of reports defined for the given data cell range(s).
See Also
l EssGDTGetData
1081
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTGetReportData
l EssGInit
l EssGDTListReports
EssGDTRequestDrillThrough
Returns the drill-through instance handle for the given data cell range.
Syntax
ESSG_FUNC_M EssGDTRequestDrillThrough (hGrid, usCells, pCells, ppDTInst);
ppDTInst; ESSG_PPDTHINST_T Drill-through instance handle returned for the given data cell range(s).
Notes
l Sends a request to the Essbase Server for an optimized Extended Member Comment
l Initializes a drill-through session with the given Extended Member Comment
l Returns the drill-through instance handle, ppDTInst.
Example
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
l EssGDTSetInfo
1082
EssGDTSetInfo
Sets drill-through connection information for a given drill-through handle.
Syntax
ESSG_FUNC_M EssGDTSetInfo (pDTInst, pDTInfo);
pDTInfo; “ESSG_DTINFO_T” on page 1028d Pointer to a structure of connection information for a given range of
data cells
Notes
The inputOption field in ESSG_DTINFO_T is ignored.
Example
See Also
l EssGDTConnect
l EssGDTGetData
l EssGDTGetHeader
l EssGDTGetInfo
l EssGDTListReports
EssGEndOperation
Frees any internal resources used after the operation is complete and all rows have been returned.
Syntax
ESSG_FUNC_M EssGEndOperation (hGrid, ulOptions);
1083
Notes
This call is optional and can be made to free internal resources after an operation is complete.
If you do not make this call, internal resources are freed when the next operation starts, or when
the caller disconnects the grid, whichever comes first.
Return Value
Access
None.
Example
See an example that uses this code in the EssGBeginRetrieve Example section.
See Also
EssGFreeCellLinkResults
Releases all resources reserved to store the links resulting from a previous call to
EssGGetCellLinkResults().
Syntax
ESSG_FUNC_M EssGFreeCellLinkResults (hGrid, pDrillData);
pDrillData; “ESSG_DRILLDATA_T” on page Reference to an array of ESSG_DRILLDATA_T structures

1027 containing information about the linked objects.
Notes
EssGGetCellLinkResults() takes a reference to a pointer to ESSG_DRILLDATA_T, but that this
function only requires the pointer to ESSG_DRILLDATA_T.
Return Value
See Also
1084
l EssGDeleteLRO
l EssGGetLRO
l EssGUpdateLRO
EssGFreeMemberInfo
Frees any data returned by any call that returns member information, including
EssGGetMemberInfo, and EssGGetDataPointResults.
Syntax
ESSG_FUNC_M EssGFreeMemberInfo (hGrid, ulMembers, pszMembers);
ulMembers ESSG_ULONG_T Describes the number of elements in the ppszMembers array to be freed.
pszMembers ESSG_PSTR_T Pointer to a one-dimensional array of member names to be freed.
Notes
The parameters to this function include the number of elements in the one-dimensional array,
and the one-dimensional array of member names itself.
Return Value
Access
None.
Example
EssGFreeMemberInfo(hGrid, ulMembers, pszMembers);
See an example that uses this code in EssGGetMemberInfo.
See Also
EssGFreeMemberwKeyStr
Frees the combined string of member name and member key that is created by
EssGCreateMemberwKeyStr.
1085
Syntax
ESSG_FUNC_M EssGFreeMemberwKeyStr (pszStr);
pszStr ; ESSG_STR_T Input. Combined member/key string of the format: <member-name

length><member-name><key length ><key>
Example
{



if(!sts)
{
(int)tmpShortGet);
}
if(sts == 0)
{
1086
usCells = 1;

}
//Display Input
printf("\n\n");
if(sts == 0)
if(sts == 0)
{

}
if (sts == 0)
{
}
if(sts ==0)
{
}
if(sts == 0)
{

pMember+2,
pKey+2);

1087



if( sts == 0)
{
}
}
See Also
l EssGCreateMemberwKeyStr
l EssGGetFromMemberwKey
EssGFreeRows
Frees data that has been returned via EssGGetRows.
Syntax
ESSG_FUNC_M EssGFreeRows (hGrid, pRange, ppData);
pRange “ESSG_RANGE_T” on page 1030 Describes the extent of the data.
ppData “ESSG_DATA_T” on page 1024 A two-dimensional array of data to be freed.
Return Value
1088
Access
None.
Example
See Also
EssGGetAPIContext
Gets the API login context handle for the specified grid.
Syntax
ESSG_FUNC_M EssGGetAPIContext (hGrid, pEssHctx);
pEssHctx ESSG_PPVOID_T Variable for the return of the API context handle of the connected grid.
Notes
l This allows the caller to call non-Grid API functions that require a login context handle.
l If there is no valid connection to the server, there is no valid API context handle and the call
will fail and set *pEssHctx to ESS_INVALID_HCTX.
l Do not use the returned login context in API functions that would change the context
information.
Return Value
Example

ESSG_PVOID_T EssHctx;
ESSG_HGRID_T hGrid;
1089
sts = EssGInit(&InitStruct, Handle);
if(!sts)

if(!sts)
"Password", "Demo",
"Basic", ESSG_CONNECT_DEFAULT);
/* Get API context handle for the specified grid */

if(!sts)
sts = EssGGetAPIContext(hGrid, &EssHctx);
}
See Also
EssGGetAPIInstance
Gets the API initialization instance handle.
Syntax
ESSG_FUNC_M EssGGetAPIInstance (Handle, pEssHinst);
Handle ESSG_HANDLE_T Handle passed back from EssGInit.
pEssHinst ESSG_PPVOID_T Variable for the return of the API instance handle used by the Grid API.
Notes
This handle the caller to call non-Grid API functions that require an instance handle.
Return Value
Access
None.
Example

ESSG_PVOID_T EssHinst;
1090
/* get API initialization instance handle */

if(!sts)
sts = EssGGetAPIInstance(Handle, &EssHinst);
See Also
EssGGetCellLinkResults
Retrieves a list of links resulting from a previous call to EssGBeginDrillOrLink().
Syntax
ESSG_FUNC_M EssGGetCellLinkResults (hGrid, pfCanDrill, pNumLROs,
ppDrillData, pRangeOut, pState);
pfCanDrill; ESSG_PBOOL_T Returns True if the cell has linked objects. If you request Zoom-In results
by specifying the ESSG_OPT_ZOOM option with
EssGBeginDrillOrLink(), pfCanDrill returns False.
pNumLROs; ESSG_PULONG_T Returns the number of links retrieved.
ppDrillData; “ESSG_DRILLDATA_T” on Returns references to an array of ESSG_DRILLDATA_T structures

page 1027 containing information about the linked objects.
pRangeOut; “ESSG_RANGE_T” on page Returns the cell ranges for the Zoom-In if no LROs were found and you
1030 specified the ESSG_OPT_ZOOM option in your call to
EssGBeginDrillOrLink().
pState; ESSG_PUSHORT_T Returns one of the following states of operation:

l In progress—Not all cells have been retrieved
l Done—All cells have been retrieved
Notes
l This function allocates memory for ESSG_DRILLDATA_T. Release that memory with a call
to EssGFreeCellLinkResults.
1091
l The handles retrieved from this function are valid until the next call to any of the following
Grid API functions:
m EssGBeginDrillOrLink()
m EssGBeginCreateLRO()
m EssGUpdateLRO()
m EssGBeginDeleteLRO()
m EssGDeleteLRO()
Return Value
See Also
l EssGGetGridOption
l EssGPerformOperation
l EssGSetGridOption
l EssGDeleteLRO
l EssGGetLRODesc
l EssGGetLinkedPartitionDesc
l EssGGetLRO
l EssGUpdateLRO
EssGGetDataPointResults
Retrieves information from the EssGBeginDataPoint call (EssGBeginDataPoint,
EssGSendRows, EssGPerformOperation).
Syntax
ESSG_FUNC_M EssGGetDataPointResults (hGrid, pulMembers, ppszMembers,
pState);
pulMembers ESSG_PULONG_T Count of members being returned.
1092
*ppszMembers ESSG_PSTR_T Pointer to a one dimensional array of size pulMembers of members returned
from the server. The API allocates this memory and should be freed by the caller
using EssGFreeMemberInfo.
Note: The ppszMembers parameter should be freed by the caller using

EssGFreeMemberInfo.
pState ESSG_PUSHORT_T Variable for the return of the state of the operation. This can be one of the
following values:
l ESSG_STATE_DONE Operation complete
l ESSG_STATE_INPROGRESS The operation is in progress
Notes
Make this call multiple times until the pState variable returns ESSG_STATE_DONE.
Return Value
Access
None.
Example
sts = EssGGetDataPointResults(hGrid, &ulMembers,
See an example that uses this code in the EssGBeginDataPoint Example section.
See Also
EssGGetFormattedValue
Returns the formatted value for the given cell.
Syntax
ESS_FUNC_M EssGGetFormattedValue(hGrid, pData, *fmtVal)
hGrid ESSG_HGRID_T Grid handle
pData ESSG_PDATA_T Pointer to the ESSG_DATA_T structure of the cell.
*fmtVal ESSG_STR_T Pointer to formatted value for this cell
1093
Notes
l The grid option ESSG_OP_GET_FORMATTED_VALUE should be turned on to obtain the
formatted values.
l You do not need to free the returned pointer, as this is managed by the API.
Return Value
l 0—If successful
EssGGetFromMemberwKey
Returns a member name and key. A key is a value generated by Essbase that uniquely identifies
a member name in the outline.
Syntax
ESSG_FUNC_M EssGGetFromMemberwKey (pszOutStr, pszMember, pszKey);
pszOutStr ; ESSG_STR_T Input string of the format: <member-name length><member-name><key

length ><key>, where the length elements are 2 bytes in size. Note that <member-
name> is null-terminated. The string is returned from the API or can be created using
EssGCreateMemberwKeyStr.
pszMember; ESSG_STR_T Member name (output).
pszKey; ESSG_STR_T Member key (output).
Notes
When the usType field of the ESSG_DATA_T structure is set to ESSG_DT_MEMBERwKEY,
then the pszStr field of Value(ESSG_DATA_VALUE) field is interpreted as the format required
for pszOutStr.
Example
{
1094


if(!sts)
{
(int)tmpShortGet);
}
if(sts == 0)
{
usCells = 1;

}
//Display Input
printf("\n\n");
if(sts == 0)
if(sts == 0)
{

}
if (sts == 0)
1095
{
}
if(sts ==0)
{
}
if(sts == 0)
{

pMember+2,
pKey+2);





if( sts == 0)
{
1096
}
}
See Also
l EssGCreateMemberwKeyStr
l EssGFreeMemberwKeyStr
EssGGetGridOption
Gets individual grid options.
Syntax
ESSG_FUNC_M EssGGetGridOption (hGrid, sOption, pOption);
hGrid ESSG_HGRID_T Handle passed back from EssGNewGrid().
sOption ESSG_SHORT_T Number indicating what option is being retrieved.
pOption ESSG_PVOID_T Pointer to the option retrieved. With the exception of the ESSG_OP_USERGRIDDATA
pointer, this data is read-only and should not be freed by the caller.
Return Value
Example
ESSG_VOID_T EssG_GetGridOption(ESSG_HGRID_T hGrid)
{
ESSG_SHORT_T sOption;
ESSG_SHORT_T tmpShort;
ESSG_PVOID_T pOption;

/* get grid option */
sOption = ESSG_OP_DRILLLEVEL;
pOption = &tmpShort;
if(!sts)
sts = EssGGetGridOption(hGrid, sOption, pOption);
if(!sts)
{
printf("\n%s: %d", "DRILLLEVEL", tmpShort);
}
}
See Also
1097
l EssGSetGridOption
EssGGetGridPerspective
Returns the perspective for a grid.
Syntax
ESSG_FUNC_M EssGGetGridPerspective(hGrid, sAttrdim, *pPerspectiveType,
*pPerspectiveString)
sAttrdim ESSG_STR_T Attribute dimension name for which the perspective is queried
*pPerspectiveType ESSG_SHORT_T Type of perspective. See “Grid Perspective Types” on page 1021.
*pPerspectiveString ESSG_STR_T Pointer to perspective tuple set being returned.

l Null for perspective types other than ESSG_PERSP_EXPLICIT.
l For ESSG_PERSP_EXPLICIT, this value should be explicitly freed.
Return Value
l 0—If successful
See Also
l EssGSetGridPerspective
EssGGetIsCellDrillable
Checks whether a cell is associated with a drill-through URL.
Syntax
ESS_FUNC_M EssGGetIsCellDrillable (hGrid, pData, pIsDrillable);
hGrid ESSG_HGRID_T Grid handle returned by EssGNewGrid()
pData ESS_PDATA_T Pointer to the ESSG_DATA_T structure of the cell
pIsDrillable ESS_PBOOL_T True, if the cell is associated with a drill-through URL; False otherwise
Return Value
l If successful, sets pIsDrillable accordingly.
1098
Example
#define ESSG_OP_GET_DRILLTHRU_URLS 41
ESSG_STS_T sts = EssGInit(&InitStruct, &Handle);

sts = EssGConnect(hGrid,Server,UserName,Password,Application,Database,ulOptions);
sts = EssGSetGridOption(hGrid, ESSG_OP_GET_DRILLTHRU_URLS ,(ESSG_PVOID_T)(ESSG_TRUE));
ppDataIn = BuildQuery(&rRangeDataIn);
sts = EssGBeginRetrieve(hGrid,ESSG_RET_RETRIEVE);
sts = EssGSendRows(hGrid, &rRangeDataIn, ppDataIn);
/*To retrieve the cell drillable property of a cell*/
EssGGetIsCellDrillable(hGrid, &(cells[ulRow][ulCol]), &bIsDrillable);

if (bIsDrillable)
printf("bIsDrillable: true");
else
printf("bIsDrillable: false");
EssGGetLinkedPartitionDesc
Retrieves the description for a linked partition. You specify the partition with a unique handle
returned by an EssGGetCellLinkResults() function call.
Syntax
ESSG_FUNC_M EssGGetLinkedPartitionDesc (hGrid, hLRO, pConnectInfo);
hLRO; ESSG_HLRO_T Handle to the linked partition (returned in a DRILLDATA

structure by the EssGGetCellLinkResults() function). The handle
must specify a linked object of type ESSG_PARTITIONTYPE.
pConnectInfo; “ESSG_CONNECTINFO_T” on Returns connection information for the linked partition.

page 1024
Notes
To retrieve descriptions for linked objects that are not partitions, use EssGGetLRODesc.
Return Value
See Also
1099
l EssGGetGridOption
l EssGSetGridOption
l EssGDeleteLRO
l EssGGetLRODesc
l EssGGetLRO
l EssGUpdateLRO
EssGGetLRO
Retrieves a LRO from an Essbase database.
Syntax
ESSG_FUNC_M EssGGetLRO (hGrid, hLRO, szTargetFile, ulOption);
hGrid ESSG_HGRID_T Grid handle returned by EssGNewGrid().
hLRO ESSG_HLRO_T Handle to the linked object (returned in a DRILLDATA structure by the
szTargetFile ESSG_STR_T The name of the target file, including path, into which the object is retrieved.
ulOption ESSG_ULONG_T Option specifying whether to retrieve the object, its catalog entry, or both. Use one of
the following:
l ESS_LRO_OBJ_API to retrieve only the object.
l ESS_LRO_CATALOG_API to retrieve only the catalog entry.
l ESS_LRO_BOTH_API to retrieve object and catalog entry.
Notes
To retrieve a cell note, use EssGGetLRODesc. EssGGetLRO does not retrieve cell note
information.
Return Value
See Also
1100
l EssGGetGridOption
l EssGSetGridOption
l EssGDeleteLRO
l EssGGetLRODesc
l EssGGetLinkedPartitionDesc
l EssGUpdateLRO
EssGGetLRODesc
Retrieves the description information for a linked object. You specify the object with a unique
handle returned by an EssGGetCellLinkResults() function call.
Syntax
ESSG_FUNC_M EssGGetLRODesc (hGrid, hLRO, pLroDesc);
hLRO; ESSG_HLRO_T Handle to the linked partition (returned in a DRILLDATA structure by the
EssGGetCellLinkResults() function). The handle can specify a linked object of any
type except ESSG_PARTITIONTYPE.
pLroDesc; ESSG_LPLRODESC_T Returns an LRO description structure containing information about the specified
object.
Notes
To retrieve descriptions for partitions (object type ESSG_PARTITIONTYPE), use
EssGGetLinkedPartitionDesc.
Return Value
See Also
l EssGDeleteLRO
1101
l EssGGetLRO
l EssGUpdateLRO
l EssGUpdateLRO
l EssGUpdateLRO
l EssGUpdateLRO
l EssGUpdateLRO
EssGGetMemberInfo
Returns member relationship information from within one dimension.
Syntax
ESSG_FUNC_M EssGGetMemberInfo (hGrid, pszMbrName, sAction,
bAliases, pulMembers, ppszMembers);
hGrid ; ESSG_HGRID_T Handle passed back from EssGNewGrid.
pszMbrName; ESSG_STR_T Name of the member for which relationship information will be obtained.
sAction; ESSG_SHORT_T Number indicating what type of relationship information will be returned. The
following values are valid for this parameter and are mutually exclusive:
l ESSG_NEXTLEVEL Children
l ESSG_ALLLEVELS All members
l ESSG_BOTTOMLEVEL Bottom level
l ESSG_SIBLEVEL Sibling level
l ESSG_SAMELEVEL Same level
l ESSG_SAMEGENERATION Same generation
l ESSG_CALCLEVEL Calculation
l ESSG_PARENTLEVEL Parent of member
l ESSG_TOPLEVEL Dimension member belongs to
bAliases ; ESSG_BOOL_T Indicates whether alias names will be returned.
pulMembers; ESSG_PULONG_T Count of members being returned.
*ppszMembers; ESSG_PSTR_T Pointer to a one dimensional array of size pulMembers of members returned from
the server. The API allocates this memory and should be freed by the caller.
Notes
l pszMbrName cannot be null.
l Free the ppszMembers parameter using EssGFreeMemberInfo.
1102
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_GetMemberInfo(ESSG_HGRID_T hGrid)
{
ESSG_STR_T pszMbrName;
ESSG_SHORT_T sAction;
ESSG_BOOL_T bAliases;
ESSG_ULONG_T ulMembers, ind;
ESSG_PSTR_T pszMembers;
char tmp[5] = "Year";
pszMbrName = tmp;
sAction = ESSG_NEXTLEVEL;
bAliases = ESSG_FALSE;

/* get member information */

if(sts == 0)
sts = EssGGetMemberInfo(hGrid,pszMbrName, sAction, bAliases,
&ulMembers, &pszMembers);
if (sts == 0)
{
printf("\nNext Level of %s:\n", pszMbrName);
for (ind = 0; ind < ulMembers; ind++)
printf("\t%s\n", *(pszMembers + ind));
EssGFreeMemberInfo(hGrid, ulMembers, pszMembers);

}
if(!sts)
sts = EssGDisconnect(hGrid, 0);
}
See Also
EssGGetResults
Retrieves information about the data returned after an operation has been completed
(EssGBeginXxx, EssGSendRows, EssGPerformOperation).
1103
Syntax
ESSG_FUNC_M EssGGetResults (hGrid, ulOptions, pRangeOut, pState);
pRangeOut “ESSG_RANGE_T” on Describes the extent of the data returned from the server. This parameter
page 1030 describes the total amount of data that will be returned. The caller can break up
the retrieval with multiple calls to EssGGetRows.
pState ESSG_PUSHORT_T Variable for the return of the state of the operation. This can be one of the
following values:
l ESSG_STATE_DONE Operation complete
l ESSG_STATE_INPROGRESS The operation is in progress
Notes
After this call is made and the pState variable contains ESSG_STATE_DONE, the caller should
call EssGGetRows to retrieve the actual data from the server.
Return Value
Access
None.
Example
See Also
EssGGetRows
Retrieves data after an operation has been completed (EssGBegin, EssGSendRows,
EssGPerformOperation, EssGGetResults).
Syntax
ESSG_FUNC_M EssGGetRows (hGrid, ulOptions, pRangeRequested,
pRangeOut, pppDataOut);
1104
pRangeRequested “ESSG_RANGE_T” on page Describes the extent of the data requested. This can be less than or
1030 equal to the number of rows and columns returned from the
EssGGetResults call.
pRangeOut “ESSG_RANGE_T” on page Describes the extent of the data returned.

1030
*pppDataOut “ESSG_DATA_T” on page The address of a two-dimensional array of data. The memory for
1024 this array is allocated by the API and should be freed by the caller
using EssGFreeRows.
Notes
l You can make multiple calls to EssGGetRows, but the pRangeRequested->ulStartRow in each
subsequent call must be greater than the last row received.
l The pRangeRequested variable should define the rows desired to be returned. If multiple
buffers of data are being returned, each subsequent call to EssGGetRows should update the
rows in the pRangeRequested parameter.
l If the caller requests rows where some of the requested rows are valid, while others are out
of range, the valid rows will be filled in. The invalid rows remain undefined.
l If the caller requests rows that are completely out of range from the information that is
available, an error is returned.
Return Value
Access
None.
Example
See Also
EssGGetSmartlistforCell
Returns the name of SmartList (Text List) object associated with a cell when the cell type is
ESSG_DT_SMARTLIST.
1105
l An Essbase database can have multiple TextList objects and members.
l This API call lets you identify which TextList object a cell is associated with.
l You do not have to free returned pointers, as this is managed by the API.
l As the grid is stateless, names returned are valid until you perform an EssGEndOperation.
Syntax
ESS_FUNC_M EssGGetSmartlistforCell (hGrid, pData, *pSmartlistname)
hGrid ESSG_HGRID_T Grid handle
pData ESSG_PDATA_T Pointer to the cell ESSG_DATA_T structure of the cell.
*pSmartlistname ESSG_STR_T Pointer to name of the TextList object the cell is associated with
Return Value
l 0—If successful
See Also
l EssOtlPutSmartList
EssGInit
Initializes the Grid API.
Syntax
ESSG_FUNC_M EssGInit (pInitStruct, pHandle);
pInitStruct “ESSG_INIT_T” on page 1029 Pointer to a structure containing useful information for the EGAPI.
pHandle ESSG_PHANDLE_T Pointer to the handle sent back from the EGAPI.
Notes
l Required before calling all other EGAPI functions except for EssGVersion.
l Make this call only once at the beginning of a session.
l This function returns a handle, which you must pass to EssGNewGrid for each grid being
used, and to any other EGAPI call requiring a non-grid specific handle.
l A thread may require its own handle (pHandle) to avoid overwriting another thread's
networking status information.
1106
Return Value
Access
None.
Example

See Also
EssGLoginSetPass
Connects a grid to an Essbase database, and changes the user password.
Syntax
hGrid; ESSG_HGRID_T Handle from EssGNewGrid()
Server; ESSG_SERVER_T Name of a valid server
Username; ESSG_USERNAME_T Name of a valid user on the server
Password; ESSG_PASSWORD_T User's password
NewPassword; ESSG_PASSWORD_T User's new password
Return Value
Example
#include
#include
1107
{
ESSG_USERNAME_T UserName;
ESSG_PASSWORD_T NewPassword;
ESSG_HGRID_T hGrid;

if(!sts)
strcpy(Server, "Rainbow");
strcpy(UserName, "Admin");
strcpy(Password, "Password");
strcpy(Password, "NewPassword");

if(!sts)
sts = EssGLoginSetPass(hGrid, Server, UserName, Password, NewPassword);
}
See Also
l EssAutoLogin
l EssGConnect
l EssGInit
l EssInit
l EssLogout
EssGNewGrid
Initializes a specific grid.
Syntax
ESSG_FUNC_M EssGNewGrid (Handle, phGrid);
1108
Handle; /* IN */ ESSG_HANDLE_T Handle passed back from EssGInit.
phGrid; /* OUT */ ESSG_PHGRID_T Pointer to the grid-specific handle sent back from the EGAPI.
Notes
l This call is required prior to calling any grid-specific API.
l The handle returned should be passed to any subsequent grid-specific API call that
manipulates the specific grid.
l The call should be made once for each grid that uses the Grid API.
l Each thread in a multithreaded environment must use its own handle (phGrid) to call a grid-
specific API, such as EssGSendRows() or EssGBeginOperation().
Return Value
Access
None.
Example

ESSG_HGRID_T hGrid;

if(!sts)
See Also
1109
EssGPerformOperation
Performs an operation after all rows have been sent to the serve rusing EssGBeginXxx and
EssGSendRows.
Syntax
ESSG_FUNC_M EssGPerformOperation (hGrid, ulOptions);
hGrid; ESSG_HGRID_T Handle passed back from EssGNewGrid().
ulOptions; ESSG_ULONG_T Reserved for future use. Set to zero.
Notes
After this call is made, call EssGGetResults to get information about the data returned.
Return Value
Example
See an example that uses this code in the EssGBeginPivot Example section.
See Also
EssGSendRows
Sends the rows to the server once an operation has been started.
Syntax
ESSG_FUNC_M EssGSendRows (hGrid, pRangeIn, ppDataIn);
pRangeIn “ESSG_RANGE_T” on page 1030 Describes the extent of the data in ppDataIn.
ppDataIn “ESSG_DATA_T” on page 1024 A two-dimensional array of cells describing the data.
Notes
l You can make multiple calls to EssGSendRows, but the pRangeIn->ulStartRow in each
subsequent call must be greater than the last row sent in.
l The pRangeIn variable should define the rows in the grid.
1110
l If you are sending in multiple buffers of data, each subsequent call to EssGSendRows should
update the rows in the pRangeIn parameter.
l After all rows are sent in, you can call EssGPerformOperation.
Return Value
Access
None.
Example
See Also
EssGSetGridOption
Sets individual grid options.
Syntax
ESSG_FUNC_M EssGSetGridOption (hGrid, sOption, pOption);

Description
sOption ESSG_SHORT_T Value indicating what option is being set. For a table of valid values, see Notes.
pOption ESSG_PVOID_T Value of option being set cast to an ESSG_PVOID_T.
Notes
l You can use the ESSG_OP_USERGRIDDATA pointer to store grid-specific information
that is private to the application.
l The following table lists valid options for sOption and the corresponding description and
data type:
Value Description Data Type Expected Default
ESSG_OP_ALIASNAMES Alias names ESSG_BOOL_T ESSG_FALSE
ESSG_OP_ALIASTABLE Alias names table ESSG_STR_T
ESSG_OP_DATALESS Enable dataless navigation. ESSG_BOOL_T ESSG_FALSE
1111
Value Description Data Type Expected Default
ESSG_OP_DRILLLEVEL Drill-level ESSG_SHORT_T ESSG_NEXTLEVEL
ESSG_OP_EMPTYGRIDERROR If FALSE, don't issue error on queries which ESSG_BOOL_T ESSG_TRUE

result in no data and return only the grid
header.
ESSG_OP_INCSEL Include selection ESSG_BOOL_T ESSG_FALSE
ESSG_OP_INDENT Indent style ESSG_SHORT_T ESSG_INDENTTOTALS
ESSG_OP_LATEST Turn on the ability to specify the latest ESSG_BOOL_T ESSG_FALSE

member.
ESSG_OP_LATESTMEMBER Specify the latest member. ESSG_STR_T NULL
ESSG_OP_REPEATMBRNAMES Repeat member names. ESSG_BOOL_T ESSG_FALSE
ESSG_OP_RETAINTHREAD If set to TRUE, don't disconnect from server ESSG_BOOL_T ESSG_FALSE

thread at end of grid operation. May improve
performance when submitting several
operations in sequence.
ESSG_OP_SELGROUP Remove Unselected Groups. Zooms on all ESSG_BOOL_T ESSG_FALSE

occurrences of selected member but removes
any other members from the same
dimension, including the selected member
itself.
ESSG_OP_SELONLY Within Selected Group. Zooms on only the ESSG_BOOL_T ESSG_FALSE

exact instance of the member that is selected.
ESSG_OP_SUPMISSING Suppress missing rows. ESSG_BOOL_T ESSG_FALSE
ESSG_OP_SUPUNDER Replace underscores with spaces. ESSG_BOOL_T ESSG_FALSE
ESSG_OP_SUPZEROS Suppress zero rows. ESSG_BOOL_T ESSG_FALSE
ESSG_OP_UPDATEMODE Update mode ESSG_BOOL_T ESSG_FALSE
ESSG_OP_USEBOTHFORROWDIMS Use both member names and aliases for the ESSG_BOOL_T ESSG_FALSE
row dimensions.
ESSG_OP_USERGRIDDATA Pointer to user data ESSG_PVOID_T NULL
ESSG_OP_RETAINTHREAD Retain threads ESSG_BOOL_T ESSG_FALSE
ESSG_OP_EMPTYGRIDERROR Issue an empty grid error ESSG_BOOL_T ESSG_FALSE
ESSG_OP_DATALESS Navigate without data ESSG_BOOL_T ESSG_FALSE
Return Value
1112
Example
ESSG_VOID_T ESSG_SetGridOption (ESSG_HGRID_T hGrid)
{
ESSG_SHORT_T sOption;
ESSG_SHORT_T tmpShort;
ESSG_PVOID_T pOption;

tmpShort = 2;
sOption = ESSG_OP_DRILLLEVEL;
pOption = (ESSG_PVOID_T)tmpShort;
/* set grid option */

if(!sts)
if(!sts)
}
See Also
EssGSetGridPerspective
This function sets perspective for a grid. Perspective is similar to grid option. If the set perspective
is valid, the grid context is the same.
Syntax
ESSG_FUNC_M EssGSetGridPerspective(hGrid, sAttrdim, sPerspectiveType,
pPerspectiveString)
sAttrdim ESSG_STR_T Attribute dimension name for which perspective has to set
sPerspectiveType ESSG_SHORT_T Type of perspective. See “Grid Perspective Types” on page 1021.
1113
pPerspectiveString ESSG_STR_T pPerspectiveString (m1,m2,m3,.....)
This is perspective tuple which should be applied for the given attribute
dimension. Level-0 members from one or more "Independent" dimensions (for
attrDim) will be the part of the input tuple.
If a member from one "independent" dimension is not present in the perspective
tuple, the member of the same dimension from the current query/calculation
context will be used.
In case of an explicit perspective missing for an attribute dimension, the default
usage for perspective is ESSG_PERSP_REALITY. This argument can be NULL
for sPerspectiveType other than ESSG_PERSP_EXPLICIT, which requires a
valid tuple.
Return Value
l 0—If successful
See Also
l EssGGetGridPerspective
EssGSetPath
Sets the ESSBASEPATH environment variable for the current process.
Syntax
ESSG_FUNC_M EssGSetPath (pszPath);
pszPath; ESSG_STR_T Pointer to the string describing the ESSBASEPATH environment variable
Notes
l Call EssGSetPath() before calling EssGInit().
l pszPath cannot exceed 120 characters, as defined in ESSG_PATHLEN.
l pszPath applies only to the current process.
l Essbase DLLs must be accessible from the system path. EssGSetPath() does not resolve the
path for the Essbase DLLs.
Return Value
l If successful, returns ESSG_STS_NOERR.
l If pszPath is too long, returns API_NAME_TOO_LONG (1030009).
1114
Example
ESS_STS_T
ESSG_SetPath(ESS_STR_T pszPath)
{
ESS_STS_T sts
ESSG_STR_T pszPath = "C:\Hyperion\products\Essbase";
sts = EssGSetPath (pszPath);
return sts;
}
See Also
EssGTerm
Terminates the Grid API.
Syntax
ESSG_FUNC_M EssGTerm (Handle);
Handle ESSG_HANDLE_T Handle to instance of the EGAPI.
Notes
l This call is required.
l Signifies termination of use of the Grid API.
l This call should be made only once per session and then only at the end of that session.
Return Value
Access
None.
Example

1115
/* initialize EGAPI */
/* terminate the EGAPI */

if(!sts)
See Also
EssGUnlock
Unlocks any blocks that were locked at the server.
Syntax
ESSG_FUNC_M EssGUnlock (hGrid, ulOptions);
Return Value
Access
None.
Example
ESSG_VOID_T ESSG_Unlock(ESSG_HGRID_T hGrid)
{
ESSG_ULONG_T ulOptions = 0;

/* unlock the locked blocks at server */

if(!sts)
sts = EssGUnlock(hGrid, ulOptions);
if(!sts)
1116
See Also
EssGUpdateLRO
Updates the description and contents of a linked object.
Syntax
ESSG_FUNC_M EssGUpdateLRO (hGrid, hLRO, pLroDesc, ulOption);
hLRO; ESSG_HLRO_T Handle to the linked object (returned in a DRILLDATA structure by the
pLroDesc; “ESSG_LRODESC_T” on A structure containing information about the LRO to be updated.

page 1029
ulOption; ESSG_ULONG_T Option specifying whether to store the object on the server. Use
ESS_STORE_OBJECT_API to store winapp and URL objects on the server.
Use ESS_NOSTORE_OBJECT_API to store cell notes off the server (and in
the index file).
Return Value
See Also
l EssGDeleteLRO
l EssGGetLRODesc
EssGVersion
Returns the version number for the API.
Syntax
ESSG_FUNC_M EssGVersion (pulVersion);
pulVersion ESSG_PULONG_T Pointer to the current version number of the Grid API.
1117
Notes
l The number is incremented whenever changes requiring either a recompile or relink by a
client occur.
l You do not need to initialize the Grid API before you use this function.
Return Value
Access
None.
Example

ESSG_ULONG_T ulVersion;
/* get version number for the API */

sts = EssGVersion(&ulVersion);
See Also
1118
C Grid API Examples
16
In This Chapter
C Grid API Example .................................................................................... 1119
C Grid API Drill-Through Example ..................................................................... 1123
ESSG_OP_MEMBERANDUNIQUENAME Example ................................................... 1125
ESSG_DT_MEMBERwKEY Example ................................................................... 1127
BuildTable Example Function ......................................................................... 1129
DisplayOutput Example Function ..................................................................... 1130
FreeTwoDim Example Function ....................................................................... 1132
C Grid API Example

This example illustrates the steps needed to perform a basic retrieval. The following grid shows
a five dimensional template with one datapoint illustrated.
The following code fragment shows how the data structures are setup and the function calls that
are needed to perform the retrieval.
/* This function allocates the necessary data to send to the server */
ESSG_PPDATA_T AllocTwoDims(ESSG_ULONG_T ulRows, ESSG_ULONG_T ulCols)

{
ESSG_PPDATA_T ppTemp;
ESSG_ULONG_T ulIndex;
if(ulRows)
ppTemp = (ESSG_PPDATA_T) malloc(sizeof(ESSG_DATA_T*) * ulRows);
if(ppTemp == NULL)
return ppTemp;
memset(ppTemp, 0, (sizeof(ESSG_PDATA_T) * ulRows));
for (ulIndex = 0; ulIndex < ulRows; ulIndex++)

{
ppTemp[ulIndex] = (ESSG_PDATA_T)malloc(sizeof(ESSG_DATA_T) * ulCols);
if(ppTemp[ulIndex])
memset(ppTemp[ulIndex], 0, (sizeof(ESSG_DATA_T) * ulCols));
}
1119
return ppTemp;
}
/* This function frees the memory allocated by AllocTwoDims */

void FreeTwoDim(ESSG_PPDATA_T ppDataToFree, ESS_ULONG_T ulRows)
{
ESS_ULONG_T ulIndex;

{
if(ppDataToFree[ulIndex]->usType == ESSG_DT_STRING)
{
free(ppDataToFree[ulIndex]->Value.pszStr);
}
free(ppDataToFree[ulIndex]);
}
free(ppDataToFree);
}
/* This function builds a table based on the above grid. */

/* Note: The items in the grid are hard coded. */
ESSG_PPDATA_T BuildTable(ESSG_PRANGE_T pRange)
{
ESSG_PPDATA_T ppTable;
ESS_ULONG_T ulRow, ulCol;
/* Your code would probably not be hard-coded here... */

pRange->ulRowStart = 0;
pRange->ulColumnStart = 0;
pRange->ulNumRows = 2;
pRange->ulNumColumns = 5;
ppTable = AllocTwoDims(2, 5);
/* ROW 1 */
ppTable[0][0].usType = ESSG_DT_BLANK;
ppTable[0][2].usType = ESSG_DT_STRING;
/* Some compilers allow you to specify \p to indicate */
/* the length of the string */
ppTable[0][2].Value.pszStr = "\pYear";
ppTable[0][3].Value.pszStr = "\pProduct";
ppTable[0][4].Value.pszStr = "\pMarket";
/* ROW 2 */
ppTable[1][0].Value.pszStr = "\pActual";
ppTable[1][1].Value.pszStr = "\pSales";
ppTable[1][2].usType = ESSG_DT_DOUBLE;
ppTable[1][2].dblData = 123.45;
1120
return (ppTable);
}
/* This function makes the necessary calls to the */

/* EGAPI to perform a basic retrieval. */
/* NOTE: This example does not show the */
/* initialization of the EGAPI or the grid. */
/* Also, the hGrid is assumed to be external. */
void CallEGAPI(void)
{
ESSG_PPDATA_T ppDataIn,
ESSG_RANGE_T rRangeDataIn,rRangeDataOut;
ESSG_STS_T sts;
ESSG_ULONG_T ulRow, ulCol;
/* Connect the grid to a database on the server */

sts = EssGConnect(hGrid, "Server", "User", "Password",
"App", "Db", ESSG_CONNECT_DEFAULT);
if (sts == 0)
{
ppDataIn = BuildTable(rRangeDatain);
/* Start the retrieve operation */
sts = EssGBeginRetrieve(hGrid, ESSG_RET_RETRIEVE);
}
if (sts == 0)
{
/* Send the entire grid to define the query */
sts = EssGSendRows(hGrid, rRangeDatain, ppDataIn);
}
if (sts == 0)
{
/* We're done sending rows, perform the retrieval */
/* Free the data we built */

FreeTwoDim(ppDataIn, rRangeDataIn.ulNumRows);
}
if (sts == 0)
{
/* Determine the results of the retrieve and how much data
* is being returned.
*/
sts = EssGGetResults(hGrid, 0, rRangeDataOut, usState);
}
if (sts == 0)
{
/* Get all of the data */
sts = EssGGetRows(hGrid,0, rRangeDataOut,
rRangeDateOut, ppDataOut);
}
if (sts == 0)
{
/* Interate though the data ... */
/* First the rows */
for (ulRow = rRangeDataOut.ulRowStart;
1121
ulRow < rRangeDataOut.ulNumRows;
ulRow++)
{
/* Then the columns */
for (ulCol = rRangeDataOut.ulColumnStart;
ulCol < rRangeDataOut.ulNumColumns;
ulCol++)
{
/* Here's a cell ... just render it. */
switch (ppDataOut[ulRow][ulCol].usType)
{
case (ESSG_DT_STRING):
DisplayString(ppDataOut[ulRow]
[ulCol].Value.pszStr);
break;
case (ESSG_DT_LONG):
DisplayValue(ppDataOut[ulRow]
[ulCol].Value.lData);
break;
case (ESSG_DT_DOUBLE):
DisplayValue(ppDataOut[ulRow]
[ulCol].Value.dblData);
break;
case (ESSG_DT_BLANK):
DisplayBlank();
break;
case (ESSG_DT_MISSING):
DisplayMissing();
break;
case (ESSG_DT_ZERO):
DisplayValue(0);
break;
case (ESSG_DT_NOACCESS):
DisplayNoAccess();
break;
case (ESSG_DT_MEMBEREX):
DisplayString(ppDataOut[ulRow]
[ulCol].Value.pszStr+1);
break;
default:
DisplayOops();
break;
}
}
}
/* Tell the API we don't care about this request any more */
/* Free the data returned */
EssGFreeRows(hGrid, rRangeDataOut, ppDataOut);
}
/* Disconnect if you wish */

1122
C Grid API Drill-Through Example
void main(int argc, char *argv[])
{
ESSG_HGRID_T hGrid;
/* BEGIN: initialize grid handle and create a new grid */


if (sts != ESS_STS_NOERR)
return;
sts = EssGNewGrid(Handle, hGrid);

if (sts != ESS_STS_NOERR)
return;
/* END: initialize grid handle and create a new grid */
ESSG_DTTest(Handle, hGrid);
}
void ESSG_DTTest(ESSG_HANDLE_T Handle, ESSG_HGRID_T hGrid)

{
ESSG_STS_T errsts,
sts = ESS_STS_NOERR;
ESSG_HLRO_T hLRO = 0;
/* ESSG_PPDATA_T ppDataOut; */
ESSG_RANGE_T rDataRangeIn,
rDataRangeOut;
ESSG_USHORT_T usState = 0;
ESSG_RANGE_T Range;
ESSG_PDTHINST_T pDTInst;
ESSG_STR_T ErrMesg;
ESSG_ULONG_T ErrSize = 255;
memset(&rDataRangeOut, 0, sizeof(ESSG_RANGE_T));
ErrMesg = malloc(255);

sts = EssGConnect(hGrid, server, user, pwd, app, db, ESSG_CONNECT_DEFAULT);
if(sts == ESS_STS_NOERR)
{
ppDataIn = BuildTableForDrillThru (&rDataRangeIn);
1123
usCells = 1;
Range.ulRowStart = 1;
Range.ulColumnStart = 6;
Range.ulNumRows = 1;
Range.ulNumColumns = 1;
sts = EssGBeginDrillOrLink(hGrid, usCells, &Range, ESSG_OPT_ZOOM);
{
/* perform the drillorlink operation */

}
if (sts ==ESS_STS_NOERR)
sts = EssGDTRequestDrillThrough(hGrid, usCells, &Range, &pDTInst);
{
/* Get the DT Info corresponding to the DT handle */
sts = ESSGDTGetInfo(pDTInst);
/* Set the password info for executing the drill through report */
sts = ESSGDTSetInfo(pDTInst);
/* determine the list of reports associated with the data cell range. */
sts = ESSGDTListReports(pDTInst);
/* Execute the report. Using index 0 for now as we have only one report
*/
sts = EssGDTExecuteReport(pDTInst, 0);
if ( sts ) /* Error Condition print error mesg */
errsts = EssDTAPIGetError(pDTInst, &sts, ErrMesg, ErrSize);
/* Get the headers for the report associated with the data cell range.
*/
sts = ESSGDTGetHeader(pDTInst);
EssDTAPIGetError(pDTInst, &sts, ErrMesg, ErrSize);
/* Get the data for the report associated with the data cell range. */
sts = ESSGDTGetData(pDTInst);
EssDTAPIGetError(pDTInst, &sts, ErrMesg, ErrSize);
}
1124
sts = EssGDTEndDrillThrough(pDTInst);
}
See the following functions for more information on Drill-Through:

EssGDTConnect
EssGDTEndDrillThrough
EssGDTExecuteReport
EssGDTGetData
EssGDTGetHeader
EssGDTGetInfo
EssGDTListReports
EssGDTRequestDrillThrough
EssGDTSetInfo
ESSG_OP_MEMBERANDUNIQUENAME Example
The following example illustrates the use of the Grid API constant
ESSG_OP_MEMBERANDUNIQUENAME.
{



1125
if(!sts)
{
(int)tmpShortGet);
}
if(sts == 0)
{
usCells = 1;

}
//Display Input
printf("\n\n");
if(sts == 0)
if(sts == 0)
{

}
if (sts == 0)
{
}
if(sts ==0)
{
}
if(sts == 0)
{
1126
pMember+2,
pKey+2);

//nn<member-name>nn<key> - where nn is string length




if( sts == 0)
{
}
}
ESSG_DT_MEMBERwKEY Example
The following example illustrates the use of the Grid API constant ESSG_DT_MEMBERwKEY.
Note: DisplayOutput is a function that is called below in ESSG_BeginZoomIn.
1127
ESSG_VOID_T DisplayOutput(ESSG_PPDATA_T ppDataOut, ESSG_RANGE_T pRangeOut)
{
ESSG_ULONG_T RowIndex, ColumnIndex;
for (RowIndex = 0; RowIndex < pRangeOut.ulNumRows; RowIndex++)
{
for (ColumnIndex = 0; ColumnIndex < pRangeOut.ulNumColumns; ColumnIndex++)
{
switch(ppDataOut[RowIndex][ColumnIndex].usType)
{
printf("%s", ppDataOut[RowIndex][ColumnIndex].Value.pszStr+1);
break;
case(ESSG_DT_LONG):
printf("%ld", ppDataOut[RowIndex][ColumnIndex].Value.lData);
break;
printf("%g", ppDataOut[RowIndex][ColumnIndex].Value.dblData);
break;
break;
break;
printf("#Error");
break;
printf("#Missing");
break;
case(ESSG_DT_ZERO):
printf("%ld", ppDataOut[RowIndex][ColumnIndex].Value.lData);
break;
break;
break;
case(ESSG_DT_MEMBERwKEY):
printf(" (Key = %s)", ppDataOut[RowIndex][ColumnIndex].Value.pszStr+5+
strlen(ppDataOut[RowIndex][ColumnIndex].Value.pszStr+2));
break;
default:
break;
}
if (ColumnIndex < pRangeOut.ulNumColumns - 1)
{
printf(",");
}
}
printf("\n");
}
printf("\n");
printf("\n");
}
1128
BuildTable Example Function
The following function examples call this example function:
...
ESSG_PPDATA_T BuildTable (ESSG_PRANGE_T pRange)
{
ESSG_PPDATA_T ppTable;
ESSG_STR_T current_str;
ESSG_USHORT_T slen = 0;
pRange->ulRowStart = 0;
pRange->ulColumnStart = 0;
pRange->ulNumRows = 2
pRange->ulNumColumns = 5;
ppTable = AllocTwoDims(2, 5);
/* ROW 1 */
slen = strlen("Year");
current_str = malloc(sizeof(ESSG_CHAR_T)*(slen+2));
*current_str = slen;
strcpy( (current_str + 1), "Year");
ppTable[0][2].Value.pszStr = current_str;
slen = strlen("Product");
strcpy( (current_str + 1), "Product");
slen = strlen("Market");
strcpy((current_str + 1), "Market");
/*** ROW 2 ***/

slen = strlen("Actual");
strcpy((current_str + 1), "Actual");
slen = strlen("Sales");
strcpy( (current_str + 1), "Sales");
1129
ppTable[1][2].usType = ESSG_DT_DOUBLE;
ppTable[1][2].Value.dblData = 123.45;
return (ppTable);
}
DisplayOutput Example Function

The following function examples call this example function:
ESSG_VOID_T DisplayOutput(
ESSG_HGRID_T hGrid,
ESSG_PPDATA_T ppDataOut,
ESSG_RANGE_T pRangeOut)
{
if (!ppDataOut)
{
printf("Data area is empty !\n");
return;
}
ESSG_ULONG_T RowIndx, ColIndx;

printf
("---- Row: %d Column: %d startRow: %d, startColumn: %d\n",
pRangeOut.ulNumRows,
pRangeOut.ulNumColumns,
pRangeOut.ulRowStart,
pRangeOut.ulColumnStart);
for(RowIndx = 0; RowIndx < pRangeOut.ulNumRows; RowIndx++)

{
for (ColIndx = 0; ColIndx < pRangeOut.ulNumColumns; ColIndx++)
{
switch(ppDataOut[RowIndx][ColIndx].usType)
{
printf("%s", ppDataOut[RowIndx][ColIndx].Value.pszStr+1);
break;
case(ESSG_DT_LONG):
printf("%ld",ppDataOut[RowIndx][ColIndx].Value.lData);
break;
printf("%g", ppDataOut[RowIndx][ColIndx].Value.dblData);
break;
break;
break;
1130
printf("#Error");
break;
printf("#Missing");
break;
case(ESSG_DT_ZERO):
printf("%ld", ppDataOut[RowIndx][ColIndx].Value.lData);
break;
break;
break;
case(ESSG_DT_STRINGEX):
case(ESSG_DT_MEMBEREX):
break;
case ESSG_DT_SMARTLIST:
{
ESSG_STR_T val = 0;
printf("SmartList");
EssGGetFormattedValue(hGrid,&ppDataOut[RowIndx][ColIndx],&val);
if(val)printf("-%s",val);
EssGGetSmartlistforCell (hGrid,&ppDataOut[RowIndx][ColIndx],&val);
if(val)printf("Name -%s",val);
}
break;
case ESSG_DT_DATE:
{
ESSG_STR_T val = 0;
printf("Date");
EssGGetFormattedValue(hGrid,&ppDataOut[RowIndx][ColIndx],&val);
if(val)printf("-%s",val);
}
break;
case ESSG_DT_MNGLESS:
printf("MeaningLess");
break;
default:
break;
}
printf("(%d, %x)",ppDataOut[RowIndx][ColIndx].usType, ppDataOut[RowIndx]
[ColIndx].pAttributes);
if (ColIndx < pRangeOut.ulNumColumns - 1)
1131
printf(",");
}
printf("\n");
}
}
FreeTwoDim Example Function

ESSG_VOID_T FreeTwoDim(ESSG_PPDATA_T ppDataToFree,
ESSG_ULONG_T ulRows)
{
ESSG_ULONG_T ulIndex;

{
if (ppDataToFree[ulIndex]->usType == ESSG_DT_STRING)
{
free(ppDataToFree[ulIndex]->Value.pszStr);
}
free(ppDataToFree[ulIndex]);
}
free(ppDataToFree);
}
delete
1132
C Grid API Error Codes
17
The C Grid API returns three types of error codes:
l Success—API returns a zero value
l Server error—API returns a very large number. These numbers are described in the file
esserror.h
l API error—API returns numbers beginning with 1100001. These values are defined in the
Grid API C language header file essgapi.h.
If you provide a valid Error Function callback when you initialize the Grid API, this callback is
called for all EGAPI errors if a valid hGrid is passed. The Error Function can in turn stop the
default error handling user interface provided within EGAPI by returning zero (0). If a non-zero
value is returned from the Error Function, or no Error Function is provided, EGAPI uses the
system specific user interface to display the error message.
The following table describes the error status constants returned when a Grid API call fails.
Error Code Value
ESSG_ERR_INITREQUIRED 1100001
ESSG_ERR_CONNECTREQUIRED 1100002
ESSG_ERR_INVALIDHANDLE 1100003
ESSG_ERR_INVALIDGRID 1100004
ESSG_ERR_CANNOTINIT 1100005
ESSG_ERR_CANNOTCONNECT 1100006
ESSG_ERR_CANNOTCREATEGRID 1100007
ESSG_ERR_INVALIDVERSION 1100008
ESSG_ERR_CANNOTGETAPIINST 1100009
ESSG_ERR_CANNOTGETAPICTX 1100010
ESSG_ERR_INVALIDOPTION 1100011
ESSG_ERR_INVALIDRANGE 1100012
ESSG_ERR_INVALIDDATA 1100013
1133
Error Code Value
ESSG_ERR_INVALIDROWORCOLMAX 1100014
ESSG_ERR_NULLARGUMENT 1100015
ESSG_ERR_CELLSREQUIRED 1100016
ESSG_ERR_RANGEREQUIRED 1100017
ESSG_ERR_INVALIDACTION 1100018
ESSG_ERR_INVALIDGRIDOPTION 1100019
ESSG_ERR_INVALIDFUNCTION 1100020
ESSG_ERR_MEMORY 1100021
ESSG_ERR_INVALIDROW 1100022
ESSG_ERR_INVALIDCOLUMN 1100023
ESSG_ERR_INVALIDPARM 1100024
ESSG_ERR_INVALIDCSLVERSION 1100025
ESSG_ERR_RANGEOVERLAP 1100026
ESSG_ERR_OPERATIONFAILED 1100027
ESSG_ERR_CANNOTSETOPTION 1100028
ESSG_ERR_INVALIDOPTIONVALUE 1100029
ESSG_ERR_EMPTYARGUMENT 1100030
ESSG_ERR_INVALIDLROHANDLE 1100031
ESSG_ERR_NOLROSAVAILABLE 1100032
ESSG_ERR_INVALIDLROTYPE 1100033
ESSG_ERR_GCINITFAIL 1100034
ESSG_ERR_GCSETLOCALEFAIL 1100035
1134
Part V
Other APIs
In Other APIs:
l Java API Reference

l MDX Provider API
l Welcome to XMLA Reference
l Working with XMLA
1135
1136
Java API Reference
18
The Java API documentation is included as Javadocs in the Oracle Hyperion Provider Services
installation, at EPM_ORACLE_INSTANCE\common\docs\en\aps, as well as at
EPM_ORACLE_INSTANCE\common\EssbaseAPI\release\docs\en\aps. You can also find
the Essbase Java API Reference on the Oracle Technology Network.
1137
1138
MDX Provider API
19
In This Chapter
MDX Provider API General Information............................................................... 1139
MDX Provider API Reference .......................................................................... 1141
MDX Sample Client Program .......................................................................... 1160
MDX Provider API General Information

MDX queries that follow the grammar given in the MDX functional specification can be
submitted to the server through the MDX-API. The query results can then be retrieved by the
client using this API.
The grammar of MDX statements is covered in the MDX section of the Oracle Essbase Technical
Reference.
A few basic MDX concepts and terminology are reviewed here. An MDX query consists of several
axis specifications, and an optional slicer specification. Each axis specifies a set-valued
expression. A set is an ordered collection of tuples, with tuples being a sequence of members
from one or more dimensions. Tuples in a set are homogeneous in dimensionality (each tuple
has members from the same dimensions in the same order).
An example of a set expression based on the Sample Basic database is:
Union(
CrossJoin({[Sales], [Profit]}, {[Actual], [Budget]}),
Union(
CrossJoin([Total Expenses].Children, {[Actual]}),
{([Opening Inventory], [Variance]), ([Additions], [Variance %])}
)
)
This expression uses several MDX functions: Union, CrossJoin, and Children. The value of this
expression is the set:
{
([Sales], [Actual]),
([Sales], [Budget]),
([Profit], [Actual]),
([Profit], [Budget]),
([Marketing], [Actual]),
([Payroll], [Actual]),
([Misc], [Actual]),
([Opening Inventory], [Variance]),
1139
([Additions], [Variance %])
}
Note that in the result of the CrossJoin, the tuples are ordered so that the first dimension changes
slowest. The tuples in this set have the dimensionality: ([Measures],[Scenario]). The
dimensionality of tuples across axis sets must not overlap.
In addition to the set expression, each axis specifies the name of the axis (COLUMNS, ROWS,
PAGES, etc.) or the axis number (AXIS(0), AXIS(1), etc.). The cube consisting of all possible
combinations of tuples, one from each axis, constitutes the result of the query. Dimensions that
are not present in any axis and in the slicer default to having their root member included in
defining the result cube. The slicer, if present, specifies a set, with a single tuple, which identifies
the members of interest along the respective dimensions. This makes the final result a slice of
the cube created from the axes. The result of an MDX query contains the metadata about each
axis and the slicer, as well as the data values in the cells in the result cube.
Here is a complete MDX query:
SELECT
Union(
CrossJoin({[Sales], [Profit]}, {[Actual], [Budget]}),
Union(
CrossJoin([Total Expenses].Children, {[Actual]}),
{([Opening Inventory], [Variance]), ([Additions], [Variance %])}
)
) ON COLUMNS,
CrossJoin(
[200].Children,
{[East], [West]}
) ON ROWS
FROM
Sample.Basic
WHERE
{[Jan]}
The result of this query has 9 tuples on the column axis and 8 tuples on the row axis, which
means there are 72 cells in all. Each cell has an ordinal, or offset, which depends on the position
of its tuples along each axis. Offsets and positions start at 0. The cells are ordered so that the first
axis position changes the fastest.
For example, the cell identified by tuple 3 in the column axis and tuple 4 in the row axis is at
offset 3 + 9*4 = 39.
l Tuple 3 in the column axis is ([Profit], [Budget]).
l Tuple 4 in the row axis is ([200-30], [East]).
l Cell 39 is therefore ([Profit], [Budget], [200-30], [East], [Jan]).
The concept of clusters is needed for reasons of efficiency. A set can be considered to be an
ordered collection of tuples, or it can be considered to be an ordered collection of clusters. A
cluster is a collection of tuples that involve all possible combinations of certain members from
each of the set's dimensions. The tuples need to ordered in the same manner as in the output of
the CrossJoin function (the first dimension changes the slowest). Use of the CrossJoin function
1140
causes clusters to be created, but the server may determine clusters from the results of other
functions as well.
MDX Provider API Reference

The C API for MDX query processing is designed to fit in with the existing Essbase APIs. Client
programs are given handles to various structures internal to the API, and use methods to access
their components. The number of functions is kept small by judicious combining of output
results normally needed together. Except where noted, memory allocated by the API for its
internal structures is freed when the client invokes the query free function. ESS_MDX is the
prefix used for the handle types, and EssMdx is the prefix used for the functions introduced by
the MDX-API.
MDX Provider Declarations

The type definitions are as follows:
typedef void *ESS_MDX_QRYHDL_T; /* MDX query handle */
typedef unsigned long ESS_MDX_MEMBERIDTYPE_T; /* MDX mbr id type */
typedef void *ESS_MDX_AXISHDL_T; /* MDX axis handle */
typedef void *ESS_MDX_DIMHDL_T; /* MDX dim handle */
typedef unsigned long ESS_MDX_PROPTYPE_T; /* MDX property type */
typedef void *ESS_MDX_PROPHDL_T; /* MDX property handle */
typedef void *ESS_MDX_CLUSTERHDL_T; /* MDX cluster handle */
typedef void *ESS_MDX_MBRHDL_T; /* MDX mbr handle */
typedef void *ESS_MDX_CELLHDL_T; /* MDX cell handle */
typedef unsigned long ESS_MDX_CELLSTATUS_T; /* MDX cell status */
The constant definitions are as follows:

/* MDX member identifier types (ESS_MDX_MEMBERIDTYPE_T) */
#define ESS_MDX_MEMBERIDTYPE_NAME 8
#define ESS_MDX_MEMBERIDTYPE_ALIAS 16
/* MDX property value types (ESS_MDX_PROPTYPE_T) */

#define ESS_MDX_PROPTYPE_BOOL ESS_DT_BOOL
#define ESS_MDX_PROPTYPE_DOUBLE ESS_DT_DOUBLE
#define ESS_MDX_PROPTYPE_DATETIME ESS_DT_DATETIME
#define ESS_MDX_PROPTYPE_STRING ESS_DT_STRING
#define ESS_MDX_PROPTYPE_ULONG ESS_DT_ULONG
#define ESS_MDX_PROPTYPE_NONE 0
/* MDX cell status bitmasks (ESS_MDX_CELLSTATUS_T) */

#define ESS_MDX_CELLSTATUS_LINKEDOBJS 0x00000001
#define ESS_MDX_CELLSTATUS_DYNCALC 0x00000002
#define ESS_MDX_CELLSTATUS_CALCEDMBR 0x00000004
#define ESS_MDX_CELLSTATUS_READONLY 0x00000008
/* MDX cell property bitmasks (ESS_MDX_CELLPROP_T) */

#define ESS_MDX_CELLPROP_GLDRILLTHRU 0x00000008
ESS_MDX_PROPVALUE_T
1141
typedef struct ess_mdx_propvalue_t
{
ESS_MDX_PROPTYPE_T ulPropType; /* ESS_MDX_PROPTYPE_XXXX */
union
{
ESS_BOOL_T bData; /* Boolean value */
ESS_ULONG_T ulData; /* Ulong value */
ESS_STR_T strData; /* String value */
ESS_DATETIME_T dtData; /* Datetime value */
ESS_DOUBLE_T dblData; /* Double value */
} value;
} ESS_MDX_PROPVALUE_T;
ESS_MDX_CELLVALUE_T
typedef struct mdxcellvalue
{
ESS_DOUBLE_T dblVal;
ESS_STR_T fmtVal;
ESS_STR_T fmtStr;
ESS_USHORT_T smId;
ESS_USHORT_T type;
ESS_ULONG_T flags; // captures drill through property.
} ESS_MDX_CELLVALUE_T;
EssMdxExecuteQuery
Executes the specified query on the currently connected database.
Syntax
ESS_FUNC_M EssMdxExecuteQuery(
ESS_MDX_QRYHDL_T hQry);
Parameter Type Description
hQry input Query handle
Notes
Before calling this function, you must first create an MDX query by calling EssMDXNewQuery.
EssMdxFreeQuery
Frees memory used for the specified query.
Syntax
ESS_FUNC_M EssMdxFreeQuery(
1142
EssMdxGetAxes
Returns information about the axes in the query.
To obtain information on the nature of the axes in the submitted query, use the following APIs
after calling “EssMdxExecuteQuery” on page 1142:
l “EssMdxGetAxes” on page 1143
l “EssMdxGetAxisInfo” on page 1143
l “EssMdxGetDimInfo” on page 1149
Note: This function returns zero if a non-existing member name is in the slicer of a query.
Syntax
ESS_FUNC_M EssMdxGetAxes(
ESS_MDX_QRYHDL_T hQry,
ESS_PULONG_T pulNAxes,
ESS_MDX_PPAXISHDL_T pphAxes,
ESS_MDX_PAXISHDL_T phSlicer);
pulNAxes output Number of axes
pphAxes output Array of axis handles
phSlicer output Slicer axis handle
EssMdxGetAxisInfo
Returns information about the specified axis.
To obtain information on the nature of the axes in the submitted query, use the following APIs
after calling “EssMdxExecuteQuery” on page 1142:
l “EssMdxGetAxes” on page 1143
l “EssMdxGetAxisInfo” on page 1143
l “EssMdxGetDimInfo” on page 1149
1143
Syntax
ESS_FUNC_M EssMdxGetAxisInfo(
ESS_MDX_AXISHDL_T hAxis,
ESS_PULONG_T pulSize,
ESS_PULONG_T pulNDims,
ESS_MDX_PPDIMHDL_T pphDims);
hAxis input Axis handle
pulSize output Number of tuples in axis
pulNDims output Number of dimensions in axis
pphDims output Array of dimension handles
EssMdxGetAxisMembers
Returns the tuple at the specified position in the given axis. Use this function to directly retrieve
a particular tuple from an axis.
Note: The client should use EssFree() when done with pphMbrs.
To obtain information about the contents of an axis set, use the following APIs:
l “EssMdxGetClusters” on page 1149
l “EssMdxGetClusterInfo” on page 1147
l “EssMdxGetClusterMembers” on page 1148
l “EssMdxGetAxisMembers” on page 1144
l “EssMdxGetMbrIdentifier” on page 1151
l “EssMdxGetMbrProperty” on page 1151
Syntax
ESS_FUNC_M EssMdxGetAxisMembers(
ESS_ULONG_T ulIndex,
ESS_MDX_PPMBRHDL_T pphMbrs);
ulIndex input Tuple position within axis
pphMbrs output Array of member handles for tuple
1144
EssMdxGetCellAtIndices
Returns the cell at the intersection of the specified tuple indices.
To obtain the cell values in the cube formed from the axes in the query, use the following APIs:
l “EssMdxGetCellAtOffset” on page 1145
l “EssMdxGetCellAtIndices” on page 1145
l “EssMdxGetValue” on page 1155
Syntax
ESS_FUNC_M EssMdxGetCellAtIndices(
ESS_PULONG_T pulIndices,
ESS_MDX_PCELLHDL_T phCell);
pulIndices input Tuple indices, one for each axis
phCell output Cell handle
EssMdxGetCellAtOffset
Returns the cell at the specified offset.
Syntax
ESS_FUNC_M EssMdxGetCellAtOffset(
ESS_ULONG_T ulOffset,
ESS_MDX_PCELLHDL_T phCell);
ulOffset input Cell offset (first axis changes fastest)
phCell input Cell handle
1145
EssMdxGetCellInfo
Returns the type of the cell corresponding to the input cell handle.
Syntax
ESS_FUNC_M EssMdxGetCellInfo (
ESS_MDX_CELLHDL_T hCell,
ESS_PULONG_T pUlType,
ESS_MDX_PCELLINFO_T pulCellInfo,
ESS_MDX_PCELLSTATUS_T pulStatus);
hCell input Cell handle
pulType output Cell data type. Values:

l ESS_MDX_VALTYPE_DOUBLE
Numeric type
l ESS_MDX_VALTYPE_SMARTLIST
Smartlist type
l ESS_MDX_VALTYPE_DATE
Date type
pulCellInfo output Cell status bit map specified using the following bitmasks:
l ESS_MDX_CELLINFO_MISSING
The cell value is missing
l ESS_MDX_CELLINFO_NOACCESS
The cell value is not accessible to the current user.
l ESS_MDX_CELLINFO_MEANINGLESS
The cell value is meaningless in the context of attribute members
l ESS_MDX_CELLINFO_OUTOFRANGE
The cell value is out of range in the context of a smartlist
pulStatus output Cell status information. This is the same information returned by the EssMdxGetCellStatus function; see the function
description for more information. The status information is returned only if the function EssMdxSetNeedCellStatus
is called.
EssMdxGetCellStatus
Returns the status of the cell specified by hCell. The status can be tested against the bitmasks in
pulStatus to determine whether the cell is of the corresponding type. This function should be
called only after an earlier call to “EssMdxSetNeedCellStatus” on page 1158.
Syntax
ESS_FUNC_M EssMdxGetCellStatus(
1146
ESS_MDX_PCELLSTATUS_T pulStatus);
pulStatus output Cell status:

Bitmap with the following masks:
l ESS_MDX_CELLSTATUS_LINKEDOBJS
l ESS_MDX_CELLSTATUS_DYNCALC
l ESS_MDX_CELLSTATUS_CALCED
l ESS_MDX_CELLSTATUS_READONLYMBR
EssMdxGetClusterDimMembers
Returns the member handles for the specified dimension within the given cluster.
Syntax
ESS_FUNC_M EssMdxGetClusterDimMembers(
ESS_MDX_CLUSTERHDL_T hCluster,
hCluster input Cluster handle
ulIndex input Dimension index within axis containing cluster
pphMbrs output Array of member handles for the specified dimension
EssMdxGetClusterInfo
Returns information about the specified cluster.
1147
Syntax
ESS_FUNC_M EssMdxGetClusterInfo(
ESS_PULONG_T pulSize,
ESS_PULONG_T pulNDims,
ESS_PPULONG_T ppulDimSizes);
pulSize output Number of tuples in cluster
pulNDims output Number of dimensions in cluster (same as that in the axis that this cluster belongs to)
ppulDimSizes output Array of dimension sizes (number of members)
EssMdxGetClusterMembers
Returns the tuple at the specified position within the given cluster.
Note: The client should use EssFree() when done with pphMbrs.
Syntax
ESS_FUNC_M EssMdxGetClusterMembers(
ulIndex input Tuple position within cluster (first dimension changes slowest)
pphMbrs output Array of member handles for the tuple
1148
EssMdxGetClusters
Returns the clusters within the specified axis.
Syntax
ESS_FUNC_M EssMdxGetClusters(
ESS_PULONG_T pulNClusters,
ESS_MDX_PPCLUSTERHDL_T pphClusters);
pulNClusters output Number of clusters
pphClusters output Array of cluster handles
EssMdxGetDimInfo
Returns information about the specified dimension, including the properties available for
members in this dimension.
Syntax
ESS_FUNC_M EssMdxGetDimInfo(
ESS_MDX_DIMHDL_T hDim,
ESS_PSTR_T ppszName,
ESS_PULONG_T pulNProps,
ESS_MDX_PPPROPHDL_T pphProps);
hDim input Dimension handle
ppszDimName output Dimension name
pulNProps output Number of properties returned
pphProps output Array of property handles
1149
Notes
l Before calling this query, you should call “EssMdxGetAxisInfo” on page 1143to get
dimensions represented on an axis.
l To get the properties of a dimension:
1. Call “EssMdxNewQuery” on page 1157 to create a query.
2. Call “EssMdxExecuteQuery” on page 1142 to execute the query.
3. Call “EssMdxGetAxes” on page 1143 to get the number of axes and the individual axis
handles from the result of the query.
4. Call “EssMdxGetAxisInfo” on page 1143 to get information (dimensions/tuples) for an
individual axis from an axis handle.
5. Call “EssMdxGetDimInfo” on page 1149 to get information for a dimension (dimension
name, number of properties for this dimension, and property handles).
6. Call “EssMdxGetPropertyInfo” on page 1153 to get the dimension properties. To get
properties, the MDX query in EssMdxQuery must use the DIMENSION PROPERTIES
option.
EssMdxGetFormatString
Returns the formatted value of the given cell.
Note: Returns formatted values only if the cell property option

ESS_MDX_CELLPROP_FORMAT_STRING is set using
EssMdxSetQueryCellProperties.
Syntax
ESS_FUNC_M EssMdxGetFormatString(
ESS_PSTR_T pFmtStr);
pFmtStr output Format string for the given cell
See Also
“EssMdxGetFormattedValue” on page 1151
1150
EssMdxGetFormattedValue
Returns the formatted value of the given cell.

ESS_MDX_CELLPROP_FORMATTED_VALUE is set using
EssMdxSetQueryCellProperties.
Syntax
ESS_FUNC_M EssMdxGetFormattedValue(
ESS_PSTR_T pFmtVal);
hQry input Input query handle
hCell input Input cell handle
pFmtVal output Formatted value of the cell
See Also
“EssMdxGetFormatString” on page 1150
EssMdxGetMbrIdentifier
Returns the identifier for the specified member.
Syntax
ESS_FUNC_M EssMdxGetMbrIdentifier(
ESS_MDX_MBRHDL_T hMbr,
ESS_PSTR_T ppszIdentifier);
hMbr input Member handle
ppszIdentifier output Member identifier (name or alias)
EssMdxGetMbrProperty
Returns the value of the specified property for the specified member. The property value will
have a type of ESS_MDX_PROPTYPE_NONE if the property is not applicable to the member.
1151
Syntax
ESS_FUNC_M EssMdxGetMbrProperty(
ESS_MDX_MBRHDL_T hMbr,
ESS_MDX_PROPHDL_T hProp,
ESS_MDX_PPROPVALUE_T pPropValue);
hMbr input Member handle
hProp input Property handle
pPropValue output Property value
EssMdxGetNamedSets
Returns the named sets in the query.
Syntax
ESS_FUNC_M EssMdxGetNamedSets(
ESS_HCTX_T hCtx,
ESS_PULONG_T pulCount,
ESS_PPSTR_T ppNames,
ESS_PLONG_T *ppTypes);
hCtx input Context handle.
pulCount output Count of the named sets returned in the query.
ppNames output An array of named sets.

The memory allocated for ppNames should be freed using EssFree().
*ppTypes output Pointer to the named set type: ESS_MDX_NAMEDSET_TYPE_SESSION.
Return Value
The return values are the number of named sets in pulCount, the named sets in ppNames, and
the type of the named sets in ppTypes.
Access
Example
void TestGetNamedSets()
{
ESS_STR_T fileNames[2];
ESS_CHAR_T qry[2][MAXQRYLEN];
1152
FILE *fileHandle;
char *s;
int length, e, i;
ESS_ULONG_T ulCount, j;
ESS_PSTR_T pNames;
ESS_PLONG_T pTypes;
fileNames[0] = "D:\\testarea\\MDXAPI\\query3.txt";
fileNames[1] = "D:\\testarea\\MDXAPI\\query4.txt";
for(i = 0; i < 2; i++)

{
fileHandle = fopen(fileNames[i], "r");
if (!(fileHandle = fopen(fileNames[i], "r")))
{
printf("\nUnable to open file: %s\n", fileNames[i]);
return;
}
else
{
s = qry[i];
length = MAXQRYLEN;
fgets(s, length, fileHandle);
if ((e = ferror(fileHandle)) != 0)
{
printf("fgets error %d\n", e);
exit((int) e);
}
fclose(fileHandle);
}
printf("\nThe query[%d]: \n%s\n", i, qry[i]);
}
ulCount = 0;
sts = EssMdxGetNamedSets(hCtx, &ulCount, &pNames, &pTypes);
printf("EssMdxGetNamedSets sts: %ld\n",sts);
for(j = 0; j < ulCount; j++)
{
printf("\tpNames[%d]: %s\n", j, pNames[j]);
printf("\tpTypes[%d]: %d\n", j, pTypes[j]);
printf("\n");
}
sts = EssFree(hInst, (ESS_PVOID_T)pNames);

}
EssMdxGetPropertyInfo
Returns information about the specified property.
Syntax
ESS_FUNC_M EssMdxGetPropertyInfo(
ESS_MDX_PROPHDL_T hProp,
1153
ESS_PSTR_T ppszName,
ESS_MDX_PPROPTYPE_T pPropType);
hProp input Property handle
ppszName output Property name
pPropType output Property type:

l ESS_MDX_PROPTYPE_BOOL
l ESS_MDX_PROPTYPE_DOUBLE
l ESS_MDX_PROPTYPE_STRING
l ESS_MDX_PROPTYPE_DATETIME
l ESS_MDX_PROPTYPE_ULONG
EssMdxGetQueryCellProperties
Returns the cell properties in effect for this query.
Syntax
ESS_FUNC_M EssMdxGetQueryCellProperties(
ESS_MDX_CELLPROPS_T pulProp);
pulProp output Pointer to bitmask specifying what cell properties are returned
See Also
“EssMdxSetQueryCellProperties” on page 1159
EssMdxGetQueryOptions
Returns the query options in effect for the current query.
Syntax
ESS_FUNC_M EssMdxGetQueryOptions(
ESS_MDX_PQRYOPT_T pulOpt);
1154
pulOpt output Pointer to bitmask specifying current query options in effect
See Also
“EssMdxSetQueryOptions” on page 1159
EssMdxGetSmartlistforCell
Returns the name of the Smartlist object associated with a cell when the cell type is
ESS_MDX_VALTYPE_SMARTLIST. An Essbase database can have multiple Smartlist objects
and Smartlist members associated with these objects. This function identifies which Smartlist
object a cell is associated with.

ESS_MDX_CELLPROP_SMLIST_NAME is set using EssMdxSetQueryCellProperties.
Syntax
ESS_FUNC_M EssMdxGetSmartlistforCell(
ESS_PSTR_T pSmartlist);
pSmartlist output Name of the Smartlist object a cell is associated with
EssMdxGetValue
Returns the specified cell's value.
Syntax
ESS_FUNC_M EssMdxGetValue(
ESS_PBOOL_T pbIsMissing,
ESS_PBOOL_T pbNoAccess,
ESS_PDOUBLE_T pdValue);
1155
pbIsMissing output Whether cell value is #Missing
pbNoAccess output Whether cell value is #NoAccess
pdValue output The cell's value, if not #Missing
EssMDXIsCellGLDrillable
Checks whether the cell is associated with a drill-through URL.
Syntax
ESS_FUNC_M EssMdxIsCellGLDrillable (hQry, hCell, pIsDrillable);
hQry ESS_MDX_QRYHDL_T Query handle
hCell ESS_MDX_CELLHDL_T Cell handle
pIsDrillable ESS_PBOOL_T True, if the cell is associated with a drill-through URL; False, otherwise
Return Value
l If successful, sets pIsDrillable based on the cell's status.
l If unsuccessful, returns an error message.
Example
#define ESS_MDX_CELLPROP_GLDRILLTHRU 0x00000008
if ((sts = EssMdxNewQuery(hCtx, qry, &hQry)) != ESS_STS_NOERR)

{
printf("EssMdxNewQuery failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxNewQuery sts: %ld\n", sts);
if ((sts = EssMdxSetQueryCellProperties(hQry,
(ESS_MDX_CELLPROP_GLDRILLTHRU
)
)) != ESS_STS_NOERR)
{
printf("EssMdxSetQueryCellProperties failure: %ld\n", sts);
exit ((int) sts);
}
if ((sts = EssMdxExecuteQuery(hQry)) != ESS_STS_NOERR)
{
printf("EssMdxExecuteQuery failure: %ld\n", sts);
exit ((int) sts);
1156
}
printf("EssMdxExecuteQuery sts: %ld\n", sts);
/* To retrieve IsCellGLDrillable property of a cell, use EssMdxIsCellGLDrillable*/
if ((sts = EssMdxIsCellGLDrillable(hQry, hCell, &bIsCellGLDT))

!= ESS_STS_NOERR)
{
printf("EssMdxIsCellGLDrillable failure: %ld\n", sts);
exit ((int) sts);
}
if (bIsCellGLDT)
printf(" Is Cell Drillable: TRUE\n");
else
printf(" Is Cell Drillable: FALSE\n");
EssMdxNewQuery
Takes the MDX query specified by pszQry and returns a query handle.
Syntax
ESS_FUNC_M EssMdxNewQuery(
ESS_HCTX_T hCtx,
ESS_STR_T pszQry,
ESS_MDX_PQRYHDL_T phQry);
hCtx input API context handle
pszQry input Query text
phQry output Query handle
Notes
This function should be called first to create any MDX query. For example, you must call this
function before calling EssMDXExecuteQuery.
EssMdxSetDataLess
Turns on a query execution mode in which cell data are not retrieved.
EssMdxGetCellAtOffset() and EssMdxGetCellAtIndices() should not be called for the query.
The default is to retrieve cell data.
Syntax
ESS_FUNC_M EssMdxSetDataLess(
1157
EssMDXSetHideData
Converts #NOACCESS cells to #MISSING.
Syntax
ESS_FUNC_M EssMDXSetHideData(
EssMdxSetMbrIdType
Sets the type of member identifier desired in the result. Defaults to
ESS_MDX_MEMBERIDTYPE_NAME.
Syntax
ESS_FUNC_M EssMdxSetMbrIdType(
ESS_MDX_MEMBERIDTYPE_T mbrIdType);
mbrIdType input Member identifier desired (name/alias):

l ESS_MDX_MEMBERIDTYPE_NAME
l ESS_MDX_MEMBERIDTYPE_ALIAS
EssMdxSetNeedCellStatus
Turns on retrieval of cell status information. By default the cell status information is not
retrieved.
Syntax
ESS_FUNC_M EssMdxSetNeedCellStatus(
1158
EssMdxSetQueryCellProperties
Specifies the cell properties to be sent from the server for each cell. By default, only cell value is
sent. The options passed in ulProp overwrite the existing query cell properties. In other words,
if EssMdxSetQueryCellProperties is called multiple times, only the ulProp value in the last call
is taken into account.
Syntax
ESS_FUNC_M EssMdxSetQueryCellProperties(
ESS_MDX_CELLPROPS_T ulProp);
ulProp input Bitmask specifying what cell properties should be sent. Values:
l ESS_MDX_CELLPROP_FORMATTED_VALUE
l ESS_MDX_CELLPROP_FORMAT_STRING
l ESS_MDX_CELLPROP_SMLIST_NAME
See Also
“EssMdxGetQueryCellProperties” on page 1154
EssMdxSetQueryOptions
Sets query options based on the value of ulOpt. The options passed in ulOpt overwrite the existing
query options. In other words, if EssMdxSetQueryOptions is called multiple times, only the
ulOpt value in the last call is taken into account.
Syntax
ESS_FUNC_M EssMdxSetQueryOptions(
ESS_MDX_QRYOPT_T ulOpt);
1159
ulOpt input Query options. Bitmask values:

l ESS_MDX_QRYOPT_GET_MI_CELLS
Indicates that formatted values should be generated for #Missing cells also. By default #Missing cells are not
formatted by server.
l ESS_MDX_QRYOPT_GET_ME_CELLS
Tells the server to distinguish #ME (meaningless value) from #Missing values. A #ME is a special case of #Missing
value. It indicates that the base member and attribute member combination in the context of that cell is
meaningless. By default this option is set to off.
l ESS_MDX_QRYOPT_SKIP_NE
Tells the server to skip unresolved member names so that the query can continue without error. Must be set per
query.
See Also
“EssMdxGetQueryOptions” on page 1154
MDX Sample Client Program

#if defined _WIN32 || defined _WINDOWS
#endif
#include <string.h>
#include <stdio.h>
#include <ctype.h>
#include <stdlib.h>
#include <assert.h>
#include <time.h>
#pragma pack(push,localid,1)
#endif
#include <essapi.h>
#pragma pack(pop,localid)
#endif
ESS_HINST_T hInst;
ESS_HCTX_T hCtx;
#define MAXQRYLEN 65536
ESS_CHAR_T qry[MAXQRYLEN];
static ESS_CHAR_T *axisnames[] =

{
"COLUMNS", "ROWS", "PAGES", "CHAPTERS", "SECTIONS"
};
void ESS_Init()
{
1160
ESS_STS_T sts;
ESS_INIT_T InitStruct = {ESS_API_VERSION,
NULL,
0L,
255,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
0L
};
{
exit ((int) sts);
}
printf("EssInit sts: %ld\n", sts);
}
void ESS_Login ()
{
ESS_USHORT_T Items;
ESS_CHAR_T SvrName[ESS_SVRNAMELEN];
strcpy(UserName,"essexer");
strcpy(Password,"password");
sts = EssLogin(hInst, SvrName, UserName, Password, &Items,
&pAppsDbs, &hCtx);
if ( (sts != 0) && (sts != 1051093L) && (sts != 1051090L) )
{
exit ((int) sts);
}
printf("EssLogin sts: %ld\n", sts);
}
void ESS_MdxAxis(ESS_MDX_QRYHDL_T hQry,

ESS_STR_T pszAxisName
)
{
ESS_STS_T sts;
ESS_ULONG_T ulNAxisDims, ulAxisSize;
ESS_ULONG_T ulNClusters, ulClusterSize, ulNClusterDims;
ESS_ULONG_T ulAxisDimCnt, ulIndex, ulPropCnt;
ESS_ULONG_T ulClusterCnt, ulClusterDimCnt;
ESS_PULONG_T ulaDimSizes;
ESS_MDX_PCLUSTERHDL_T haClusters;
1161
ESS_MDX_CLUSTERHDL_T hCluster;
ESS_MDX_PDIMHDL_T haDims;
ESS_STR_T pszDimName, pszMbrIdentifier, pszPropName;
ESS_MDX_PMBRHDL_T haMbrs;
ESS_PULONG_T ulaNProps = NULL;
ESS_MDX_PPPROPHDL_T haaProps = NULL;
ESS_MDX_PPROPHDL_T haProps;
ESS_MDX_PROPHDL_T hProp;
ESS_MDX_PROPTYPE_T propType;
ESS_MDX_PROPVALUE_T propval;
if ((sts = EssMdxGetAxisInfo(hAxis, &ulAxisSize, &ulNAxisDims,

&haDims)) != ESS_STS_NOERR)
{
printf("EssMdxGetAxisInfo failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetAxisInfo sts: %ld\n", sts);
printf("%s Size %ld Num dims %ld\n", pszAxisName,
ulAxisSize, ulNAxisDims);
if (ulAxisSize == 0)
{
return;
}
if ((sts = EssAlloc(hInst,
ulNAxisDims * sizeof(ESS_ULONG_T),
(ESS_PPVOID_T) &ulaNProps)) != ESS_STS_NOERR)
{
printf("EssAlloc failure: %ld\n", sts);
exit ((int) sts);
}
if ((sts = EssAlloc(hInst,
ulNAxisDims * sizeof(ESS_MDX_PPROPHDL_T),
(ESS_PPVOID_T) &haaProps)) != ESS_STS_NOERR)
{
printf("EssAlloc failure: %ld\n", sts);
exit ((int) sts);
}
for (ulAxisDimCnt = 0; ulAxisDimCnt < ulNAxisDims;
ulAxisDimCnt++)
{
if ((sts = EssMdxGetDimInfo(haDims[ulAxisDimCnt],
&pszDimName,
&ulaNProps[ulAxisDimCnt],
&haaProps[ulAxisDimCnt])) != ESS_STS_NOERR)
{
printf("EssMdxGetDimInfo failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetDimInfo sts: %ld\n", sts);
printf("Dim %ld name %s #props %ld\n", ulAxisDimCnt,
pszDimName, ulaNProps[ulAxisDimCnt]);
haProps = haaProps[ulAxisDimCnt];
for (ulPropCnt = 0; ulPropCnt < ulaNProps[ulAxisDimCnt]; ulPropCnt++)
{
1162
hProp = haProps[ulPropCnt];
if ((sts = EssMdxGetPropertyInfo(hProp, &pszPropName,
&propType)) != ESS_STS_NOERR)
{
printf("EssMdxGetPropertyInfo failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetPropertyInfo sts: %ld\n", sts);
printf("Property %ld type %ld name %s\n", ulPropCnt,
propType, pszPropName);
}
}
if ((sts = EssMdxGetClusters(hAxis, &ulNClusters,
&haClusters)) != ESS_STS_NOERR)
{
printf("EssMdxGetClusters failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetClusters sts: %ld\n", sts);
printf("Num clusters %ld\n", ulNClusters);
for (ulClusterCnt = 0; ulClusterCnt < ulNClusters;
ulClusterCnt++)
{
hCluster = haClusters[ulClusterCnt];
if ((sts = EssMdxGetClusterInfo(hCluster, &ulClusterSize,
&ulNClusterDims,
&ulaDimSizes)) != ESS_STS_NOERR)
{
printf("EssMdxGetClusterInfo failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetClusterInfo sts: %ld\n", sts);
printf("Cluster %ld Size %ld\n", ulClusterCnt, ulClusterSize);
for (ulClusterDimCnt = 0; ulClusterDimCnt < ulNClusterDims;
ulClusterDimCnt++)
{
printf("Cluster Dim %ld Size %ld\n", ulClusterDimCnt,
ulaDimSizes[ulClusterDimCnt]);
}
for (ulIndex = 0; ulIndex < ulClusterSize; ulIndex++)
{
if ((sts = EssMdxGetClusterMembers(hCluster, ulIndex,
&haMbrs)) != ESS_STS_NOERR)
{
printf("EssMdxGetClusterMembers failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetClusterMembers sts: %ld\n", sts);
ulClusterDimCnt++)
{
if ((sts = EssMdxGetMbrIdentifier(haMbrs[ulClusterDimCnt],
&pszMbrIdentifier)) != ESS_STS_NOERR)
{
printf("EssMdxGetMbrIdentifier failure: %ld\n", sts);
exit ((int) sts);
}
1163
printf("EssMdxGetMbrIdentifier sts: %ld\n", sts);
printf("Mbr %ld identifier %s\n", ulClusterDimCnt,
pszMbrIdentifier);
haProps = haaProps[ulClusterDimCnt];
for (ulPropCnt = 0;
ulPropCnt < ulaNProps[ulClusterDimCnt];
ulPropCnt++)
{
if ((sts = EssMdxGetMbrProperty(haMbrs[ulClusterDimCnt],
haProps[ulPropCnt],
&propval)) != ESS_STS_NOERR)
{
printf("EssMdxGetMbrProperty failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetMbrProperty sts: %ld\n", sts);
printf("Property %ld Type ", ulPropCnt);
switch (propval.ulPropType)
{
case ESS_MDX_PROPTYPE_ULONG:
{
printf("Ulong Value: %ld\n",
propval.value.ulData);
break;
}
case ESS_MDX_PROPTYPE_STRING:
{
printf("String Value: %s\n",
propval.value.strData);
break;
}
case ESS_MDX_PROPTYPE_BOOL:
{
printf("Bool Value: %s\n",
propval.value.bData ? "TRUE" : "FALSE");
break;
}
case ESS_MDX_PROPTYPE_DOUBLE:
{
printf("Double Value: %lf\n",
propval.value.dblData);
break;
}
case ESS_MDX_PROPTYPE_DATETIME:
{
ESS_CHAR_T tmpbuf[80];
struct tm* pTime;
pTime = gmtime((time_t*)&(propval.value.dtData));
sprintf(tmpbuf, "%02i-%02i-%04i",
printf("DateTime Value: %s\n", tmpbuf);
break;
}
case ESS_MDX_PROPTYPE_NONE:
{
printf("NULL Value\n");
break;
1164
}
}
}
}
if ((sts = EssFree(hInst, (ESS_PVOID_T) haMbrs)) != ESS_STS_NOERR)
{
printf("EssFree failure: %ld\n", sts);
exit ((int) sts);
}
}
ulClusterDimCnt++)
{
if ((sts = EssMdxGetClusterDimMembers(hCluster, ulClusterDimCnt,
{
printf("EssMdxGetClusterDimMembers failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetClusterDimMembers sts: %ld\n", sts);
for (ulIndex = 0; ulIndex < ulaDimSizes[ulClusterDimCnt];
ulIndex++)
{
if ((sts = EssMdxGetMbrIdentifier(haMbrs[ulIndex],
{
exit ((int) sts);
}
printf("Dim %ld Mbr %ld identifier %s\n", ulClusterDimCnt,
ulIndex, pszMbrIdentifier);
}
}
}
for (ulIndex = 0; ulIndex < ulAxisSize; ulIndex++)
{
if ((sts = EssMdxGetAxisMembers(hAxis, ulIndex,
{
printf("EssMdxGetAxisMembers failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetAxisMembers sts: %ld\n", sts);
for (ulAxisDimCnt = 0; ulAxisDimCnt < ulNAxisDims;
ulAxisDimCnt++)
{
if ((sts = EssMdxGetMbrIdentifier(haMbrs[ulAxisDimCnt],
{
exit ((int) sts);
}
printf("Mbr %ld identifier %s\n", ulAxisDimCnt, pszMbrIdentifier);
haProps = haaProps[ulAxisDimCnt];
1165
for (ulPropCnt = 0;
ulPropCnt < ulaNProps[ulAxisDimCnt];
ulPropCnt++)
{
hProp = haProps[ulPropCnt];
if ((sts = EssMdxGetPropertyInfo(hProp, &pszPropName,
&propType)) != ESS_STS_NOERR)
{
printf("EssMdxGetPropertyInfo failure: %ld\n", sts);
exit ((int) sts);
}
if ((sts = EssMdxGetMbrProperty(haMbrs[ulAxisDimCnt],
hProp,
&propval)) != ESS_STS_NOERR)
{
printf("EssMdxGetMbrProperty failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetMbrProperty sts: %ld\n", sts);
printf("Property %ld Type ", ulPropCnt);
switch (propval.ulPropType)
{
case ESS_MDX_PROPTYPE_ULONG:
{
printf("Ulong Value: %ld\n",
propval.value.ulData);
break;
}
case ESS_MDX_PROPTYPE_STRING:
{
printf("String Value: %s\n",
propval.value.strData);
break;
}
case ESS_MDX_PROPTYPE_BOOL:
{
printf("Bool Value: %s\n",
propval.value.bData ? "TRUE" : "FALSE");
break;
}
case ESS_MDX_PROPTYPE_DOUBLE:
{
printf("Double Value: %lf\n",
propval.value.dblData);
break;
}
case ESS_MDX_PROPTYPE_DATETIME:
{
ESS_CHAR_T tmpbuf[80];
struct tm* pTime;
pTime = gmtime((time_t*)&(propval.value.dtData));
sprintf(tmpbuf, "%02i-%02i-%04i",
printf("DateTime Value: %s\n", tmpbuf);
break;
}
case ESS_MDX_PROPTYPE_NONE:
1166
{
printf("NULL Value\n");
break;
}
}
}
}
if ((sts = EssFree(hInst, (ESS_PVOID_T) haMbrs)) != ESS_STS_NOERR)
{
exit ((int) sts);
}
}
if ((sts = EssFree(hInst, (ESS_PVOID_T) ulaNProps)) != ESS_STS_NOERR)
{
exit ((int) sts);
}
if ((sts = EssFree(hInst, (ESS_PVOID_T) haaProps)) != ESS_STS_NOERR)
{
exit ((int) sts);
}
}
void ESS_MdxQry()
{
ESS_STS_T sts;
ESS_MDX_QRYHDL_T hQry;
ESS_ULONG_T ulNAxes, ulNAxisDims, ulAxisSize, ulResultSize;
ESS_ULONG_T ulNClusters, ulClusterSize, ulNClusterDims;
ESS_ULONG_T ulAxisCnt, ulAxisDimCnt, ulIndex, ulPropCnt;
ESS_ULONG_T ulCellOffset, ulClusterCnt, ulClusterDimCnt;
ESS_MDX_CELLSTATUS_T ulCellStatus;
ESS_PULONG_T ulaDimSizes;
ESS_MDX_PCLUSTERHDL_T haClusters;
ESS_MDX_CLUSTERHDL_T hCluster;
ESS_MDX_PAXISHDL_T haAxes;
ESS_MDX_PDIMHDL_T haDims;
ESS_STR_T pszDimName, pszMbrIdentifier, pszPropName;
ESS_MDX_AXISHDL_T hAxis, hSlicerAxis;
ESS_MDX_PMBRHDL_T haMbrs;
ESS_MDX_CELLHDL_T hCell;
ESS_DOUBLE_T dValue;
ESS_BOOL_T bIsMissing, bNoAccess;
ESS_PULONG_T ulaNProps;
ESS_MDX_PPPROPHDL_T haaProps;
ESS_MDX_PPROPHDL_T haProps;
ESS_MDX_PROPHDL_T hProp;
ESS_MDX_PROPTYPE_T propType;
ESS_MDX_PROPVALUE_T propval;
if ((sts = EssMdxNewQuery(hCtx, qry, &hQry)) != ESS_STS_NOERR)

{
1167
printf("EssMdxNewQuery failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxNewQuery sts: %ld\n", sts);
if ((sts = EssMdxSetMbrIdType(hQry, ESS_MDX_MEMBERIDTYPE_ALIAS)) !=

ESS_STS_NOERR)
{
printf("EssMdxSetMbrIdType failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxSetMbrIdType sts: %ld\n", sts);
if ((sts = EssMdxSetNeedCellStatus(hQry)) != ESS_STS_NOERR)

{
printf("EssMdxSetNeedCellStatus failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxSetNeedCellStatus sts: %ld\n", sts);
if ((sts = EssMdxExecuteQuery(hQry)) != ESS_STS_NOERR)

{
printf("EssMdxExecuteQuery failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxExecuteQuery sts: %ld\n", sts);
if ((sts = EssMdxGetAxes(hQry, &ulNAxes, &haAxes,

&hSlicerAxis)) != ESS_STS_NOERR)
{
printf("EssMdxGetAxes failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetAxes sts: %ld\n", sts);
printf("Number of axes: %ld\n", ulNAxes);
ulResultSize = 1;
for (ulAxisCnt = 0; ulAxisCnt < ulNAxes; ulAxisCnt++)
{
hAxis = haAxes[ulAxisCnt];
if ((sts = EssMdxGetAxisInfo(hAxis, &ulAxisSize, &ulNAxisDims,
&haDims)) != ESS_STS_NOERR)
{
printf("EssMdxGetAxisInfo failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetAxisInfo sts: %ld\n", sts);
printf("Axis %ld Size %ld Num dims %ld\n", ulAxisCnt,
ulAxisSize, ulNAxisDims);
ulResultSize *= ulAxisSize;
}
if (hSlicerAxis)
{
ESS_MdxAxis(hQry, hSlicerAxis, "SLICER");
}
else
1168
{
printf("Slicer Axis is empty\n");
}
for (ulAxisCnt = 0; ulAxisCnt < ulNAxes; ulAxisCnt++)

{
hAxis = haAxes[ulAxisCnt];
ESS_MdxAxis(hQry, hAxis, axisnames[ulAxisCnt]);
}
for (ulCellOffset = 0; ulCellOffset < ulResultSize;
ulCellOffset++)
{
if ((sts = EssMdxGetCellAtOffset(hQry, ulCellOffset,
&hCell)) != ESS_STS_NOERR)
{
printf("EssMdxGetCellAtOffset failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetCellAtOffset sts: %ld\n", sts);
if ((sts = EssMdxGetValue(hCell, &bIsMissing, &bNoAccess,
&dValue)) != ESS_STS_NOERR)
{
printf("EssMdxGetValue failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetValue sts: %ld\n", sts);
if (bIsMissing)
{
printf("CellOffset %ld Value #Missing\n", ulCellOffset);
}
else if (bNoAccess)
{
printf("CellOffset %ld Value #NoAccess\n", ulCellOffset);
}
else
{
printf("CellOffset %ld Value %lf\n", ulCellOffset,
dValue);
}
if (!bNoAccess)
{
if ((sts = EssMdxGetCellStatus(hQry, hCell,
&ulCellStatus)) != ESS_STS_NOERR)
{
printf("EssMdxGetCellStatus failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxGetCellStatus sts: %ld\n", sts);
if (ulCellStatus & ESS_MDX_CELLSTATUS_LINKEDOBJS)
{
printf("Cell status: LINKEDOBJS\n");
}
if (ulCellStatus & ESS_MDX_CELLSTATUS_DYNCALC)
{
printf("Cell status: DYNCALC\n");
}
if (ulCellStatus & ESS_MDX_CELLSTATUS_CALCEDMBR)
1169
{
printf("Cell status: CALCEDMBR\n");
}
if (ulCellStatus & ESS_MDX_CELLSTATUS_READONLY)
{
printf("Cell status: READONLY\n");
}
}
}
if ((sts = EssMdxFreeQuery(hQry)) != ESS_STS_NOERR)

{
printf("EssMdxFreeQuery failure: %ld\n", sts);
exit ((int) sts);
}
printf("EssMdxFreeQuery sts: %ld\n", sts);
void ESS_Term()
{
{
}
printf("EssTerm sts: %ld\n", sts);
}
void ESS_Logout()
{
sts = EssLogout(hCtx);
printf("\n\nEssLogout sts: %ld\n",sts);
}
{

printf("EssSetActive sts: %ld\n",sts);
}
int main(int argc, char *argv[])

{
FILE *f;
char *s, *sout;
int n, l, e;
assert(argc > 1);

f = fopen(argv[1], "r");
assert(f != NULL);
s = qry;
1170
n = MAXQRYLEN;
while (n > 0 && !feof(f) && fgets(s, n, f) != NULL)
{
l = strlen(s);
s += l;
n -= l;
}
if ((e = ferror(f)) != 0)
{
printf("fgets error %d\n", e);
exit((int) e);
}
fclose(f);
printf("The query is\n%s\n", qry);
if (argc > 2)
{
AppName = argv[2];
}
if (argc > 3)
{
DbName = argv[3];
}
ESS_Init();
ESS_Login();
ESS_SetActive();
ESS_MdxQry();
ESS_Logout();
ESS_Term();
return 0;
}
1171
1172
Welcome to XMLA Reference
20
To use XML for Analysis (XMLA) API, you must install Provider Services. See the Oracle
Hyperion Enterprise Performance Management System Installation Start Here and Oracle Hyperion
Enterprise Performance Management System Installation and Configuration Guide. This help
explains XMLA methods and provides sample code for rowsets. XMLA clients can communicate
to Essbase only through Provider Services.
For information, click Contents, Index, or Search in the left frame.
1173
1174
Working with XMLA
21
In This Chapter
Key Features............................................................................................ 1175
Methods ................................................................................................ 1175
XMLA Rowsets .......................................................................................... 1181
Flattened Rowset Examples ........................................................................... 1211
Key Features
XML for Analysis (XMLA) is an open industry-standard Web service interface designed for
online analytical processing. XMLA is a set of XML Message Interfaces built on the open
standards of HTTP, XML, and Simple Object Access Protocol (SOAP). XMLA, which is not
bound to any language, platform, or operating system, provides standardized data access
between client applications and any multidimensional data source on the Web.
Key XMLA features:
l Support for flattened rowsets
l Support for stateful sessions
l Backward XMLA level representation (level 1 is the top level)
l User authentication through basic HTTP authentication
l XMLA High-Availability functionality through Oracle Hyperion Provider Services
l XMLA administration and monitoring through Oracle Essbase Administration Services
Note: XMLA is available for use with Essbase only.
Methods
The following methods provide a standard way for XML applications to access basic information
from the server. Because these methods are invoked using SOAP, they accept input and deliver
output in XML. By default, these methods are stateless, so the server context ends at the
completion of any command.
The simplified interface model has two methods.
l Discover
1175
l Execute
Discover obtains information and metadata from a Web Service. This information can include
a list of available data sources and data about a data source provider. Properties define and shape
the data obtained. Discover allows you to specify the types of information that the client
application needs. The use of generic interface and properties enables extensibility without
necessitating rewriting existing functions.
Execute executes Multidimensional Expressions (MDX) or other provider-specific commands
against an XMLA data source. The following diagram illustrates a possible implementation of
an n-tiered application.
Provided with the URL for a server hosting a Web Service, the client uses SOAP and HTTP
protocols to send Discover and Execute calls to the server. The server instantiates the XMLA
provider, which handles the calls. The XMLA provider fetches the data, packages it into XML,
and sends the data to the client.
The Discover and Execute methods enable users to determine what can be queried on a server
and, based on this, submit commands to be executed.
The XML namespace for these methods is “urn:schemas-microsoft-com:xml-analysis”.
Connection information is supplied in each method call with the connection properties.
Discover
The Discover method retrieves information, such as the list of data sources on a server or details
about a data source. The data retrieved with the Discover method depends on the values of the
parameters passed to it.
Namespace
urn:schemas-microsoft-com:xml-analysis
SOAP Action
"urn:schemas-microsoft-com:xml-analysis:Discover"
Syntax
Discover (
[in] RequestType As EnumString,
[in] Restrictions As Restrictions,
[in] Properties As Properties,
[out] Result As Rowset)
Parameters
RequestType [in]
1176
This required parameter comprises a RequestType enumeration value, which determines the
type of information to be returned. The RequestType enumeration is used by the Discover
method to determine the structure and content of the rowset returned in the Result parameter.
The Restrictions parameter format and XML result set are also dependent on the value specified
in this parameter. This enumeration can be extended to support provider-specific enumeration
strings.
Each RequestType enumeration value corresponds to a return rowset. For rowset definitions,
see “XMLA Rowsets” on page 1181. Support is required for the following explicitly named
RequestType enumeration values.
Enumeration value Description
DISCOVER_ Returns a list of XMLA data sources available on the server or Web Service.
DATASOURCES
DISCOVER_ Returns a list of information and values about the requested properties that are supported by the specified data
PROPERTIES source (provider).
DISCOVER_SCHEMA_ Returns the names, values, and other information of all supported RequestType enumeration values (including
ROWSETS those listed here), and any additional provider-specific enumeration values.
DISCOVER_ Returns a list of names, data types, and enumeration values of enumerators supported by the provider of a
ENUMERATORS specific data source.
DISCOVER_KEYWORDS Returns a rowset containing a list of keywords reserved by the provider.
DISCOVER_LITERALS Returns information about literals supported by the data source provider. Schema Rowset Constant Given, a
constant that corresponds to one of the schema rowset names defined by OLE DB, such as MDSCHEMA_CUBES,
returns the OLE DB schema rowset in XML format. Note that providers also may extend OLEDB by providing
additional provider-specific schema rowsets. The schema rowsets that tabular data providers (TDP) and
multidimensional data providers (MDP) are required to support are listed in the section "DISCOVER_SCHEMA_
ROWSETS Rowset."
Restrictions [in]
This parameter, of the Restrictions data type, enables the user to restrict the data returned in
Result. Result columns are defined by the rowset specified in the RequestType parameter. Some
columns of Result can filter the rows returned. For these columns and those that can be restricted,
see the rowset tables in “XMLA Rowsets” on page 1181. To obtain the restriction information
for provider-specific schema rowsets, use the DISCOVER_SCHEMA_ROWSETS request type.
This parameter can be empty, but it must be included.
Properties [in]
This parameter, of the Properties data type, comprises a collection of XMLA properties. Each
property enables users to control some aspect of the Discover method, such as specifying the
return format of the result set, the timeout, or the locale in which the data should be formatted.
You can obtain the available properties by using the DISCOVER_PROPERTIES request type
with the Discover method.
The properties in the Properties parameter have no required order. This parameter can be empty,
but it must be included.
Result [out]
1177
This required parameter contains the result set returned by the provider as a Rowset object. The
columns and content of the result set are specified by the values in the RequestType and
Restrictions parameters. The column layout of the returned result set also is determined by the
value specified in RequestType. For information about the rowset layouts that correspond to
for each RequestType value, see “XMLA Rowsets” on page 1181.
Example
In the following sample, the client sends the XML Discover call to request a list of cubes from
the Demo catalog:
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<Discover xmlns="urn:schemas-microsoft-com:xml-analysis"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<RequestType>MDSCHEMA_CUBES</RequestType>
<Restrictions>
<RestrictionList>
<CATALOG_NAME>Demo</CATALOG_NAME>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>
Provider=Essbase;Data Source=localhost
</DataSourceInfo>
<Format>Tabular</Format>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The provider returns the following result to the client:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<m:DiscoverResponse xmlns:m="urn:schemas-microsoft-com:xml-analysis">
<m:return xsi:type="xsd:string"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<root xmlns="urn:schemas-microsoft-com:xml-analysis:rowset"
<xsd:schema xmlns="urn:schemas-microsoft-com:xml-analysis:rowset"
targetNamespace="urn:schemas-microsoft-com:xml-analysis:rowset"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:sql="urn:schemas-microsoft-com:xml-sql"
elementFormDefault="qualified">
<xsd:element name="root">
<xsd:complexType>
<xsd:sequence minOccurs="0" maxOccurs="unbounded">
1178
<xsd:element name="row" type="row"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="row">
<xsd:sequence maxOccurs="unbounded" minOccurs="0">
<xsd:element name="CATALOG_NAME" type="xsd:string"
sql:field="CATALOG_NAME"/>
<xsd:element name="CUBE_NAME" type="xsd:string"
sql:field="CUBE_NAME"/>
<xsd:element name="CUBE_TYPE" type="xsd:string"
sql:field="CUBE_TYPE"/>
<xsd:element name="LAST_SCHEMA_UPDATE" type="xsd:dateTime"
sql:field="LAST_SCHEMA_UPDATE" minOccurs="0"/>
<xsd:element name="DESCRIPTION" type="xsd:string"
sql:field="DESCRIPTION" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<CUBE_NAME>Demo.Basic</CUBE_NAME>
<CUBE_TYPE>CUBE</CUBE_TYPE>
</row>
</root>
</m:return>
</m:DiscoverResponse>
</SOAP-ENV:Body>
Execute
The Execute method sends action requests, including those involving data transfer, such as
retrieving or updating data on the server, to the server.
Namespace
urn:schemas-microsoft-com:xml-analysis
SOAP Action
"urn:schemas-microsoft-com:xml-analysis:Execute"
Syntax
Execute (
[in] Command As Command,
[in] Properties As Properties,
[out] Result As Resultset)
Parameters
Command [in]
This required parameter is of Command data type and consists of an MDX statement to be
executed.
Properties [in]
1179
This parameter is of the Properties data type and consists of a collection of XMLA properties.
Each property allows the user to control some aspect of the Execute method, such as defining
the information required for the connection, specifying the return format of the result set, or
specifying the locale in which the data should be formatted.
The available properties and their values can be obtained by using the
DISCOVER_PROPERTIES request type with the Discover method.
The properties in the Properties parameter have no required order. This parameter can be empty,
but it must be included.
Result [out]
This parameter contains the Resultset result returned by the provider. The Command parameter
and values in the Properties parameter define the shape of the result set. If no shape-defining
properties are passed, the XMLA provider may use a default shape. The two result set formats
defined by this specification are Tabular and Multidimensional, as specified by the client through
the Format property. OLAP data lends itself to the Multidimensional format (although the
Tabular format also can be used). A provider may support additional rowset types, and clients
aware of the specialized types can request them.
Example
The following is an example of an Execute method call with <Statement> set to an MDX SELECT
statement:
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<Execute xmlns="urn:schemas-microsoft-com:xml-analysis"
<Command>
<Statement>
SELECT CrossJoin([Measures].CHILDREN , [Market].CHILDREN)
on columns, [Product].Members on rows
from Sample.Basic
</Statement>
</Command>
<Properties>
<PropertyList>
<DataSourceInfo>
</DataSourceInfo>
<Catalog>Sample</Catalog>
<Format>Multidimensional</Format>
<AxisFormat>TupleFormat</AxisFormat>
<Content>SchemaData</Content>
</PropertyList></Properties>
</Execute>
</SOAP-ENV:Body>
The abbreviated response for the preceding method call:
1180
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<m:ExecuteResponse
xmlns:m="urn:schemas-microsoft-com:xml-analysis">
<m:return
<root xmlns="urn:schemas-microsoft-com:xml-analysis:mddataset">
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xars="urn:schemas-microsoft-com:xars">
...<!-The schema for the data goes here. -- >
</xsd:schema>
... <!-The data in MDDataSet format goes here. -- >
</root>
</m:return>
</m:ExecuteResponse>
</SOAP-ENV:Body>
XMLA Rowsets
Information returned in the Result parameter of the Discover method is structured according
to the rowset column layouts detailed in this section.
CATALOGS Rowset
The CATALOGS rowset identifies the physical attributes associated with catalogs accessible from
Analytic Services.
GUID: DBSCHEMA_CATALOGS
the section called “Flattened Rowset Examples” describes the rowset structure.
Table 8 CATALOGS Rowset Structure
Column Name Essbase Mapping
CATALOG_NAME Application name
DESCRIPTION Always null
Request Example
<SOAP-ENV:Body>
<RequestType>DBSCHEMA_CATALOGS</RequestType>
<Restrictions>
1181
<RestrictionList></RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>Provider=Essbase;Data Source=localhost
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
Response Example (truncated)

<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
1182
MDSCHEMA_CUBES Rowset
The CUBES rowset contains information about the available cubes in a schema (or the catalog,
if the provider does not support schemas).
GUID: MDSCHEMA_CUBES
Table 9 describes the rowset structure.
Table 9 MDSCHEMA_CUBES Rowset structure
CUBE_NAME Database name
CUBE_TYPE “CUBE”
LAST_SCHEMA_UPDATE Time stamp of last outline update
DESCRIPTION Database description
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_CUBES</RequestType>
<Restrictions>
<RestrictionList>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
Response Example
<SOAP-ENV:Body>
1183
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="CUBE_TYPE" type="xsd:string"
sql:field="CUBE_TYPE"/>
<xsd:element name="LAST_SCHEMA_UPDATE" type="xsd:dateTime"
sql:field="LAST_SCHEMA_UPDATE" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<CUBE_NAME>Demo.Basic</CUBE_NAME>
<CUBE_TYPE>CUBE</CUBE_TYPE>
</row>
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_DIMENSIONS Rowset
The DIMENSIONS rowset contains information about the dimensions in a given cube. Each
dimension has one row.
GUID: MDSCHEMA_DIMENSIONS
1184
Table 10 MDSCHEMA_DIMENSIONS Rowset structure
DIMENSION_NAME Dimension name
DIMENSION_UNIQUE_NAME Dimension name
DIMENSION_CAPTION Dimension name
DIMENSION_ORDINAL Dimension number. First dimension is 1, second is 2, and so on
DIMENSION_TYPE If Essbase dimension type is:

l TIME: MD_DIMTYPE_TIME
l ACCOUNTS: MD_DIMTYPE_MEASURE
l ALL OTHER: MD_DIMTYPE_OTHER
DIMENSION_CARDINALITY Number of members in the dimension
DEFAULT_HIERARCHY Dimension name
DESCRIPTION Comment added for the dimension
DIMENSION_UNIQUE_SETTINGS 2
DIMENSION_IS_VISIBLE True always
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_DIMENSIONS</RequestType>
<Restrictions>
<RestrictionList>
<CATALOG_NAME>Sample</CATALOG_NAME>
<CUBE_NAME>Basic</CUBE_NAME>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
1185
Response Example(truncated)
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="DIMENSION_NAME" type="xsd:string"
sql:field="DIMENSION_NAME"/>
<xsd:element name="DIMENSION_UNIQUE_NAME" type="xsd:string"
sql:field="DIMENSION_UNIQUE_NAME"/>
<xsd:element name="DIMENSION_CAPTION" type="xsd:string"
sql:field="DIMENSION_CAPTION"/>
<xsd:element name="DIMENSION_ORDINAL" type="xsd:unsignedInt"
sql:field="DIMENSION_ORDINAL"/>
<xsd:element name="DIMENSION_TYPE" type="xsd:short"
sql:field="DIMENSION_TYPE"/>
<xsd:element name="DIMENSION_CARDINALITY" type="xsd:unsignedInt"
sql:field="DIMENSION_CARDINALITY"/>
<xsd:element name="DEFAULT_HIERARCHY" type="xsd:string"
sql:field="DEFAULT_HIERARCHY"/>
<xsd:element name="DIMENSION_UNIQUE_SETTINGS" type="xsd:int"
sql:field="DIMENSION_UNIQUE_SETTINGS"/>
<xsd:element name="DIMENSION_IS_VISIBLE" type="xsd:boolean"
sql:field="DIMENSION_IS_VISIBLE"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<CUBE_NAME>Sample.Basic</CUBE_NAME>
1186
<DIMENSION_NAME>Year</DIMENSION_NAME>
<DIMENSION_UNIQUE_NAME>[Year]</DIMENSION_UNIQUE_NAME>
<DIMENSION_CAPTION>Year</DIMENSION_CAPTION>
<DIMENSION_ORDINAL>1</DIMENSION_ORDINAL>
<DIMENSION_TYPE>1</DIMENSION_TYPE>
<DIMENSION_CARDINALITY>19</DIMENSION_CARDINALITY>
<DEFAULT_HIERARCHY>[Year]</DEFAULT_HIERARCHY>
<DIMENSION_UNIQUE_SETTINGS>2</DIMENSION_UNIQUE_SETTINGS>
<DIMENSION_IS_VISIBLE>true</DIMENSION_IS_VISIBLE>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_FUNCTIONS Rowset
The FUNCTIONS rowset exposes all functions supported by the MDP. Default sort order:
ORIGIN, INTERFACE_NAME, and FUNCTION_NAME.
GUID: MDSCHEMA_FUNCTIONS
Table 11describes the rowset structure.
Table 11 MDSCHEMA_FUNCTIONS Rowset structure
FUNCTION_NAME Name of the function
DESCRIPTION Description of the function
PARAM_LIST A comma delimited list of parameters
RETURN_TYPE Always 12
ORIGIN 1 (always:MDX functions)
INTERFACE_NAME One of the following: Member, Set, Tuple, Numeric, Dimension, Level, Boolean
OBJECT One of the following values: Set, Member, Tuple, Level, Hierarchy, Dimension
HELP_CONTEXT Help context ID for the function
CAPTION Display caption of the function
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
1187
<RequestType>MDSCHEMA_FUNCTIONS</RequestType>
<Restrictions><RestrictionList></RestrictionList></Restrictions>
<Properties>
<PropertyList>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
Response Example (truncated)

<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="FUNCTION_NAME" type="xsd:string"
sql:field="FUNCTION_NAME"/>
sql:field="DESCRIPTION"/>
<xsd:element name="PARAMETER_LIST" type="xsd:string"
sql:field="PARAMETER_LIST"/>
<xsd:element name="RETURN_TYPE" type="xsd:int"
sql:field="RETURN_TYPE"/>
<xsd:element name="ORIGIN" type="xsd:int"
sql:field="ORIGIN"/>
<xsd:element name="INTERFACE_NAME" type="xsd:string"
sql:field="INTERFACE_NAME"/>
<xsd:element name="OBJECT" type="xsd:string"
sql:field="OBJECT" minOccurs="0"/>
<xsd:element name="HELP_CONTEXT" type="xsd:int"
sql:field="HELP_CONTEXT" minOccurs="0"/>
<xsd:element name="CAPTION" type="xsd:string"
1188
sql:field="CAPTION"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>

<row>
<FUNCTION_NAME>Ancestor</FUNCTION_NAME>
<DESCRIPTION>Given the input member, returns the ancestor
at the specified level.</DESCRIPTION>
<PARAMETER_LIST>Member, Level | Numeric Expression</PARAMETER_LIST>
<RETURN_TYPE>12</RETURN_TYPE>
<ORIGIN>1</ORIGIN>
<INTERFACE_NAME>Member</INTERFACE_NAME>
<HELP_CONTEXT>9142</HELP_CONTEXT>
<CAPTION>Ancestor</CAPTION>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_HIERARCHIES Rowset
The HIERARCHIES rowset contains information about the hierarchies available in a dimension.
GUID: MDSCHEMA_HIERARCHIES
Table 12 MDSCHEMA_HIERARCHIES Rowset Structure
HIERARCHY_NAME Dimension name
HIERARCHY_UNIQUE_NAME Dimension name
HIERARCHY_CAPTION Dimension name
DIMENSION_TYPE If Essbase dimension type is:

l TIME: MD_DIMTYPE_TIME
l ACCOUNTS: MD_DIMTYPE_MEASSURE
l ALL OTHER: MD_DIMTYPE_OTHER
HIERARCHY_CARDINALITY Number of members in the dimension
1189
DEFAULT_MEMBER Dimension name
ALL_MEMBER Dimension name
DESCRIPTION Dimension comment
STRUCTURE MD_STRUCTURE_UNBALANCED(2)
HIERARCHY_UNIQUE_SETTINGS 2
HIERARCHY_IS_VISIBLE True
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_HIERARCHIES</RequestType>
<Restrictions>
<RestrictionList>
<DIMENSION_UNIQUE_NAME>Year</DIMENSION_UNIQUE_NAME>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
Response Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
1190
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="HIERARCHY_NAME" type="xsd:string"
sql:field="HIERARCHY_NAME"/>
<xsd:element name="HIERARCHY_UNIQUE_NAME" type="xsd:string"
sql:field="HIERARCHY_UNIQUE_NAME"/>
<xsd:element name="HIERARCHY_CAPTION" type="xsd:string"
sql:field="HIERARCHY_CAPTION"/>
<xsd:element name="DIMENSION_TYPE" type="xsd:short"
sql:field="DIMENSION_TYPE"/>
<xsd:element name="HIERARCHY_CARDINALITY" type="xsd:unsignedInt"
sql:field="HIERARCHY_CARDINALITY"/>
<xsd:element name="DEFAULT_MEMBER" type="xsd:string"
sql:field="DEFAULT_MEMBER"/>
<xsd:element name="ALL_MEMBER" type="xsd:string"
sql:field="ALL_MEMBER"/>
<xsd:element name="STRUCTURE" type="xsd:int"
sql:field="STRUCTURE"/>
<xsd:element name="HIERARCHY_UNIQUE_SETTINGS" type="xsd:int"
sql:field="HIERARCHY_UNIQUE_SETTINGS"/>
<xsd:element name="HIERARCHY_IS_VISIBLE" type="xsd:boolean"
sql:field="HIERARCHY_IS_VISIBLE"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<HIERARCHY_NAME>Year</HIERARCHY_NAME>
<HIERARCHY_UNIQUE_NAME>[Year]</HIERARCHY_UNIQUE_NAME>
<HIERARCHY_CAPTION>Year</HIERARCHY_CAPTION>
<DIMENSION_TYPE>1</DIMENSION_TYPE>
<HIERARCHY_CARDINALITY>19</HIERARCHY_CARDINALITY>
<DEFAULT_MEMBER>[Year]</DEFAULT_MEMBER>
<ALL_MEMBER>[Year]</ALL_MEMBER>
<STRUCTURE>2</STRUCTURE>
<HIERARCHY_UNIQUE_SETTINGS>2</HIERARCHY_UNIQUE_SETTINGS>
<HIERARCHY_IS_VISIBLE>true</HIERARCHY_IS_VISIBLE>
1191
</row>
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_MEASURES Rowset
The MEASURES rowset contains information about the available measures.
GUID: MDSCHEMA_MEASURES
Table 13 MDSCHEMA_MEASURES Rowset Structure
MEASURE_NAME Member names in the Accounts dimension
MEASURE_UNIQUE_NAME Above member name
MEASURE_CAPTION Above member name
MEASURE_AGGREGATOR Essbase ADDITION: 1

Essbase SUBSTRACTION: 17
Essbase MULTIPLICATION:18
Essbase DIVISION:19
Essbase PERCENT:20
Essbase NOOP: 21
DESCRIPTION Member comment
DATA_TYPE 5
EXPRESSION Member formula
MEASURE_IS_VISIBLE True
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_MEASURES</RequestType>
<Restrictions>
1192
<RestrictionList>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="MEASURE_NAME" type="xsd:string"
sql:field="MEASURE_NAME"/>
<xsd:element name="MEASURE_UNIQUE_NAME" type="xsd:string"
sql:field="MEASURE_UNIQUE_NAME"/>
<xsd:element name="MEASURE_CAPTION" type="xsd:string"
sql:field="MEASURE_CAPTION"/>
<xsd:element name="MEASURE_AGGREGATOR" type="xsd:int"
sql:field="MEASURE_AGGREGATOR"/>
1193
<xsd:element name="DATA_TYPE" type="xsd:unsignedShort"
sql:field="DATA_TYPE"/>
<xsd:element name="NUMERIC_PRECISION" type="xsd:unsignedShort"
sql:field="NUMERIC_PRECISION"/>
<xsd:element name="NUMERIC_SCALE" type="xsd:short"
sql:field="NUMERIC_SCALE"/>
<xsd:element name="EXPRESSION" type="xsd:string"
sql:field="EXPRESSION" minOccurs="0"/>
<xsd:element name="MEASURE_IS_VISIBLE" type="xsd:boolean"
sql:field="MEASURE_IS_VISIBLE"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<MEASURE_NAME>Measures</MEASURE_NAME>
<MEASURE_UNIQUE_NAME>[Measures]</MEASURE_UNIQUE_NAME>
<MEASURE_CAPTION>Measures</MEASURE_CAPTION>
<MEASURE_AGGREGATOR>0</MEASURE_AGGREGATOR>
<DATA_TYPE>5</DATA_TYPE>
<NUMERIC_PRECISION>0</NUMERIC_PRECISION>
<NUMERIC_SCALE>0</NUMERIC_SCALE>
<MEASURE_IS_VISIBLE>true</MEASURE_IS_VISIBLE>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_MEMBERS Rowset
The MEMBERS rowset contains information about the available members.
GUID: MDSCHEMA_MEMBERS
Table 14 MDSCHEMA_MEMBERS Rowset Structure
LEVEL_UNIQUE_NAME Level name
LEVEL_NUMBER Level number
1194
GENERATION_NUMBER Generation number
MEMBER_ORDINAL Member number
MEMBER_NAME Member name
MEMBER_UNIQUE_NAME Unique member name
MEMBER_TYPE 1 (REGULAR)
MEMBER_CAPTION Member name
MEMBER_ALIAS Default alias
CHILDREN_CARDINALITY Child count
PARENT_LEVEL Level number of the parent. For dimension, same level number as the dimension level number
PARENT_UNIQUE_NAME Name of the parent. For dimension, same name as the dimension name
PARENT_COUNT Always 1
DESCRIPTION Member comment
Request Example
<SOAP-ENV:Envelope
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
secext-1.0.xsd">
<SOAP-ENV:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>system</wsse:Username>
<wsse:Password>password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_MEMBERS</RequestType>
<Restrictions>
<RestrictionList>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>
</DataSourceInfo>
1195
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="LEVEL_UNIQUE_NAME" type="xsd:string"
sql:field="LEVEL_UNIQUE_NAME"/>
<xsd:element name="LEVEL_NUMBER" type="xsd:unsignedInt"
sql:field="LEVEL_NUMBER"/>
<xsd:element name="GENERATION_NUMBER" type="xsd:unsignedInt"
sql:field="GENERATION_NUMBER"/>
<xsd:element name="MEMBER_ORDINAL" type="xsd:unsignedInt"
sql:field="MEMBER_ORDINAL"/>
<xsd:element name="MEMBER_NAME" type="xsd:string"
sql:field="MEMBER_NAME"/>
<xsd:element name="MEMBER_UNIQUE_NAME" type="xsd:string"
sql:field="MEMBER_UNIQUE_NAME"/>
<xsd:element name="MEMBER_TYPE" type="xsd:int"
sql:field="MEMBER_TYPE"/>
<xsd:element name="MEMBER_CAPTION" type="xsd:string"
1196
sql:field="MEMBER_CAPTION"/>
<xsd:element name="MEMBER_ALIAS" type="xsd:string"
sql:field="MEMBER_ALIAS" minOccurs="0"/>
<xsd:element name="CHILDREN_CARDINALITY" type="xsd:unsignedInt"
sql:field="CHILDREN_CARDINALITY"/>
<xsd:element name="PARENT_LEVEL" type="xsd:unsignedInt"
sql:field="PARENT_LEVEL"/>
<xsd:element name="PARENT_UNIQUE_NAME" type="xsd:string"
sql:field="PARENT_UNIQUE_NAME"/>
<xsd:element name="PARENT_COUNT" type="xsd:unsignedInt"
sql:field="PARENT_COUNT"/>
sql:field="DESCRIPTION" minOccurs="0" />
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<LEVEL_UNIQUE_NAME>[Year].Levels(2)</LEVEL_UNIQUE_NAME>
<LEVEL_NUMBER>2</LEVEL_NUMBER>
<GENERATION_NUMBER>1</GENERATION_NUMBER>
<MEMBER_ORDINAL>1</MEMBER_ORDINAL>
<MEMBER_NAME>Jan</MEMBER_NAME>
<MEMBER_UNIQUE_NAME>[Jan]</MEMBER_UNIQUE_NAME>
<MEMBER_TYPE>1</MEMBER_TYPE>
<MEMBER_CAPTION>Jan</MEMBER_CAPTION>
<CHILDREN_CARDINALITY>0</CHILDREN_CARDINALITY>
<PARENT_LEVEL>1</PARENT_LEVEL>
<PARENT_UNIQUE_NAME>[Qtr1]</PARENT_UNIQUE_NAME>
<PARENT_COUNT>1</PARENT_COUNT>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_PROPERTIES Rowset
The PROPERTIES rowset contains information about the available properties for each level of
the dimension, assuming that each level defines a class of members. The properties of all
members in this class are the same. For a data store that does not support named levels, a dummy
level includes all members in the dimension. The name of this level is the same as the name of
the dimension.
The default sort order: PROPERTY_TYPE, CATALOG_NAME, SCHEMA_NAME,
CUBE_NAME, DIMENSION_UNIQUE_NAME, HIERARCHY_UNIQUE_NAME, and
LEVEL_UNIQUE_NAME.
GUID: MDSCHEMA_PROPERTIES
1197
Table 15 MDSCHEMA_PROPERTIES Rowset Structure
LEVEL_UNIQUE_NAME Dimension name
PROPERTY_TYPE 1 (MDPROP_MEMBER)
PROPERTY_NAME One of the following:

l For attribute dimension, the name of the dimension is the name of the property
l For UDA, the UDA name
l For aliases, the alias name
PROPERTY_CAPTION One of the following:

l For attribute dimensions, the attribute dimension name
DATA_TYPE 1 (double) – attribute dimension

2 (boolean) – attribute dimension
3 (string) – attribute dimension, UDA or alias
4 (integer) – attribute dimension
CHARACTER_MAXIMUM_LENGTH 80 (for UDA or an attribute dimension)

30 (for alias)
CHARACTER_OCTET_LENGTH 320 (for UDA or an attribute dimension)

120 (for alias)
PROPERTY_CONTENT_TYPE 0 (MD_PROPTYPE_REGULAR)
SQL_COLUMN_NAME One of the following:

l For attribute dimensions, the attribute dimension name
PROPERTY_ORIGIN 1 (MD_USER_DEFINED)
PROPERTY_ATTRIBUTE_HIERARCHY_NAME For attribute dimensions, the attribute dimension name
PROPERTY_CARDINALITY ONE (for UDA and aliases)

MANY (for attribute dimension)
1198
PROPERTY_IS_VISIBLE True
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_PROPERTIES</RequestType>
<Restrictions>
<RestrictionList>
<DIMENSION_UNIQUE_NAME>Product</DIMENSION_UNIQUE_NAME>
<LEVEL_UNIQUE_NAME>SKU</LEVEL_UNIQUE_NAME>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
1199
</xsd:complexType>
</xsd:element>
sql:field="LEVEL_UNIQUE_NAME" minOccurs ="0"/>
<xsd:element name="MEMBER_UNIQUE_NAME" type="xsd:string"
sql:field="MEMBER_UNIQUE_NAME" minOccurs ="0"/>
<xsd:element name="PROPERTY_TYPE" type="xsd:short"
sql:field="PROPERTY_TYPE" minOccurs ="0"/>
<xsd:element name="PROPERTY_NAME" type="xsd:string"
sql:field="PROPERTY_NAME" minOccurs ="0"/>
<xsd:element name="PROPERTY_CAPTION" type="xsd:string"
sql:field="PROPERTY_CAPTION" minOccurs ="0"/>
<xsd:element name="DATA_TYPE" type="xsd:unsignedShort"
sql:field="DATA_TYPE" minOccurs ="0"/>
<xsd:element name="CHARACTER_MAXIMUM_LENGTH"
type="xsd:unsignedInt"
sql:field="CHARACTER_MAXIMUM_LENGTH" minOccurs ="0"/>
<xsd:element name="CHARACTER_OCTET_LENGTH" type="xsd:unsignedInt"
sql:field="CHARACTER_OCTET_LENGTH" minOccurs ="0"/>
<xsd:element name="NUMERIC_PRECISION" type="xsd:unsignedShort"
sql:field="NUMERIC_PRECISION" minOccurs ="0"/>
<xsd:element name="NUMERIC_SCALE" type="xsd:short"
sql:field="NUMERIC_SCALE" minOccurs ="0"/>
sql:field="DESCRIPTION" minOccurs ="0"/>
<xsd:element name="PROPERTY_CONTENT_TYPE" type="xsd:short"
sql:field="PROPERTY_CONTENT_TYPE" minOccurs ="0"/>
<xsd:element name="SQL_COLUMN_NAME" type="xsd:string"
sql:field="SQL_COLUMN_NAME" minOccurs ="0"/>
<xsd:element name="LANGUAGE" type="xsd:unsignedShort"
sql:field="LANGUAGE" minOccurs ="0"/>
<xsd:element name="PROPERTY_ORIGIN" type="xsd:unsignedShort"
sql:field="PROPERTY_ORIGIN" minOccurs ="0"/>
<xsd:element name="PROPERTY_ATTRIBUTE_HIERARCHY_NAME"
type="xsd:string"
sql:field="PROPERTY_ATTRIBUTE_HIERARCHY_NAME" minOccurs ="0"/>
<xsd:element name="PROPERTY_CARDINALITY" type="xsd:string"
sql:field="PROPERTY_CARDINALITY" minOccurs ="0"/>
<xsd:element name="MIME_TYPE" type="xsd:string"
sql:field="MIME_TYPE" minOccurs ="0"/>
<xsd:element name="PROPERTY_IS_VISIBLE" type="xsd:boolean"
sql:field="PROPERTY_IS_VISIBLE" minOccurs ="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
1200
<DIMENSION_UNIQUE_NAME>[Product]</DIMENSION_UNIQUE_NAME>
<HIERARCHY_UNIQUE_NAME>[Product]</HIERARCHY_UNIQUE_NAME>
<LEVEL_UNIQUE_NAME>[Product]</LEVEL_UNIQUE_NAME>
<PROPERTY_TYPE>1</PROPERTY_TYPE>
<PROPERTY_NAME>Caffeinated</PROPERTY_NAME>
<PROPERTY_CAPTION>Caffeinated</PROPERTY_CAPTION>
<DATA_TYPE>2</DATA_TYPE>
<PROPERTY_CONTENT_TYPE>0</PROPERTY_CONTENT_TYPE>
<SQL_COLUMN_NAME>Caffeinated</SQL_COLUMN_NAME>
<PROPERTY_ORIGIN>1</PROPERTY_ORIGIN>
<PROPERTY_ATTRIBUTE_HIERARCHY_NAME>Caffeinated
</PROPERTY_ATTRIBUTE_HIERARCHY_NAME>
<PROPERTY_CARDINALITY>MANY</PROPERTY_CARDINALITY>
<PROPERTY_IS_VISIBLE>true</PROPERTY_IS_VISIBLE>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
MDSCHEMA_SETS Rowset
The SETS rowset contains information about the sets in a schema (or the catalog, if the provider
does not support schemas).
GUID: MDSCHEMA_SETS
Table 16 MDSCHEMA_SETS Rowset Structure
SET_NAME Name of the set
SCOPE Session
MDSCHEMA_LEVELS Rowset
The LEVELS rowset contains information about the levels available in a dimension.
GUID: MDSCHEMA_LEVELS
1201
Table 17 MDSCHEMA_LEVELS Rowset Structure
DIMENSION_UNIQUE_NAME Name of the dimension to which the level belongs
HIERARCHY_UNIQUE_NAME Name of the dimension to which the level belongs
LEVEL_NAME Unique level name
LEVEL_UNIQUE_NAME Unique level name
LEVEL_CAPTION Level name
LEVEL_NUMBER Level number
LEVEL_CARDINALITY Number of members in the level
LEVEL_TYPE MDLEVEL_TYPE_ALL (for dimension level)

MDLEVEL_TYPE_TIME (for dimension type TIME)
MDLEVEL_TYPE_REGULAR (for all others)
LEVEL_UNIQUE_SETTINGS 2 (MDDIMENSIONS_MEMBER_NAME_UNIQUE)
LEVEL_IS_VISIBLE True
ESSBASE_GEN_UNIQUE_NAME Generation unique name
ESSBASE_GEN_CAPTION Generation caption
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>MDSCHEMA_LEVELS</RequestType>
<Restrictions>
<RestrictionList>
</RestrictionList>
</Restrictions>
<Properties>
<PropertyList>
</DataSourceInfo>
</PropertyList>
</Properties>
1202
</Discover>
</SOAP-ENV:Body>
Response Example
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="LEVEL_NAME" type="xsd:string"
sql:field="LEVEL_NAME"/>
sql:field="LEVEL_UNIQUE_NAME"/>
<xsd:element name="LEVEL_CAPTION" type="xsd:string"
sql:field="LEVEL_CAPTION"/>
<xsd:element name="LEVEL_NUMBER" type="xsd:unsignedInt"
sql:field="LEVEL_NUMBER"/>
<xsd:element name="LEVEL_CARDINALITY" type="xsd:unsignedInt"
sql:field="LEVEL_CARDINALITY"/>
<xsd:element name="LEVEL_TYPE" type="xsd:int"
sql:field="LEVEL_TYPE"/>
<xsd:element name="LEVEL_UNIQUE_SETTINGS" type="xsd:int"
sql:field="LEVEL_UNIQUE_SETTINGS"/>
<xsd:element name="LEVEL_IS_VISIBLE" type="xsd:boolean"
sql:field="LEVEL_IS_VISIBLE"/>
1203
<xsd:element name="ESSBASE_GEN_UNIQUE_NAME" type="xsd:string"
sql:field="ESSBASE_GEN_UNIQUE_NAME"/>
<xsd:element name="ESSBASE_GEN_CAPTION" type="xsd:string"
sql:field="ESSBASE_GEN_CAPTION"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<LEVEL_NAME>[Year].Levels(2)</LEVEL_NAME>
<LEVEL_UNIQUE_NAME>[Year].Levels(2)</LEVEL_UNIQUE_NAME>
<LEVEL_CAPTION>[Year].Level 2</LEVEL_CAPTION>
<LEVEL_NUMBER>2</LEVEL_NUMBER>
<LEVEL_CARDINALITY>12</LEVEL_CARDINALITY>
<LEVEL_TYPE>4</LEVEL_TYPE>
<LEVEL_UNIQUE_SETTINGS>2</LEVEL_UNIQUE_SETTINGS>
<LEVEL_IS_VISIBLE>true</LEVEL_IS_VISIBLE>
<ESSBASE_GEN_UNIQUE_NAME>[Year].[Months]</ESSBASE_GEN_UNIQUE_NAME>
<ESSBASE_GEN_CAPTION>[Year].Months</ESSBASE_GEN_CAPTION>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
DISCOVER_SCHEMA_ROWSETS Rowset
GUID: DISCOVER_SCHEMA_ROWSETS
Table 18 DISCOVER_SCHEMA Rowset Structure
SchemaName The name of the schema/request. This returns the values in the RequestTypes enumeration, plus any additional types
supported by the provider. The provider defines rowset structures for the additional types.
Restrictions List of restrictions allowed
Description Description of the schema
DISCOVER_DATASOURCES Rowset
GUID: DISCOVER_DATASOURCES
1204
Table 19 DISCOVER_DATASOURCES Rowset Structure
DataSourceName Name of the data source
DataSourceDescription Description of the data source
DataSourceInfo Provider=Essbase Data Source= name of the Analytic Server
ProviderName XMLA for Essbase
ProviderType MDP
AuthenticationMode Authenticated
DISCOVER_PROPERTIES Rowset
GUID: DISCOVER_PROPERTIES
Table 20 DISCOVER_PROPERTIES Rowset Structure
PropertyName Name of the property
PropertyDescription Description of the property
PropertyType XML data type of the property.
PropertyAccessType Access for the property. The value can be Read, Write, or ReadWrite
IsRequired True if a property is required, false if it is not required
Value Current value of the property
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>DISCOVER_PROPERTIES</RequestType>
<Restrictions>
</Restrictions>
<Properties>
<PropertyList>
</DataSourceInfo>
</PropertyList>
1205
</Properties>
</Discover>
</SOAP-ENV:Body>
Response Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="PropertyName" type="xsd:string"
sql:field="PropertyName"/>
<xsd:element name="PropertyDescription" type="xsd:string"
sql:field="PropertyDescription"/>
<xsd:element name="PropertyType" type="xsd:string"
sql:field="PropertyType"/>
<xsd:element name="PropertyAccessType" type="xsd:string"
sql:field="PropertyAccessType"/>
<xsd:element name="IsRequired" type="xsd:boolean"
sql:field="IsRequired"/>
<xsd:element name="Value" type="xsd:string"
sql:field="Value"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<PropertyName>ProviderName</PropertyName>
<PropertyDescription>The name of the Analytic Services Provider
</PropertyDescription>
<PropertyType>string</PropertyType>
<PropertyAccessType>Read</PropertyAccessType>
<IsRequired>false</IsRequired>
<Value>Analytic Services XML for Analysis Provider</Value>
</row>
1206
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
DISCOVER_ENUMERATORS Rowset
GUID: DISCOVER_ENUMERATORS
Table 21 DISCOVER_ENUMERATORS Rowset Structure
EnumName Name of the enumerator that contains a set of values
EnumDescription Description of the enumerator
ElementName Name of one of the value elements in the enumerator set

Example: TDP
ElementDescription Description of the element
EnumType Data type of the Enum values
ElementValue Value of the element

Example: 01
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>DISCOVER_ENUMERATORS</RequestType>
<Restrictions>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
1207
Response Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="EnumName" type="xsd:string"
sql:field="EnumName"/>
<xsd:element name="EnumDescription" type="xsd:string"
sql:field="EnumDescription" minOccurs="0"/>
<xsd:element name="ElementName" type="xsd:string"
sql:field="ElementName"/>
<xsd:element name="ElementDescription" type="xsd:string"
sql:field="ElementDescription" minOccurs="0"/>
<xsd:element name="ElementValue" type="xsd:string"
sql:field="ElementValue" minOccurs="0"/>
<xsd:element name="EnumType" type="xsd:string"
sql:field="EnumType"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row>
<EnumName>ProviderType</EnumName>
<ElementName>TDP</ElementName>
<EnumType>string</EnumType>
</row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
1208
DISCOVER_KEYWORDS Rowset
GUID: DISCOVER_KEYWORDS
Table 22 DISCOVER_KEYWORDS Rowset Structure
Keyword A list of keywords reserved by a provider

Example: AND
Request Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<RequestType>DISCOVER_KEYWORDS</RequestType>
<Restrictions>
</Restrictions>
<Properties>
<PropertyList>
<DataSourceInfo>
</DataSourceInfo>
</PropertyList>
</Properties>
</Discover>
</SOAP-ENV:Body>
Response Example
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<m:DiscoverResponse
xmlns:m="urn:schemas-microsoft-com:xml-analysis">
1209
<xsd:complexType>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Keyword" type="xsd:string"
sql:field="Keyword"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<row><Keyword>aggregate</Keyword></row>
<row><Keyword>ancestors</Keyword></row>
< ................More Rows............. >
</root>
</m:return>
</SOAP-ENV:Body>
DISCOVER_LITERALS Rowset
GUID: DISCOVER_LITERALS
the section called “Example 1” describes the rowset structure.
Table 23 DISCOVER_LITERALS Rowset Structure
LiteralName Name of the literal described in the row

Example: DBLITERAL_LIKE_PERCENT
LiteralValue Contains the literal value

Example, if LiteralName is DBLITERAL_LIKE_PERCENT and the percent character (%) is used to match zero
or more characters in a LIKE clause, this column’s value would be “%.”
LiteralInvalidChars Characters, in the literal, that are not valid

Example: If table names can contain anything other than a numeric character, this string would be
“0123456789”
LiteralInvalidStartingChars Characters that are not valid as the first character of the literal. If the literal can start with any valid character,
this is null.
LiteralMaxLength Maximum number of characters in the literal. If there is no maximum or the maximum is unknown, the value
is -1.
1210
Flattened Rowset Examples
Flattening a rowset is a way to present multidimensional data in a grid. This two-dimensional,
tabular presentation of data can facilitate understanding of the output of a multidimensional
XMLA request.
MDX Examples
The following examples illustrate flattened rowsets as MDX queries and results. MDX is used
for ease of presentation; however, the example queries are intended to be considered in terms
of XMLA SOAP requests. Remember that in XMLA, level 0 represents a dimension, rather than
a leaf member, as in MDX. Therefore, although these examples are in MDX, the levels are
reversed as if they were in XMLA.
Example 1
The following query requests all members of level 1.
SELECT NON EMPTY {[Profit]} ON COLUMNS,
NON EMPTY [Product].Levels(1).ALLMEMBERS ON ROWS
FROM Sample.Basic
This query has the following result:
[Product].[Family].[MEMBER_CAPTION] [Profit]
100 30468
200 27954
300 25799
400 21301
Diet 28826
Example 2
The following query requests a maximum of two levels. The flattening of rowsets includes level
1 in this request for levels(2). When using flattened rowsets, if you query for level N, levels 1
through N are returned.
SELECT NON EMPTY {[Profit] } ON COLUMNS,
NON EMPTY [Product].Levels(2).ALLMEMBERS ON ROWS
FROM Sample.Basic
This query has the following result (truncated):
1211
[Product].[Family].[MEMBER_CAPTION] [Product].[SKU].[MEMBER_CAPTION] [Profit]
100 100–10 22777
100 100–20 5708
100 100–30 1983
200 200–10 7201
200 200–20 12025
200 200–30 4636
200 200–40 4092
... ... ...
Example 3
The following query builds on the previous, and also asks for the result set to include the member
unique name and level number properties for the set of levels 1 through N, where N=2. Each
member and each property is allotted a row.
SELECT NON EMPTY {[Profit]} ON COLUMNS,
NON EMPTY [Product].Levels(2).ALLMEMBERS
DIMENSION PROPERTIES MEMBER_UNIQUE_NAME, LEVEL_NUMBER
ON ROWS
FROM Sample.Basic
[Product]. [Family].
[MEMBER_ UNIQUE_ [Product]. [Family]. [Product]. [SKU]. [MEMBER_ [Product]. [SKU].
NAME] LEVEL_ NUMBER UNIQUE_ NAME] LEVEL_ NUMBER [Profit]
[100] 1 [100–10] 2 22777
[100] 1 [100–20] 2 5708
[100] 1 [100–30] 2 1983
[200] 1 [200–10] 2 7201
[200] 1 [200–20] 2 12025
[200] 1 [200–30] 2 4636
[200] 1 [200–40] 2 4092
[300] 1 [300–10] 2 12195
[300] 1 [300–20] 2 2511
[300] 1 [300–30] 2 2511
1212
[Product]. [Family].
[MEMBER_ UNIQUE_ [Product]. [Family]. [Product]. [SKU]. [MEMBER_ [Product]. [SKU].
NAME] LEVEL_ NUMBER UNIQUE_ NAME] LEVEL_ NUMBER [Profit]
... ... ... ... ...
Example 4
By implementing CrossJoin in a flattened rowsets query, you can use multiple dimensions (at
least two). In this example, Market and Product dimensions are requested. For each dimension,
the same logic as in previous examples applies: Each dimension, level, and property is allotted
one column (in this case, one level and one property are requested).
SELECT NON EMPTY {[Profit] } ON COLUMNS,
NON EMPTY Crossjoin ([Market].Levels(1).AllMembers,[Product].Levels(1).ALLMEMBERS)
DIMENSION PROPERTIES MEMBER_CAPTION
ON ROWS
FROM Sample.Basic
[Market]. Levels(1). [MEMBER_CAPTION] [Product]. [Family]. [MEMBER_CAPTION] [Profit]
East Colas 12656
East Root Beer 2534
East Cream Soda 2627
East Fruit Soda 6344
East Diet Drinks 2408
West Colas 3549
West Root Beer 9727
West Cream Soda 10731
West Fruit Soda 5854
West Diet Drinks 8087
... ... ...
Example 5
In this example, CrossJoin is used to request levels 1–2 for Market and Product.
SELECT NON EMPTY { [Profit] } ON COLUMNS,
DIMENSION PROPERTIES MEMBER_CAPTION
ON ROWS
FROM Sample.Basic
1213
[Market]. Levels(1). [Market]. Levels(2). [Product]. [Family]. [Product]. [SKU].

[MEMBER_ CAPTION] [MEMBER_ CAPTION] [MEMBER_ CAPTION] [MEMBER_ CAPTION] [Profit]
East New York Colas Cola 3498
East New York Root Beer Old Fashioned -2594
East New York Root Beer Birch Beer 3086
East New York Cream Soda Dark Cream 2496
East New York Cream Drinks Vanilla Cream -1952
East New York Fruit Soda Grape 1329
East New York Fruit Soda Orange 1388
East New York Fruit Soda Strawberry 951
... ... ... ... ...
Example 6
The following example uses CrossJoin to represent multiple dimensions, requests a different
number of levels for each dimension, and requests multiple properties.
DIMENSION PROPERTIES MEMBER_CAPTION, LEVEL_NUMBER
ON ROWS
FROM Sample.Basic
[Market]. [Market]. [Product]. [Market]. [Market].

Levels(1). Levels(1). [Family]. Levels(1). [Product]. [SKU]. Levels(1).
[MEMBER_ [LEVEL_ [MEMBER_ [LEVEL_ [MEMBER_ [LEVEL_
CAPTION] NUMBER] CAPTION] NUMBER] CAPTION] NUMBER] [Profit]
East 1 Colas 1 Cola 2 11129
East 1 Colas 1 Diet Cola 2 1114
East 1 Colas 1 Caffeine Free Cola 2 413
East 1 Root Beer 1 Old Fashioned 2 -2540
East 1 Root Beer 1 Diet Root Beer 2 982
East 1 Root Beer 1 Birch Beer 2 4092
East 1 Cream Soda 1 Dark Cream 2 3233
East 1 Cream Soda 1 Vanilla Cream 2 -918
1214
[Market]. [Market]. [Product]. [Market]. [Market].
Levels(1). Levels(1). [Family]. Levels(1). [Product]. [SKU]. Levels(1).
[MEMBER_ [LEVEL_ [MEMBER_ [LEVEL_ [MEMBER_ [LEVEL_
CAPTION] NUMBER] CAPTION] NUMBER] CAPTION] NUMBER] [Profit]
... ... ... ... ... ... ...
Example 7
The following example uses multiple, nested CrossJoins.
NON EMPTY {CROSSJOIN
(
CROSSJOIN( [Market].Levels(1).ALLMEMBERS,
[Product].[Family].ALLMEMBERS
),
[Year].Levels(1).ALLMEMBERS
)
} DIMENSION PROPERTIES MEMBER_CAPTION
ON ROWS FROM Sample.Basic
[Market]. Levels(1). [MEMBER_ [Product]. [Family]. [MEMBER_ [Year]. Levels(1). [MEMBER_

CAPTION] CAPTION] CAPTION] [Profit]
East Colas Qtr1 2747
East Root Beer Qtr1 562
... ... ... ...
XMLA Examples
The following examples illustrate an XMLA response and request.
This is an example of a flattened rowset request. To flatten the result, you must use Tabular
format in the PropertyList element, as shown in the example.
1215
<SOAP-ENV:Body>
<Execute xmlns="urn:schemas-microsoft-com:xml-analysis"
<Command>
<Statement>
WITH MEMBER [Year].[calctest] AS '4'
NON EMPTY {[Year].ALLMEMBERS } ON ROWS
FROM Sample.Basic
</Statement>
</Command>
<Properties>
<PropertyList>
</DataSourceInfo>
<Catalog>Sample</Catalog>
<AxisFormat>TupleFormat</AxisFormat>
</PropertyList>
</Properties>
</Execute>
</SOAP-ENV:Body>
An example of a flattened rowset response:

<SOAP-ENV:Body>
<m:ExecuteResponse xmlns:m="urn:schemas-microsoft-com:xml-analysis">
<m:return
<xsd:complexType>
<xsd:element name="row" type="row" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="column1" type="xsd:string"
sql:field="[Year].Levels(1).[MEMBER_CAPTION]" minOccurs="0"/>
<xsd:element name="column2" type="xsd:string"
sql:field="[Year].Levels(2).[MEMBER_CAPTION]" minOccurs="0"/>
<xsd:element name= "column3" type="xsd:double"
sql:field= "[Profit]" minOccurs="0"/>
</xsd:sequence>
1216
</xsd:complexType>
</xsd:schema>
<row>
<column3>105522.000000</column3>
</row>
<row>
<column1>Qtr1</column1>
<column3>24703.000000</column3>
</row>
<row>
<column2>Jan</column2>
<column3>8024.000000</column3>
</row>
<row>
<column2>Feb</column2>
</row>
<row>
<column2>Mar</column2>
</row>
<row>
<column3>27107.000000</column3>
</row>
<row>
<column2>Apr</column2>
</row>
<row>
<column2>May</column2>
</row>
<row>
<column2>Jun</column2>
</row>
<row>
<column3>27912.000000</column3>
</row>
<row>
<column2>Jul</column2>
</row>
<row>
<column2>Aug</column2>
1217
</row>
<row>
<column2>Sep</column2>
</row>
<row>
<column3>25800.000000</column3>
</row>
<row>
<column2>Oct</column2>
</row>
<row>
<column2>Nov</column2>
</row>
<row>
<column2>Dec</column2>
</row>
<row>
<column1>calctest</column1>
</row>
</root>
</m:return>
</m:ExecuteResponse>
</SOAP-ENV:Body>
1218
API Sample Programs
A
In This Appendix
Sample C API Program 1 (cs1.c) ..................................................................... 1219
Sample C API Program 1 (cs1.c)

This file contains an annotated Essbase C API program. This fundamental sample program can
be used in a C++ programming environment as a starting point for more functional programs.
This file is to be used with the Oracle Essbase API Reference to illustrate basic points in API
programming. A complete set of actual C code files is also included with the Essbase API. Look
in the samples directory of this documentation for the *.c files, executables, projects, and
workspaces.
/*
Copyright 1992-2008 Oracle Corporation. All Rights Reserved.
NAME
cs1.c
DEPENDENCIES
You must add ESSAPIN.LIB to your project.
You must also identify the /API/Include and /API/Lib
directories to the compiler/linker.
DESCRIPTION
This file is used for testing of the Main API and
describing the most fundamental aspects of the Essbase API.
This simple application program is intended as a starting
point for more complex programs. This program performs only
the most basic initialization and login functions. It
connects to a server/application/database, performs only
the most basic of tasks (lists connected users), disconnects,
logs out and terminates. Because all Essbase API programs
must do these things, this program represents the
most simple API program possible. It is applicable in the
most general sense to being used as a starting point for
more useful and complex production-oriented programs.
NOTES
This program has three sections:
1219
1 - The includes and function definitions
2 - The function declarations
3 - The main flow
MODIFIED
* Created 26 Aug 1999 publications
*/
/***********************************************************/
/***********************************************************/
/***********************************************************/
/*
Declaration of Include files
*/

#endif
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#pragma pack (1)
#include <essapi.h>
#include <essotl.h>
#pragma pack ()
/*
Declaration of handles and connection information variables
*/
ESS_HINST_T hInst;
ESS_HCTX_T hCtx;
ESS_SVRNAME_T srvrName = "";
ESS_USERNAME_T userName = "";
ESS_PASSWORD_T pswd = "";
/*
Declaration of all the Essbase API functions used in this
program. You could declare all the functions here, and have
them available for the prototype section. This program only
uses a few functions.
*/
/* Initialization and Login functions */

void ESS_Init();
void ESS_AutoLogin();
void ESS_Login(); //This app uses EssAutoLogin().
void ESS_LoginSetPassword(); //I declared these other loginvoid
ESS_AutoLoginSetPassword(); //functions for future use.
void ESS_Logout();
void ESS_Term();
void ESS_GetVersion();
void ESS_GetAPIVersion();
void ESS_SetActive();
1220
void ESS_ListDatabases();
void ESS_ListUsers();
void ESS_Free();
/************* START FUNCTION DECLARATIONS ***************/

/**********************************************************/
void ESS_Init()
{
ESS_STS_T sts;
NULL,
0L,
255,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
0L
};
{
exit ((int) sts);
}
}
/*****************************************************/
/*****************************************************/
void ESS_Login ()
{
ESS_USHORT_T Items;
sts = EssLogin (hInst, srvrName, userName,

pswd, &Items, &pAppsDbs, &hCtx);
if ( (sts == 1051093L) || (sts == 1051090L) )
{ ESS_LoginSetPassword(); }
else
if ( (sts != 0) && (sts != 1051093L) && (sts != 1051090L) )
{
printf("\n\tUsage: ");
printf("MAINAPI servername username password\n");
printf("\tDefault: \n\tserver name: local\n\t");
printf("user name: admin\n\tpassword: password\n");
exit ((int) sts);

}
}
1221
/*****************************************************/
/*****************************************************/
void ESS_AutoLogin ()
{
ESS_CHAR_T SvrName[ESS_SVRNAMELEN]; //this is different in VC++6
ESS_CHAR_T AppName[ESS_APPNAMELEN];
ESS_CHAR_T DbName[ESS_DBNAMELEN];
// ESS_HCTX_T hCtx; Don't set this again, it is set in EssInit
strcpy(UserName,"Admin");
strcpy(Password,"Password");
strcpy(AppName,"");
strcpy(DbName,"");

sts = EssAutoLogin (hInst, SvrName, UserName, Password,
AppName, DbName, Option, &Access, &hCtx);
printf("EssAutoLogin sts: %ld\r\n", sts);
}
/*****************************************************/
/*****************************************************/
void ESS_LoginSetPassword()
{
ESS_USHORT_T Items;
ESS_PASSWORD_T newPswd = "password2";
sts = EssLoginSetPassword (hInst, srvrName, userName, pswd, newPswd,

printf("EssLoginSetPassword sts: %ld\r\n", sts);
if (sts)
{ printf("\n\tEssLoginSetPassword sts: %ld\n",sts);
exit ((int) sts);
}
}
/*****************************************************/
/*****************************************************/
void ESS_GetAPIVersion()
{
1222
if(!sts)
printf("API Version %#x\n",Version);
}
/*****************************************************/
/*****************************************************/
void ESS_Term()
{
{
}
printf("EssTerm sts: %ld\r\n", sts);
}
/*****************************************************/
/*****************************************************/
void ESS_Logout()
{

}
/*****************************************************/
/*****************************************************/
void ESS_GetVersion()
{
sts = EssGetVersion (hCtx, &Release, &Version, &Revision);

printf("EssGetVersion sts: %ld\r\n", sts);
if(!sts)
{
printf("\r\nEssbase Application Server - ");
printf("Version %d.%d.%d\r\n", Release, Version, Revision);
}
}
/*****************************************************/
/*****************************************************/
1223
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "sample";
DbName = "basic";
printf("EssSetActive sts: %ld\r\n",sts);
}
/*****************************************************/
/*****************************************************/
void ESS_ListDatabases()
{
ESS_USHORT_T Items;
ESS_USHORT_T ind;
sts = EssListDatabases(hCtx, NULL, &Items, &pAppsDbs);

printf("EssListDatabases sts: %ld\r\n",sts);
if(!sts)
{
if(Items && pAppsDbs)
{
printf("\r\n--Applications/databases available--\r\n");
{
if((pAppsDbs+ind) !=NULL)
{
if((pAppsDbs[ind].AppName != NULL)
&& (pAppsDbs[ind].DbName != NULL))
{
printf("%s",pAppsDbs[ind].AppName);
printf(" ==> ");
printf("%s",pAppsDbs[ind].DbName);
printf("\n\r");
}
}
}
}
else
printf("\r\nDatabase List is Empty\r\n\r\n");
}
}
/*****************************************************/
/*****************************************************/
void ESS_ListUsers()
{
1224
ESS_STS_T sts;
ESS_USHORT_T Count;
ESS_USHORT_T ind;
sts = EssListUsers (hCtx, NULL, NULL, &Count, &Users);

if (!sts)
{
if (Count && Users)
{
printf ("\r\n-----User List from EssListUsers()-----\r\n\r\n");
{
printf ("Name->%s\tApplication->%s\tdatabase->%s\r\n",
Users[ind].DbName);
// printf("Login %d\r\n",Users[ind].Login);
// printf("Type %d\r\n",Users[ind].Type);
// printf("Access %d\r\n",Users[ind].Access);
// printf("MaxAccess %d\r\n",Users[ind].MaxAccess);
// printf("Expiration %d\r\n",Users[ind].Expiration);
// printf("LastLogin %d\r\n",Users[ind].LastLogin);
// printf("FailCount %d\r\n",Users[ind].FailCount);
// printf("LoginId %ld\r\n",Users[ind].LoginId);
}
// printf("end of userlist %d\r\", count);
printf ("\r\n----User List from EssListUsers()-----\r\n\r\n");
printf("\r\n");
}
else
}
}
/*****************************************************/
/*************** MAIN FUNCTION ***********************/
/*
This is the actual program. It initializes and logs with EssAutoLogin,
then gets the Essbase Server version and the version of the API. It
sets the active application and lists the users connected to the
application. The output consists of simple printf statements.
*/
main()
{
ESS_Init();
ESS_AutoLogin();
/*
Every Essbase API program must issue EssInit to get the context
handle (hCtx). The EssLogin is required to connect to a
database/application. Almost any functions can follow the Init and Login.
We used EssAutoLogin to display the Connect dialog box, but this
program could have used EssLogin and retrieve the Username and
1225
Password as command line arguments. Following sample programs will
illustrate the use of command line arguments.
*/
/*
The following statements perform some of the most simple actions. The
output, in the form of printf statements, is done by the individual
functions. The EssFree functions that release allocated memory are
also in the individual functions. More complex programs will not free
memory in the individual functions because the allocated structures
and handles are needed until the end.
These simple actions can easily be more complex. Additional operations

would be added in this section. Following sample programs will do more,
but this program merely retrieves some basic information and displays it.
*/
ESS_GetVersion();
ESS_GetAPIVersion();
ESS_SetActive();
ESS_ListDatabases();
ESS_ListUsers();
/*
The EssLogout disconnects the user from the Essbase Server, application,
and database. The EssTerm ends the program and frees allocated memory,
such as the context handle.
*/
ESS_Logout();
ESS_Term();
}
/*
End of program
*/

programming. A complete set of actual C code files is also included with the Essbase API. Look
in the samples directory for the *.c files, executables, projects, and workspaces.
/*
NAME
cs2.c
DEPENDENCIES
DESCRIPTION
This file is used as an example of a simple
1226
applications program. This program performs basic initialization and
login and queries the active application/database. It then manipulates
the user list, adding, renaming, and deleting a new user.
NOTES
1 - The includes and function definitions
2 - The function declarations
3 - The main flow
MODIFIED
* Modified 03 Sep 1999 Publications
*/
/*********************************************************************/
/***************** START FUNCTION DEFINITIONS **********************/
/*********************************************************************/

#endif
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#pragma pack (1)
#include <essapi.h>
#include <essotl.h>
#pragma pack ()
ESS_HINST_T hInst;
ESS_HCTX_T hCtx;

void ESS_Init();
// void ESS_Login(); /* Requires command line arguments */
void ESS_Logout();
void ESS_Term();
void ESS_AutoLogin(); /* Displays the login dialog box */
void ESS_LoginSetPassword(); /* Called if EssAutoLogin returns error */
/* Application functions */
// void ESS_GetActive();
void ESS_ListApplications();
void ESS_GetDatabaseInfo();
void ESS_ListUsers(); /* These functions will be called repeatedly */

void ESS_CreateUser (); /* to create a user, list users, rename the */
1227
void ESS_RenameUser(); /* new user, list users again, then delete */
void ESS_DeleteUser(); /* the new users and list users again */
void ESS_GetUserInfo ();
/**********************************************************************/
/***************** START FUNCTION DECLARATIONS **********************/
/**********************************************************************/
void ESS_Init()
{
ESS_STS_T sts;
NULL,
0L,
255,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
0L
};
{ printf("EssInit failure: %ld\n", sts);
exit ((int) sts);
}
}
/**********************************************************************/
void ESS_Login ()
{
ESS_USHORT_T Items;
sts = EssLogin (hInst, srvrName, userName, pswd, &Items,

&pAppsDbs, &hCtx);
if ( (sts == 1051093L) || (sts == 1051090L) )
else
if ( (sts != 0) && (sts != 1051093L) && (sts != 1051090L) )
{ printf("\n\tUsage: MAINAPI servername username password\n");
exit ((int) sts);

}
}
/**********************************************************************/
{
1228
// ESS_HCTX_T hCtx; Don't set this again, it is set at the top
strcpy(AppName,"");
strcpy(DbName,"");

}
/**********************************************************************/
{
ESS_USHORT_T Items;
sts = EssLoginSetPassword (hInst, srvrName, userName, pswd, newPswd,

if (sts)
exit ((int) sts);
}
}
/**********************************************************************/
{
if(!sts)
}
/**********************************************************************/
void ESS_Term()
{
1229
{
}
}
/**********************************************************************/
void ESS_Logout()
{

}
/**********************************************************************/
{

if(!sts)
{
}
}
/********************************************************************/
void ESS_GetActive()
{
ESS_STR_T pDbName;
ESS_STR_T pAppName;
if((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pAppName)) == 0)

{
if((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pDbName)) == 0)
{
if((sts =
EssGetActive(hCtx, &pAppName, &pDbName, &Access)) == 0)
{
if(pAppName)
{
if(*pAppName)
printf("Current active app: [%s]\r\n",pAppName);
else
printf("No active Application is set\r\n");
}
1230
EssFree(hInst, pDbName);
}
EssFree(hInst, pAppName);
}
}
}
/**********************************************************************/
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "sample";
DbName = "basic";
}
/**********************************************************************/
void ESS_ListApplications()
{
ESS_PAPPNAME_T strp = NULL;
ESS_USHORT_T Items;
ESS_USHORT_T ind;
sts = EssListApplications(hCtx, &Items, &strp);

if(!sts)
{
if(Items && strp)
{
printf("Applications availables\r\n");
for(ind = 0; ind <Items; ind++)
{
if(strp[ind] != NULL)
printf("%s\r\n", strp[ind]);
}
EssFree(hInst, strp);
}
else
printf("\r\nApplication List is Empty\r\n\r\n");
}
}
/**********************************************************************/
{
ESS_USHORT_T Items;
ESS_USHORT_T ind;

1231
if(!sts)
{
{
{
{
{
printf(" ==> ");
printf("\n\r");
}
}
}
}
else
}
}
/**********************************************************************/
void ESS_GetDatabaseInfo()
{
ESS_PDBINFO_T DbInfo;
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "Sample";
DbName = "Basic";
sts = EssGetDatabaseInfo(hCtx, AppName, DbName, &DbInfo);

if(!sts)
{
printf("\r\n----- Results of EssGetDatabaseInfo -----\r\n");
printf("AppName: %s\r\n",DbInfo->AppName);
printf("DbName: %s\r\n",DbInfo->Name);
printf("DbType: %d\r\n",DbInfo->DbType);
printf("Status: %d\r\n",DbInfo->Status);
printf("nConnects: %d\r\n",DbInfo->nConnects);
printf("nLocks: %d\r\n",DbInfo->nLocks);
printf("nDims: %d\r\n",DbInfo->Data);
printf("Country: %s\r\n",DbInfo->Country);
printf("Time: %s\r\n",DbInfo->Time);
printf("Category: %s\r\n",DbInfo->Category);
printf("Type: %s\r\n",DbInfo->Type);
printf("CrPartition: %s\r\n",DbInfo->CrPartition);
printf("\r\n----- Results of EssGetDatabaseInfo -----\r\n");
if(DbInfo)
1232
{
EssFree(hInst, DbInfo);
}
}
}
/*********************************************************************/
void ESS_ListUsers()
{
ESS_STS_T sts;
ESS_USHORT_T Count;
ESS_USHORT_T ind;
sts = EssListUsers (hCtx, NULL, NULL, &Count, &Users);

if (!sts)
{
if (Count && Users)
{
{
printf ("Name->%s\tApplication->%s\tdatabase->%s\r\n",
Users[ind].DbName);
}
printf("\r\n");
}
else
}
}
/**********************************************************************/
void ESS_CreateUser()
{
ESS_CHAR_T UserName[] = "newuser"; //this is different in VC++6

ESS_CHAR_T Password[] = "password"; //compare to API reference example
printf("Begin EssCreateUser Function");
sts = EssCreateUser (hCtx, UserName, Password);

printf("EssCreateUser sts: %ld",sts);
}
/**********************************************************************/
void ESS_RenameUser()
{
ESS_CHAR_T OldName[] = "newuser";
ESS_CHAR_T NewName[] = "user4";
1233
sts = EssRenameUser (hCtx, OldName, NewName);
}
/**********************************************************************/
void ESS_DeleteUser()
{
ESS_CHAR_T UserName[] = "user4";
sts = EssDeleteUser (hCtx, UserName);

printf("EssDeleteUser sts: %ld",sts);
}
/**********************************************************************/
void ESS_GetUserInfo ()
{
sts = EssGetUser (hCtx, "Jim Smith", &User);

printf("EssGetUserInfo %ld\r\n",sts);
if (!sts)
{
User->Name, User->AppName, User->DbName);
printf("Login %d\r\n",User->Login);
printf("Type %d\r\n",User->Type);
printf("Access %d\r\n",User->Access);
printf("MaxAccess %d\r\n",User->MaxAccess);
printf("Expiration %d\r\n",User->Expiration);
printf("LastLogin %d\r\n",User->LastLogin);
printf("FailCount %d\r\n",User->FailCount);
printf("LoginId %ld\r\n",User->LoginId);
if (User)
}
}
/**********************************************************************/
void getCmdLineArgs(int argc, char *argv[])
{
if (argc>1)
strcpy(srvrName,argv[1]);
if (argc>2)
strcpy(userName,argv[2]);
if (argc>3)
strcpy(pswd,argv[3]);
printf("Server name: %s\n",srvrName);

printf("User name: %s\n",userName);
printf("Password: %s\n",pswd);
}
1234
/*****************************************************/
/*************** MAIN FUNCTION ***********************/
/*****************************************************/

{
getCmdLineArgs(argc,argv);
ESS_Init();
ESS_AutoLogin();
ESS_GetVersion();
ESS_SetActive();
ESS_ListApplications();
ESS_GetDatabaseInfo();
ESS_ListUsers();
//ESS_CreateUser();
//ESS_RenameUser();
//ESS_DeleteUser();
//ESS_GetUserInfo ();
ESS_Logout();
ESS_Term();
}
/*
End of program
*/

programming. A complete set of actual C code files is also included with the Oracle Essbase API.
Look in the samples directory for the *.c files, executables, projects, and workspaces.
/*
NAME
cs3.c
DEPENDENCIES
You must add ESSAPIN.LIB to your project.
You must also identify the API/Include and API/Lib
directories to the compiler/linker.
DESCRIPTION
This file is used as an extended example of
API programming techniques. This program illustrates the sequence of
1235
function call expected by the Essbase Server and shows the syntax of
actual API function calls in an actual working program.
NOTES
1 - the includes and function definitions
2 - the function declarations
3 - the main program flow
MODIFIED
* Created 26July99 Publications
*/
/******************* Includes and Definitions ***********************/

/**********************************************************************/

#endif
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#pragma pack (1)
#include <essapi.h>
#include <essotl.h>
#pragma pack ()
ESS_HINST_T hInst;
ESS_HCTX_T hCtx;

void ESS_Init();
void ESS_Login();
void ESS_Logout();
void ESS_Term();
void ESS_AutoLogin();
void ESS_LoginSetPassword();
// void ESS_GetActive();
void ESS_UnloadDb();
void ESS_ClearDatabase();
/* Report - updating - Calculation */

void ESS_Report();
void ESS_RunRept ();
void ESS_ReportFile ();
1236
void ESS_Update();
void ESS_UpdateFile();
void ESS_Calc();
void ESS_CalcLine();
void ESS_RunCalc ();
void ESS_CalcFile();
void ESS_Import ();
void ESS_Free();
/***************** START FUNCTION DECLARATIONS *******************/

/*******************************************************************/
void ESS_Init()
{
ESS_STS_T sts;
NULL,
0L,
255,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
NULL,
0L
};
{ printf("EssInit failure: %ld\n", sts);
exit ((int) sts);
}
}
/**********************************************************************/
void ESS_Login ()
{
ESS_USHORT_T Items;
sts = EssLogin (hInst, srvrName, userName, pswd, &Items, &pAppsDbs,

&hCtx);
if ( (sts == 1051093L) || (sts == 1051090L) )
else
if ( (sts != 0) && (sts != 1051093L) && (sts != 1051090L) )
{
printf("\n\tUsage: MAINAPI servername username password\n");
exit ((int) sts);
}
}
1237
/**********************************************************************/
{
// ESS_HCTX_T hCtx; Don't set this again, it is set at the top
strcpy(AppName,"");
strcpy(DbName,"");

}
/**********************************************************************/
{
ESS_USHORT_T Items;
sts = EssLoginSetPassword (hInst, srvrName, userName, pswd, newPswd, &Items,

&pAppsDbs, &hCtx);
if (sts)
exit ((int) sts);
}
}
/**********************************************************************/
{
if(!sts)
}
1238
/**********************************************************************/
void ESS_Term()
{
{
}
}
/**********************************************************************/
void ESS_Logout()
{

}
/**********************************************************************/
{

if(!sts)
{
}
}
/**********************************************************************/
void ESS_GetActive()
{
ESS_STR_T pDbName;
ESS_STR_T pAppName;
if((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pAppName)) == 0)

{
if((sts = EssAlloc (hInst, 80, (ESS_PPVOID_T)&pDbName)) == 0)
{
if((sts =
EssGetActive(hCtx, &pAppName, &pDbName, &Access)) == 0)
{
if(pAppName)
{
1239
if(*pAppName)
printf("Current active app: [%s]\r\n",pAppName);
else
printf("No active Application is set\r\n");
}
EssFree(hInst, pDbName);
}
EssFree(hInst, pAppName);
}
}
}
/**********************************************************************/
{
ESS_STR_T AppName;
ESS_STR_T DbName;
AppName = "sample";
DbName = "basic";
}
/*********************************************************************/
{
ESS_USHORT_T Items;
ESS_USHORT_T ind;

if(!sts)
{
{
{
{
{
printf(" ==> ");
printf("\n\r");
}
}
}
1240
}
else
}
}
/*********************************************************************/
void ESS_ClearDatabase()
{
sts = EssClearDatabase(hCtx);
printf("EssClearDatabase sts:%ld\r\n",sts);
printf("The database is now empty\n");
}
/************************************************************************************/
void ESS_Report()
{
ESS_STR_T rString;
ESS_CHAR_T pszReportIn[512];
strcpy(pszReportIn,
" {TABDELIMIT} \
{SUPALL COLHEADING NAMESON BLOCKHEADERS PAGEHEAD INDENTGEN 2 DECIMALS \
VARIABLE} \
{BRACKET} \
<SINGLECOLUMN \
<QUOTEMBRNAMES \
{SUPMISSING} \
<BOTTOM ( 4, @DATACOL(1) ) \
<SYM \
<PAGE( 'Measures') \
'Measures' \
<COL( 'Market','Scenario') \
{ OUTALTNAMES } \
<ICHILDREN 'Market' \
'Actual' \
'Budget' \
<ROW( 'Year','Product') \
<ICHILDREN 'Year' \
<DIMBOTTOM 'Product' \
! " );
sts = EssReport (hCtx, ESS_TRUE, ESS_FALSE, pszReportIn);

//sts = EssReport (hCtx, ESS_TRUE, ESS_FALSE, "<Desc &ThisMonth !");
//sts = EssReport (hCtx, ESS_TRUE, ESS_FALSE, "<Desc Year !");
printf("EssReport sts: %ld\r\n",sts);
if(!sts)
sts = EssGetString(hCtx, &rString);
{
printf("%s", rString);
}
1241
printf("\r\n");
}
/**********************************************************************/
void ESS_Update()
{
sts = EssUpdate(hCtx, ESS_TRUE, ESS_FALSE,

"Year Market Scenario Measures Product 123456");
printf("EssUpdate sts: %ld\r\n",sts);
}
/**********************************************************************/
void ESS_CalcLine()
{
ESS_STR_T Script;
Script = "CALC DIM (Measures, Product, Market, Year, Scenario);";

if (!sts)
{
}
}
/***********************************************************************/
void ESS_Calc()
{
ESS_STR_T Script;

printf("EssBeginCalc sts: %ld\r\n",sts);
if (!sts)
{
printf("EssSendString sts: %ld\r\n",sts);
}
if (!sts)
{
printf("EssEndCalc sts: %ld\r\n",sts);
}
if (!sts)
{
while(!sts && (pState.State != ESS_STATE_DONE))
1242
}
}
/**********************************************************************/
void ESS_ReportFile ()
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T rString;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
hSrcCtx = hCtx;
AppName = "Sample";
DbName = "Basic";
FileName = "cdlockdb";
sts = EssReportFile (hCtx, hSrcCtx, AppName, DbName, FileName,

ESS_TRUE, ESS_FALSE);
printf("EssReportFile sts: %ld\r\n",sts);
if (!sts)
{
sts = EssGetString (hCtx,&rString);
}
}
/**********************************************************************/
void ESS_UpdateFile ()
{
ESS_HCTX_T hSrcCtx;
ESS_BOOL_T isStore;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
AppName = "Sample";
DbName = "Basic";
hSrcCtx = hCtx;
FileName = "cdupdtdb.txt";
isStore = ESS_TRUE;
sts = EssUpdateFile (hCtx, hSrcCtx, AppName, DbName, FileName,

isStore, isUnlock);
printf("EssUpdateFile sts: %ld\r\n",sts);
}
/**********************************************************************/
1243
void ESS_RunCalc ()
{
ESS_HCTX_T hSrcCtx;
ESS_STR_T AppName;
ESS_STR_T DbName;
ESS_STR_T FileName;
hSrcCtx = hCtx;
AppName = "Sample";
DbName = "Basic";
FileName = "calc5dim";
sts = EssCalcFile (hCtx, hSrcCtx, AppName, DbName, FileName,

ESS_TRUE);
printf("EssCalcFile sts: %ld\r\n",sts);
if (!sts)
{
}
}
/**********************************************************************/
void ESS_Import ()
{
eSS_STS_T sts = eSS_STS_NOERR;
eSS_SHORT_T isAbortOnError;
eSS_OBJDEF_T Rules;
eSS_OBJDEF_T Data;
eSS_PMBRERR_T pMbrErr = NULL;
Data.hCtx = hCtx;
Data.AppName = "Sample";
Data.DbName = "Basic";
Data.FileName = "calcdat.txt";
Rules.hCtx = hCtx;
Rules.AppName = "Olap";
Rules.DbName = "Demo";
Rules.ObjType = eSS_OBJTYPE_RULES;
Rules.FileName = "Actmap";
//* Running conditions *
isAbortOnError = eSS_TRUE;
sts = EssImport (hCtx, NULL, &Data, &pMbrErr, NULL, isAbortOnError);

if(pMbrErr)
1244
}
/**********************************************************************/
/*
This routine gets arguments from the command line. The routine under
stands a number of arguments will be present up to 3 arguments total
The first parameter, argc, is the number of arguments present
following the command to start (csamp3). The second parameter, argv,
is the array of arguments. This program (csamp3) has been built to
override the command line arguments, but could be easily modified to
use them. In other words, this routine is not used.
*/
void getCmdLineArgs(int argc, char *argv[])

{
if (argc>1)
strcpy(srvrName,argv[1]);
if (argc>2)
strcpy(userName,argv[2]);
if (argc>3)
strcpy(pswd,argv[3]);
printf("Server name: %s\n",srvrName);

printf("User name: %s\n",userName);
printf("Password: %s\n",pswd);
}
/******************* Program Main Flow ****************************/

/********************************************************************/

{
getCmdLineArgs(argc,argv);
/**** Initialization and Login Functions ****/
ESS_Init();
ESS_AutoLogin();
ESS_GetVersion();
ESS_SetActive();
/**** Report and Updating Calculation ****/

/*
This section issues a report to show what is in the database, then
clears all the data, runs another report to show that the database
is empty, then imports data from calcdat.txt, then finally, issues
another report to show that the database now has data.
*/
ESS_Report();
ESS_ClearDatabase();
ESS_Report();
ESS_Import ();
ESS_Report();
1245
/*
This section runs a calculation from a file. (ESS_RunCalc calls
EssCalcFile, which specifies the calculation script in the file
calc5dim.csc.) Then issues yet another report to show the results.
*/
ESS_CalcLine();
ESS_Report();
ESS_ReportFile();
ESS_UpdateFile();
ESS_ReportFile();
ESS_Logout();
ESS_Term();
}
/*
End of program
*/
1246
Shared Services Migration and
B User Management API Example
/*
Declaration of Include files
*/

#include
#endif
#include
#include
#include
#pragma pack (1)
#include
#include
#pragma pack ()
/
***************************************************************************************/
/*-------------------------- Example Usage Starts Here --------------------------------*/
/
***************************************************************************************/
/*
ESS_FUNC_M EssSetSSSecurityMode(ESS_HCTX_T hCtx,
ESS_USHORT_T Option,
ESS_STR_T Password);
*/
ESS_FUNC_M ESS_SS_SetSSSecurityMode(ESS_HCTX_T hCtx)
{

*
**/
sts = EssSetSSSecurityMode(hCtx, option, newpassword);
if(sts)
printf("Failed to migrate Analytic Services Server to Shared Services mode.
1247
\n");
return (sts);
}
/*
ESS_FUNC_M EssGetEssbaseSecurityMode (ESS_HCTX_T hCtx,
ESS_PSECURITY_MODE_T mode);
*/
ESS_FUNC_M ESS_SS_GetEssbaseSecurityMode(ESS_HCTX_T hCtx)
{
ESS_SECURITY_MODE_T mode;
sts = EssGetEssbaseSecurityMode(hCtx, &mode);
if(sts)
{
printf("Failed to get Essbase Security mode.\n");
}
else
{
printf("Essbase Security Mode : %d\n", mode);
}
return(sts);
}
/*
ESS_FUNC_M EssListSSMigrFailedUsers(ESS_HCTX_T,
ESS_PUSHORT_T,
ESS_PPUSERNAME_T);
*/
ESS_FUNC_M ESS_SS_ListSSMigrFailedUsers(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
index;
sts = EssListSSMigrFailedUsers(hCtx, &Count, &pNativeUserList);
if (!sts)
{
{
printf ("\n------- User List -------\n\n");

{
}
}
else
printf("\nUser list is empty\n\n");
1248
}
else
printf("Failed to get Shared Services migration failed Users list.\n");
return (sts);
}
/*
ESS_FUNC_M EssListSSMigrFailedGroups(ESS_HCTX_T,
ESS_PUSHORT_T,
ESS_PPUSERNAME_T);
*/
ESS_FUNC_M ESS_SS_ListSSMigrFailedGroups(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
index;
sts = EssListSSMigrFailedGroups(hCtx, &Count, &pNativeUserList);
if (!sts)
{
{
printf ("\n------- Group List -------\n\n");

{
}
}
else
printf("\nGroup list is empty\n\n");
}
else
printf("Failed to get Shared Services migration failed Groups list.\n");
return (sts);
}
/*
ESS_FUNC_M EssSetUserToSS (ESS_HCTX_T hCtx,
ESS_STR_T UserName,
*/
ESS_FUNC_M ESS_SS_SetUserToSS(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T userName = ESS_NULL;
1249
sts = EssAlloc(hInst, sizeof(ESS_USERNAME_T), &userName);
if(sts)
return (sts);
memset(userName, 0, sizeof(ESS_USERNAME_T));
strcpy( userName, "essexer");

*
**/
sts = EssSetUserToSS(hCtx, userName, option, newpassword);
if(sts)
printf("Failed to migrate User %s to Shared Services mode.\n", userName);
if (userName)
EssFree(hInst, userName);
return (sts);
}
/*
ESS_FUNC_M EssSetGroupToSS (ESS_HCTX_T hCtx,
ESS_STR_T GroupName);
*/
ESS_FUNC_M ESS_SS_SetGroupToSS(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T groupName = ESS_NULL;
sts = EssAlloc(hInst, sizeof(ESS_USERNAME_T), &groupName);

if(sts)
return (sts);
memset(groupName, 0, sizeof(ESS_USERNAME_T));
strcpy( groupName, "essgrp");
sts = EssSetGroupToSS(hCtx, groupName);
if(sts)
printf("Failed to migrate Group %s to Shared Services mode.\n", groupName);
if (groupName)
EssFree(hInst, groupName);
return (sts);
}
/*
ESS_FUNC_M EssSetUsersToSS(ESS_HCTX_T hCtx,
*/
1250
ESS_FUNC_M ESS_SS_SetUsersToSS(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{

*
**/
option = 0; /* Using user provided password */
sts = EssAlloc(hInst, sizeof(ESS_PASSWORD_T), &newpassword);

if(sts)
return (sts);
memset(newpassword, 0, sizeof(ESS_PASSWORD_T));
strcpy( newpassword, "password");
sts = EssSetUsersToSS(hCtx, option, newpassword);
if(sts)
printf("Failed to migrate Users to Shared Services mode.\n");
if (newpassword)
EssFree(hInst, newpassword);
return (sts);
}
/*
ESS_FUNC_M EssSetGroupsToSS(ESS_HCTX_T hCtx);
*/
ESS_FUNC_M ESS_SS_SetGroupsToSS(ESS_HCTX_T hCtx)
{
sts = EssSetGroupsToSS(hCtx);
if(sts)
printf("Failed to migrate Groups to Shared Services mode.\n");
return (sts);
}
/*
ESS_FUNC_M EssSetEasLocation (ESS_HCTX_T hCtx,
ESS_STR_T EasLocation);
*/
ESS_FUNC_M ESS_SS_SetEasLocation(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_STR_T easLoc = ESS_NULL;
/* Eas Location */
1251
sts = EssAlloc(hInst, sizeof(ESS_PATHLEN), &easLoc);
if(sts)
return (sts);
memset(easLoc, 0, sizeof(ESS_PATHLEN));
strcpy( easLoc, "localhost:10080");
sts = EssSetEasLocation(hCtx, easLoc);
if (sts)
printf("Failed to set EAS Location.\n");
if (easLoc)
EssFree(hInst, easLoc);
return (sts);
}
/*
ESS_FUNC_M EssReRegisterApplication (ESS_HCTX_T hCtx,
ESS_STR_T AppName,
ESS_BOOL_T AllApps);
*/
ESS_FUNC_M ESS_SS_ReRegisterApplication(ESS_HCTX_T hCtx, ESS_HINST_T hInst)
{
ESS_BOOL_T allApps;
ESS_STR_T appName = ESS_NULL;
sts = EssAlloc(hInst, sizeof(ESS_APPNAME_T), &appName);

if(sts)
return (sts);
memset(appName, 0, sizeof(ESS_APPNAME_T));
strcpy( appName, "Sample");
/* Do you want All applications re-registered?

* Enter ESS_TRUE for Yes
* ESS_FALSE for No
**/
allApps = ESS_FALSE; /* Re-registering only 1 application */
sts = EssReRegisterApplication(hCtx, appName, allApps);
if (sts)
printf("Failed to Re-register Application %s.\n", appName);
if (appName)
EssFree(hInst, appName);
return (sts);
}
/
***************************************************************************************/
/*-------------------------- Example Usage Starts Here --------------------------------*/
/
***************************************************************************************/
1252
/
***************************************************************************************/
/*--------------------------------- Testing API ---------------------------------------*/
/
***************************************************************************************/
/*
Declaration of handles and connection information variables
*/
/*****************************************************/
/*************** MAIN FUNCTION ***********************/
/*****************************************************/
main()
{
ESS_HINST_T hInst;
ESS_HCTX_T hCtx;
ESS_USHORT_T Items;

ESS_NULL,
0L,
255,
ESS_NULL,
ESS_NULL,
ESS_NULL,
ESS_NULL,
ESS_NULL,
ESS_NULL,
ESS_NULL,
0L
};
sts = EssInit(&InitStruct, &hlnst);

if (sts)
{
exit ((int) sts);
}
sts = EssLogin(hInst, srvrName, userName, pswd, &Items, &pAppsDbs, &hCtx);

if (sts)
{
exit ((int) sts);
}
sts = ESS_SS_SetSSSecurityMode(hCtx);
if (sts)
1253
printf("ESS_SS_SetSSSecurityMode failed: %ld\n", sts);
sts = ESS_SS_GetEssbaseSecurityMode(hCtx);
if (sts)
printf("ESS_SS_GetEssbaseSecurityMode failed: %ld\n", sts);
sts = ESS_SS_ListSSMigrFailedUsers(hCtx, hInst);

if (sts)
printf("ESS_SS_ListSSMigrFailedUsers failed: %ld\n", sts);
sts = ESS_SS_ListSSMigrFailedGroups(hCtx, hInst);

if (sts)
printf("ESS_SS_ListSSMigrFailedGroups failed: %ld\n", sts);
sts = ESS_SS_SetUserToSS(hCtx, hInst);

if (sts)
printf("ESS_SS_SetUserToSS failed: %ld\n", sts);
sts = ESS_SS_SetGroupToSS(hCtx, hInst);

if (sts)
printf("ESS_SS_SetGroupToSS failed: %ld\n", sts);
sts = ESS_SS_SetUsersToSS(hCtx, hInst);

if (sts)
printf("ESS_SS_SetUsersToSS failed: %ld\n", sts);
sts = ESS_SS_SetGroupsToSS(hCtx);
if (sts)
printf("ESS_SS_SetGroupsToSS failed: %ld\n", sts);
sts = ESS_SS_SetEasLocation(hCtx, hInst);

if (sts)
printf("ESS_SS_SetEasLocation failed: %ld\n", sts);
sts = ESS_SS_ReRegisterApplication(hCtx, hInst);

if (sts)
printf("ESS_SS_ReRegisterApplication failed: %ld\n", sts);
sts = EssLogout(hCtx);
sts = EssTerm(hInst);
}
1254
Limits
C
In This Appendix
Name Limits ............................................................................................ 1255
Drill-through URL Limits ............................................................................... 1257
Name Limits
Subtopics
l Essbase Server (Host) Name Limits
l Application Name Limits
l Database Name Limits
l Filter Name Limits
l Group Name Limits
l Object Name Limits
l Password Limits
l User Name Limits
Essbase Server (Host) Name Limits

l Non-Unicode application limit: 1024 bytes
l Unicode-mode application limit: 1024 characters
Application Name Limits

Application names can contain all special characters allowed in DOS file names. No spaces,
commas, tabs, slashes, backslashes, or periods are allowed. The use of some special characters is
not recommended because they are often used by the operating system (for example, @, $, %,
and &).
1255
Database Name Limits
Database names can contain all special characters allowed in DOS file names. No spaces,
commas, tabs, slashes, backslashes, or periods are allowed. The use of some special characters is
not recommended because they are often used by the operating system (for example, @, $, %,
and &).
Filter Name Limits

Group Name Limits

Object Name Limits

Object names can contain all special characters allowed in DOS file names. No spaces, commas,
backslashes, or periods are allowed.
Password Limits
User Name Limits

User names are not case sensitive and must not contain the backslash character (\).
1256
Drill-through URL Limits
The following limits apply to drill-through URLs:
l The number of drill-through URLs per database is limited to 255.
l The number of drillable regions in a drill-through URL is limited to 256.
l The number of characters per drillable region is limited to 65536.
1257
1258

ESBAR

Uploaded by

Copyright:

Available Formats

ESBAR

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ESBAR

Uploaded by

Copyright:

Available Formats

Oracle® Essbase

Part I. Preliminary Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 1. Introduction to the Oracle Essbase API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 2. Building the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3. Integrating Essbase With Your Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 4. Building a Simple API Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Chapter 5. Unicode Issues in Essbase API Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Part II. C Main API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 6. Using the C Main API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Chapter 7. C Main API Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 8. C Main API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Part III. C Outline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

Chapter 9. Using the C Outline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689

Chapter 10. C Outline API Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695

Chapter 11. C Outline API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723

Chapter 12. C Outline API Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

Part IV. C Grid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007

Chapter 13. Using the C Grid API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009

Chapter 14. C Grid API Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015

Chapter 15. C Grid API Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033

Chapter 16. C Grid API Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119

Part V. Other APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135

Chapter 18. Java API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137

Chapter 19. MDX Provider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139

Chapter 20. Welcome to XMLA Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173

Chapter 21. Working with XMLA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175

Appendix A. API Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219

Appendix C. Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255

Access to Oracle Support

Send feedback on this documentation to: [email protected]

l Introduction to the Oracle Essbase API Reference

Essbase API Overview

What's in This Document

What You Should Know Before You Start

Conventions Used in this Document

Convention Purpose Example

italic Anything you replace with a value in syntax EssOtlCloseOutline (hOutline)

() Parentheses enclose function parameters, show order of execution for EssOtlDeleteMember

; Statement terminator marks end of command EXIT;

Using Function Reference Entries

Table 2 API Function Entries

Function Entry Description

Description Brief description of the function.

Parameters Definitions of the parameters of the function.

Return Value Value returned by the function.

Notes Notes on using the function.

Access Level of security or other access required to use the function.

Example How to use the function.

See Also Related functions.

Table 3 Supported Compilers

AIX (5.3 or later, 32/64 bit) AIX compiler (11.1 or later)

Solaris (10 or later, 32/64 bit) Sun Studio (12.2 or later)

Note: The Essbase API no longer supports Visual Basic.

Sample Windows Make Files

# Common Windows settings

!IF "$(SXR_64BIT)" == "1"

CFLAGS = /nologo /c /w /D"_CRT_SECURE_NO_DEPRECATE" -DBIT64 -DWIN64

!IF "$(PROCESSOR_ARCHITEW6432)" == "IA64"

CFLAGS = /nologo /MLd /c /w -D_USE_32BIT_TIME_T

!IF "$(UTF8)" == "0"