Grid API Reference

Grid API Declarations
Grid API Functions Reference
Example
Error Codes

Grid API Declarations


Grid API Constants

The following constants are defined in the Essbase Grid API.

Returned on successful API call

ConstantDefinition
ESSG_STS_NOERR0

Defines the version of the EGAPI API. Changes each time the API is modified.

ConstantDefinition
ESSG_VERSION0x00040000

Define the maximum number of rows and columns supported

ConstantDefinition
WIN32
ESSG_MAXROWS0xFFFFFFFF / sizeof(ESSG_PDATA_T)
ESSG_MAXCOLUMNS0xFFFFFFFF / sizeof(ESSG_DATA_T)
OTHER
ESSG_MAXROWS0xFFFF / sizeof (ESSG_PDATA_T)
ESSG_MAXCOLUMNS0xFFFF / sizeof(ESSG_DATA_T)
Used by the pAttributes member of the ESSG_DATA_T structure

ConstantDefinition
ESSG_CA_READONLY0X00000001
ESSG_CA_READWRITE0X00000002
ESSG_CA_LINKEDOBJ0X00000004
ESSG_CA_LINKPARTITION0X00000008
ESSG_CA_LINKCELLNOTE0X00000010
ESSG_CA_LINKWINAPP0X00000020
ESSG_CA_LINKURL0X00000040

Used by the usType member of the ESSG_DATA_T structure

ConstantDefinition
ESSG_DT_STRING1
ESSG_DT_LONG2
ESSG_DT_DOUBLE3
ESSG_DT_BLANK4
ESSG_DT_RESERVED5
ESSG_DT_ERROR6
ESSG_DT_MISSING7
ESSG_DT_ZERO8
ESSG_DT_NOACCESS9
ESSG_DT_MEMBER10

Used for the pAttributes for members in the ESSG_DATA_T structure

ConstantDefinition
ESSG_MA_DIMTOP0x00000001
ESSG_MA_ZOOMINABLE0x00000002
ESSG_MA_NEVERSHARE0x00000004
ESSG_MA_LABELONLY0x00000008
ESSG_MA_STOREDATA0x00000010
ESSG_MA_EXPSHARE0x00000020
ESSG_MA_IMPSHARE0x00000040
ESSG_MA_DYNCALC0x00000080
ESSG_MA_DIMNUMBITS 0xF8000000
(the last 5 bits contain the dim number)

Used by the ulOptions parameter of EssGBeginRetrieve

ConstantDefinition
ESSG_RET_RETRIEVE0
ESSG_RET_RETRIEVELOCK1
ESSG_RET_LOCKONLY2

Used by the ulOptions parameter of EssGBeginUpdate

ConstantDefinition
ESSG_RET_REQUIRELOCK0
ESSG_RET_LOCKIFNEEDED1

This bitmask contant is used by the ulOptions parameter of EssGBeginConditionalRetrieve, EssGBeginConditionalZoomIn, EssGBeginReport, and EssGBeginReportFile

ConstantDefinition
ESSG_NOATTRIBUTES0x00001000

These bitmask constants are used by the ulOptions parameter of EssGBeginZoomIn and EssGBeginConditionalZoomIn

ConstantDefinition
ESSG_ZOOM_DOWN0x00000080
ESSG_ZOOM_ACROSS0x00000100

Describe the connect options

ConstantDefinition
ESSG_CONNECT_DEFAULT0
ESSG_CONNECT_NODIALOG1

Describe the various zoom levels

ConstantDefinition
ESSG_OPTIONS0
ESSG_NEXTLEVEL1
ESSG_ALLLEVELS2
ESSG_BOTTOMLEVEL3
ESSG_SIBLEVEL4
ESSG_SAMELEVEL5
ESSG_SAMEGENERATION6
ESSG_CALCLEVEL7
ESSG_PARENTLEVEL8
ESSG_TOPLEVEL9

Used for setting and retrieving grid options

ConstantDefinition
ESSG_OP_DRILLLEVEL1
ESSG_OP_INCSEL2
ESSG_OP_SELONLY3
ESSG_OP_SELGROUP4
ESSG_OP_INDENT5
ESSG_OP_SUPMISSING6
ESSG_OP_SUPZEROS7
ESSG_OP_SUPUNDER8
ESSG_OP_UPDATEMODE9
ESSG_OP_ALIASNAMES10
ESSG_OP_ALIASTABLE11
ESSG_OP_USERGRIDDATA12
ESSG_OP_RETAINTHREAD20
ESSG_OP_EMPTYGRIDERROR21
ESSG_OP_DRILLONLEAF22
ESSG_OP_DATALESS23
ESSG_OP_SPANHYBRIDANALYSIS24

Describe the various indent styles

ConstantDefinition
ESSG_INDENTNONE1
ESSG_INDENTSUBITEMS2
ESSG_INDENTTOTALS3

Used by get results calls to determine the process state

ConstantDefinition
ESSG_STATE_DONE1
ESSG_STATE_INPROGRESS2

Buffer length constants (including terminating null)

ConstantDefinition
ESSG_USERNAMELEN31
ESSG_PASSWORDLEN101
ESSG_SERVERLEN31
ESSG_APPLICATIONLEN9
ESSG_DATABASELEN9

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 the Integration Server 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 the Integration Server 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

