Use 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 functionality, drill-down, keep-only, and pivots. You can also launch report specs and get the resulting data in grid form. You can test the results of your Grid API functions by performing the same actions in Microsoft Excel or Lotus 1-2-3.
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 the Grid API functions with the two-dimensional data for each call, and to render any returned data.
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 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.
#pragma pack(push, id, 1) #include "essgapi.h" #pragma pack(pop, id)
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 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 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.
When you use Essbase Grid API functions, you must call the initialization function, EssGInit. This function performs the following tasks:
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.
When you use EssGInit to initialize the API, you need to pass in the version number of the API 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 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.
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:
After EssGEndOperation, EssGCancelOperation, or another EssGBeginXxxx operation is called, all information from the previous operation is lost.
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.
Therefore, you will probably want to call the main API when using the Grid API functions. To call the main API you need two pieces of information:
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, 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; for example, EssLogin, EssAutoLogin, EssSetActive, or 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.
Assume a zero-based column and row numbering scheme in the range structure that you pass into functions expecting 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].