Cプログラムのカスタム・メッセージ関数の定義

C APIでは、APIによって処理される前に、エラー・メッセージをトラップするのに使用できる、カスタム・メッセージ処理関数を提供できます。カスタム・メッセージ処理関数をコーディングして、特定のエラー状態をトラップしたり、プログラム全体にわたりすべてのユーザー・メッセージを同じように処理および表示できます。カスタム・メッセージ関数を提供しない場合は、メッセージ処理はすべて、APIのデフォルトのメッセージ・ハンドラによって処理されます。

プログラムでカスタム・メッセージ関数を定義するには、最初に関数を作成し、EssInit()呼出しの前に、API初期化構造体のフィールドMessageFuncがカスタム関数を参照するように設定します。

カスタム・メッセージ処理関数のコーディング

カスタム・メッセージ処理関数とその引数には任意の名前を付けられますが、宣言する場合には次の形式を使用する必要があります:

      ESS_FUNC_M      CustomMessage (
ESS_PVOID_T     UserContext,     /* user context pointer */
ESS_LONG_T      MessageNumber,   /* Essbase message number */
ESS_USHORT_ T   Level,           /* message level */
ESS_STR_T       LogString,       /* message log string */
ESS_STR_T       MessageString    /* message string */
);

このコードでは、フィールドは次のように定義されています:

UserContext引数は、API初期化の間に初期化構造体のUserContextフィールドでEssInit()関数へ渡されたポインタのコピーです(CのメインAPIの初期化を参照)。このポインタを使用して、カスタム・メッセージ処理の間に必要な、アプリケーション特有のコンテキスト情報を含めることができますが、通常、このポインタは、プログラムの状態情報を含む構造体を渡すために使用されます。
MessageNumber引数は、特定のエラー状態によって戻されたメッセージをトラップするために使用します(各エラー・メッセージ・コードは、ヘッダー・ファイル(esserror.h)で定義されています)。
Level引数は、メッセージの種類(情報、警告、エラー)を表すメッセージ・レベルに基づいてメッセージをトラップする場合に使用します。

LogString引数は、サーバー・ログ項目情報を文字列として受領します。次のフォームの文字列を渡します:

            [Date & Time] Server/Application/Database/Username/Thread/Message#

例:

            [Fri Feb 04 11:51:18 1994]Elm/Sample/Basic/Admin//1012550

MessageString引数は、文字列としてメッセージ・テキストを含んでいます。次のようなメッセージ・テキストを渡します:
```
            Total Calc Elapsed Time : [46] seconds
         
```
デフォルトのAPIメッセージ・ハンドラでは、ログ文字列とメッセージ文字列が連続して表示されます(メッセージ・ダイアログ内に表示されるか、またはstdoutストリームに書き込まれます)。例:
```
            [Fri Feb 04 11:51:18 1994]Elm/Sample/Basic/Admin//1012550 Total Calc Elapsed Time : [46] seconds
         
```

関数をポイントするようにMessageFuncフィールドを設定

カスタム・メッセージ関数へのポインタは、EssInit()関数に渡される初期化構造体のMessageFuncフィールドに割り当てる必要があります(CのメインAPIの初期化を参照)。

カスタム関数を使用したメッセージ処理のコントロール

カスタム・メッセージ関数が呼び出されてから、Essbaseサーバーがメッセージを戻すか、EssbaseAPIがエラーを戻します。関数が呼び出されると、渡された引数には、そのメッセージのメッセージ番号、メッセージ・レベル、ログ文字列およびエラー文字列が含まれています。各メッセージについて、関数は、これらの引数値を使用して、メッセージを処理するか、無視するか、またはデフォルト処理のためにAPIにそれを戻すかを決めます:

APIに対する戻りコードの意味- 戻り値が0の場合、関数がメッセージを正常に処理し、それ以上のアクションをAPIが実行する必要はないことを示します。戻りコードが0でない場合、メッセージは、さらなる処理および表示のために、デフォルトのAPIメッセージ処理関数に渡されます。プログラムにメッセージを無視させるには、カスタム・メッセージ関数から0を戻します。

注：	メッセージを処理し終えると、APIは、自動的にログおよびメッセージ文字列を解放します。コード内でそれらを解放しようとしないでください。

関数がどの戻りコードを生成しなければならないかの決定- どの戻りコードを生成するか決めるには、カスタム・メッセージ関数をコーディングして、MessageNumber引数またはLevel引数、あるいはその両方を確認します。たとえば、プログラムは、すべての情報メッセージ、またおそらくはすべての警告メッセージを無視する場合があります(これをユーザー定義可能な設定にできます)。それには、ESSAPI.Hに定義された適切な定数(たとえばESS_LEVEL_WARNING)に対してLevel引数をテストし、値が必要な値以下の場合に0を戻します。その他のメッセージの場合、関数はこれらを内部で処理して0の値を戻すか、0以外の値を戻して、これらのメッセージがデフォルトのAPIメッセージ・ハンドラで処理されるようにします。

注：	カスタム・メッセージ関数からEssbase API関数を呼び出さないでください。ただし、メモリー管理API関数EssAlloc()、EssRealloc()およびEssFree()を除きます。

独自のカスタム・メッセージ処理関数を定義しても、同時にAPIを使用する他のアプリケーションには影響しません。EssInit()を呼び出す各アプリケーションでは、カスタム・メッセージ関数を作成するか、またはデフォルトのメッセージ・ハンドラを使用するかを独自に選択できます。