ConstantDefinition
ESSG_PARTITIONTYPE1
ESSG_CELLNOTETYPE2
ESSG_WINAPPTYPE3
ESSG_URLTYPE4

Data Types

Data Type Essbase Type
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
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

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.

ESSG_CONNECTINFO_T

This structure 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;
Data Type Field Description
ESSG_SERVER_T Server The name of the server.
ESSG_APPLICATION_T Application The name of the application.
ESSG_DATABASE_T Database The name of the Essbase database.
ESSG_USERNAME_T Username The user's name.
ESSG_PASSWORD_T Password The user's password.

ESSG_DATA_T

This structure describes the format of the data to be sent and received by the EGAPI. Note that calls returning this structure will return member names in the Member structure. The caller can pass 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 ESS_DATA_T data structure defines each cell sent or returned via the grid API. If this structure is being returned to the caller, the pszStr contains string data and the dblData contains numeric data. The usType parameter should be used to determine whether it's a member, a number, or the text. If the structure being passed into the API, the same is true. The pszStr field should contain a member name or text and the dblData field should contain numeric data. The usType field should be set appropriately. You might not know on input if the cell is a member name or text. That's okay, just set it to text (ESSG_DT_STRING), and the server will figure out that it's a member.

typedef struct ESSG_DATA_T
{
    ESSG_PVOID_T    pAttributes;
        union
        {
             ESSG_LONG_T    lData;
             ESSG_WORD_T    wData;
             ESSG_DOUBLE_T  dblData;
             ESSG_STR_T     pszStr;
        } Value;
    ESSG_USHORT_T usType;
} ESSG_DATA_T, *ESSG_PDATA_T, **ESSG_PPDATA_T;
Data Type Field Description
ESSG_PVOID_T pAttributes One of the long integer constants listed below indicating the cell type or member type. (OUT)
ESSG_LONG_T lData A long value containing the data. (IN)
ESSG_WORD_T wData A word value containing the data. (IN)
ESSG_DOUBLE_T dblData A floating point value containing the data. (IN/OUT)
ESSG_STR_T pszStr A null terminated Pascal string containing a member name or text. (IN/OUT) A Pascal string is defined as a string whose first byte contains the length of the string. Thus, all strings are limited to a length of 255 bytes.
ESSG_USHORT_T usType One of the tag constants listed below indicating the data type. (IN/OUT)

Constants for ESSG_DATA_T

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

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_DRILLDATA_T

This structure 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;
Data Type Field Description
ESSG_HLRO_T hLRO A unique handle to a linked object.
ESSG_USHORT_T usLinkObjType The object type.
ESSG_LINKOBJDESC Description The object description.
ESSG_PSTR_T pMbrCombos An array of member names.
ESSG_ULONG_T ulNumMbrCombos The number of member names in pMbrCombos.

ESSG_DTDATA_T

This structure defines a report data cell.

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;

Data Type Field Description
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

This structure defines header information for a specific column.

typedef struct ESSG_DTHEADER_T
{
   ESSG_ULONG_T         colIndex;
   ESSG_CHAR_T          viewName[ESSG_DESCLEN + 1];
   ESSG_CHAR_T          data[ESSG_DESCLEN + 1];
   ESSGDTREPORTDATATYPE dataType;
} ESSG_DTHEADER_T, *ESSG_PDTHEADER_T, **ESSG_PPDTHEADER_T;

Data Type Field Description
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 the dataType field of the ESSG_DTHEADER_T structure:

  ESSGDTINT
  ESSGDTFLOAT
  ESSGDTSTRING

ESSG_DTINFO_T

This structure 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;

Data Type Field Description
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

This structure defines a report definition.

typedef struct ESSG_DTREPORT_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_DTREPORT_T, *ESSG_PDTREPORT_T, **ESSG_PPDTREPORT_T;

Data Type Field Description
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

This structure 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_INIT_T, *ESSG_PINIT_T;
Data Type Field Description
ESSG_ULONG_T ulVersion This should be set to ESSG_VERSION.
ESSG_ULONG_T ulMaxRows The maximum number of rows for the grid. The limit is 65535 rows.
ESSG_ULONG_T ulMaxColumns The maximum number of columns for the grid. The limit is 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_LRODESC_T

This structure contains information describing a specific object linked to a data cell in an Essbase database. The fields are described as follows:

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;
Data Type Field Description
ESSG_ULONG_T usLinkObjType The object type.
ESSG_USERNAME_T userName The name of the last user to modify the object.
ESSG_TIME_T LastUpdate The last date the object was modified. ESSG_TIME_T is defined as an unsigned long.
ESSG_LROINFO_T lroInfo The 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

This structure 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;
Data Type Field Description
ESSG_CHAR_T objName[ESSG_ONAMELEN] Source file name of object linked to a data cell. ESSG_ONAMELEN specifies the maximum length of an object name; the default value is 511.
ESSG_CHAR_T Desc[ESS_DESCLEN] Description of an object linked to a data cell. ESS_DESCLEN specifies the maximum length of the description; the default value is 79.

ESSG_RANGE_T

This structure describes the extent of the data being sent or received.

typedef struct
{
    ESSG_ULONG_T ulRowStart;
    ESSG_ULONG_T ulColumnStart;
    ESSG_ULONG_T ulNumRows;
    ESSG_ULONG_T ulNumColumns;
} ESSG_RANGE_T, *ESSG_PRANGE_T;
Data Type Field Description
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).