ESS_INIT_T

API初期化関数EssInit()に渡され、API開発者がAPIの使用をカスタマイズできるフィールドを含んでいます。構造体のフィールドのいずれかが0(またはポインタについてはNULL)に設定されている場合、APIのデフォルトが使用されます。(詳細は、Cプログラムにおけるメモリーの使用を参照してください。)

      
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;

データ型	フィールド	説明
ESS_ULONG_T	Version	アプリケーションのコンパイルに使用するEssbase APIのバージョン。ESS_API_VERSIONに設定します。下位互換性のために使用されます。
ESS_PVOID_T	UserContext	ユーザー定義のメッセージ・コンテキストへのオプションのポインタ(ユーザー定義のメッセージ関数に引数として渡されます)
ESS_USHORT_T	MaxHandles	APIプログラムが必要とする同時コンテキスト・ハンドルの最大数(1-255)。デフォルトは255です。この数を減らすと、API内でプログラムのために使用されるクライアント・メモリーの量が減る可能性があります。
ESS_SIZE_T	MaxBuffer	クライアント・プログラムで割り当てることができるバッファの最大サイズ(通常は64KB)。デフォルトは64KBです。
ESS_STR_T	LocalPath	クライアントでファイルやオブジェクトを操作するためのデフォルトのローカル・パス名。これが設定されていない場合、Essbaseは、デフォルトではESSBASEPATH環境変数を使用し、渡されるディレクトリ名には\CLIENTを追加します。
ESS_STR_T	MessageFile	メッセージ・データベース・ファイル、ESSBASE.MDBの修飾パス名。これが設定されていない場合、Essbaseは最初に、ARBORMSGPATH環境変数の完全修飾パスを使用しようとします。それ以外の場合は、(ESSBASEPATH)\BIN\SSBASE.MDBを使用します。ESSBASEPATHが定義されていない場合、実行時にエラーが戻されます。
ESS_PFUNC_T	AllocFunc	ユーザー定義のメモリー割当て関数へのポインタ。すべてのプラットフォーム: メモリー割当て関数はmalloc()関数を使用します。
ESS_PFUNC_T	ReallocFunc	ユーザー定義のメモリー再割当て関数へのポインタ。すべてのプラットフォーム: メモリー割当て関数はrealloc()関数を使用します。
ESS_PFUNC_T	FreeFunc	ユーザー定義のメモリー解放関数へのポインタ。すべてのプラットフォーム: メモリー割当て関数はfree()関数を使用します。
ESS_PFUNC_T	MessageFunc	ユーザー定義のメッセージ・コールバック関数へのポインタ。ユーザー定義のコールバック関数に送信されたメッセージは、EssInitでEssbaseに渡されます。リリース6.2より以前は、メッセージがNLS文字(アクセント付き文字など外国語文字)を含んでいた場合、Essbaseは、OEM (DOS)フォーマットでそれらを提供していました。リリース6.2以降は、これらのメッセージは、文字の誤解を避けるため、完全に文字(Windows)フォーマットになっています。これは、Essbaseのローカライズ・バージョンのみに影響します。
ESS_STR_T	HelpFile	ユーザー定義のアプリケーション・ヘルプ・ファイルの完全修飾パス名で、「自動ログイン」ダイアログ・ボックスのヘルプに使用されます。ログイン・へルプ・コンテキストはヘルプ・ファイルで定義する必要があります。 Essbaseと使用中の製品との統合。を参照してください。デフォルトでは、「ヘルプ」ボタンをクリックすると、『Oracle Essbase Spreadsheet Add-inユーザー・ガイド』オンライン・ヘルプに含まれているEssbaseシステムのログインに関するヘルプ・トピックが表示されます。 ESSBASEPATHが定義されていない場合、ヘルプ・ファイル名はNULLに設定されます。
ESS_ULONG_T	Ess_System	内部で使用するために予約されています。NULLに設定します
ESS_USHORT_T	usApiType	必須。プログラムがUnicodeモードと非Unicodeモードのどちらであるかを定義します。有効な値は、Unicodeモードの定数(C)を参照してください。
typedef ESS_BOOL_T (*ESS_PCATCHFUNC_T)(ESS_HCTX_T);	CatchFunc	クライアントによって実装されると、Essbaseはクエリー中にこの関数を断続的(数秒ごと)に呼び出します。ルーチンがTRUEを戻すと、API呼出しが取り消されます。
typedef ESS_STS_T (*ESS_PCATCH_INIT_FUNC_T)(ESS_ HCTX _T);	CatchInitFunc	この関数は、CatchFunc呼出しにどのような状態が必要であっても、リソースを初期化します。たとえば、ユーザーが[Esc]キーを押すかどうか、そして、CatchFuncがルーチンを呼び出してキーボードからのデータを取得するかどうかに基づいてクエリーを終了したい場合は、CatchFunc呼出しのたびに初期化されないようにメモリーを事前初期化する必要がある場合があります。 Essbaseは、クエリー中に次のプロセスを実行します: 非NULLの場合に、CatchInitFuncを呼び出します。 CatchFuncを断続的に呼び出しながら、クエリーを実行します。非NULLの場合に、CatchTermFuncを呼び出します。
typedef ESS_STS_T (*ESS_PCATCH_TERM_FUNC_T)(ESS_ HCTX _T);	CatchTermFunc	この関数は、CatchInitFuncによって初期化されたリソースを終了します。
typedef ESS_STS_T (*ESS_PCOOKIE_CREATE_FUNC_T)(ESS_HCTX_T);	CookieCreateFunc	Essbaseは、SetActive時にこの関数を呼び出します。CatchFunc、CatchInitFunc、およびCatchTermFunc呼出しにユーザー情報が必要な場合に、この関数を使用します。たとえば、一定のユーザー・アクティビティに基づいてクエリーを終了したい場合は、CatchFunc呼出しで使用されるCookieを作成する必要があります。EssGetCookieを呼び出して、Cookieを取得します。
typedef ESS_STS_T (*ESS_PCOOKIE_DELETE_FUNC_T)(ESS_HCTX_T);	CookieDeleteFunc	この関数は、CookieCreateFuncによって作成されたCookieを削除します。Essbaseは、ClearActive時にこの関数を呼び出します。

Essbase APIを使用したクエリー取消し

Essbase APIを使用して開発されたプログラムは、オプションで初期化時にカスタム・クエリー取消し関数を登録できます。ESS_INIT_Tには、クエリー取消しのためのカスタム・コールバック関数を作成できるフィールドが5つあります。そのフィールドは、CatchFunc、CatchInitFunc、CatchTermFunc、CookieCreateFunc、CookieDeleteFuncです。これらはデフォルトでNULLに設定されます。

クエリー取消しの使用例

次のコードは、[Esc]キーが押されたときにクエリー取消しを有効にします。KbdHitExは、キーボードから入力された次のキーを取得して、キーの値を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;
}

ただし、KdbHitExルーチンでは、最初に初期化ルーチンInitializeMyKeyboardが呼び出され、後で終了ルーチンTerminateMyKeyboardが呼び出される必要があると仮定します。この場合には、CatchInitFuncと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 ();
}

今度は、InitializeMyKeyboardルーチンとTerminateMyKeyboardルーチンがステータス情報を保持する必要があると仮定します。Cookieを使用して、ステータスを保持できます。CookieCreateFuncによって作成されたCookieには、EssGetCookieによってCatchFunc、CatchInitFunc、およびCatchTermFuncでアクセスできます。

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