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

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;
   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;
}
ESS_STS_T FreeKeyboardState (ESS_PVOID_T kbdState)
{
   if (kbdState)
      free(kbdState);
   return 0;
}