# Grid API Reference

Grid API Declarations
Grid API Functions Reference
Example
Error Codes

## Grid API Concepts

- General Information
- Overview of Architecture
- Supported Platforms and Compilers
- Files to Include in the Program
- Files to Link with the Program
- Files to Send with the Program
- API Libraries
- Naming Conventions

## Using the Grid API

- Initialization and Setup
- Memory Management
- Versioning
- Using the Grid API Functions
- Using the Main API Functions
- Coordinate Systems

## General Information on the Grid API

Use the Essbase Application Programming Interface (API) to create custom interfaces to the Essbase Data Server.

The Essbase 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 Essbase Spreadsheet Add-In. 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. Grid API functions can be tested by performing the same actions in Microsoft Excel or other automated grid tools.

## Overview of Architecture

The Essbase Grid API functions use the Common Spreadsheet Layer (CSL) to communicate with the Essbase Data Server.

The Grid API functions provide functionality similar to the Essbase extended spreadsheet macros.

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.

### Information About Grid API

The Essbase Grid API (EGAPI) offers significant advantages for developers currently building reporting applications using the Essbase API and report script commands. Some of the benefits are as follows:

- 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.
- 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.
- 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.
- Most Hyperion add-in spreedsheet 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.
- 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.

## Supported Platforms and Compilers

The Essbase Grid API is not supported on all platforms. For a list of platforms on which the Grid API is supported, see APIs and Platforms. For a list of specific operating system releases on which the Essbase API is supported, see Supported Platforms. For a list of specific compiler releases which are supported by the Essbase API, see Supported Compilers.

Function names and parameter order are the same for all platforms. However, you must link different files for each platform. See Files to Link with the Program.

### Compiler Options

- 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 Files to Link with the Program.
- 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)

## Files to Include in the Program

In order to use the Essbase API functions in your program, you must include the file that contains Essbase API definitions.

To use the Essbase 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 Essbase 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`.

## Initialization and Setup

When you use Essbase Grid API functions, you must call the initialization function, EssGInit. This function performs the following tasks:

- Passes information about your environment to the Essbase Grid API functions.
- Provides you with an instance handle that you use for future communication with the Essbase Grid API functions.

Notes:

- 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 Main API Functions.
- You cannot use Main Essbase API instance handles and login contexts in Grid API calls. See Using the Main API Functions.

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

## 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 Essbase Grid API. You do not need to do any initialization before you make this call.

## Using the 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 Main API Functions

The Essbase 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:

- Essbase instance handle
- 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.

## 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]`.