APIには、サーバーで生成されたエラー・メッセージおよび他のメッセージを遮断するための、また、クライアント・プログラムの画面上に適切なメッセージを自動的に表示するためのメカニズムが含まれます。通常、このメカニズムは、役に立ちますが、必要に応じてオフにできます。APIでは、プログラムが、それらのメッセージが表示されるのを防ぎ、プログラム内で処理するためにそれらをトラップできます。どのメッセージを表示するかを選択し、プログラムの内部メッセージおよびエラー処理と一貫した方法で、メッセージを表示できます。このメカニズムは、Essbaseのプログラムとのシームレスな統合を提供します。
Essbaseにおけるデフォルトのメッセージ・プロセスはプラットフォームに依存しますが、通常はログ情報(アプリケーション名およびデータベース名、ユーザー名、タイムスタンプなど)付きのダイアログ・ボックスと、そのメッセージ・テキストが表示されます。
各Essbaseメッセージには、一意の識別番号、メッセージ・レベル番号および関連するテキスト文字列(必ずしも一意でない)が備わっています。デフォルトでは、Essbaseは、重大なエラーのエラー・メッセージのみを表示し、警告や情報のエラー・メッセージは表示しません。
Cにおけるメッセージ処理
CのAPIでは、カスタム・メッセージ処理関数を定義し、初期化呼出し、EssInit()の間に、ポインタをその関数へ渡せます。APIがサーバーからメッセージを受け取ると、このカスタム関数が呼び出されます。カスタム関数は、関数の戻りコードを調べて、メッセージを内部で処理するか、またはデフォルトのメッセージ処理のためにAPIにメッセージを戻します。詳細は、CのメインAPIメッセージ処理に関する説明を参照してください。
WindowsおよびCのためのメッセージ処理関数の例を次に示します:
/* C Example of a message handling function */
ESS_FUNC_M ErrorHandler (ESS_PVOID_T myCtx,
ESS_LONG_T MsgNum,
ESS_USHORT_T Level,
ESS_STR_T LogStr,
ESS_STR_T MsgStr)
{
ESS_STS_T sts = 0;
ESS_STR_T ErrorStr;
ESS_USHORT_T len;
HANDLE hMem;
/* Only display messages of level ERROR or above */
if (Level >= ESS_LEVEL_ERROR)
{
/* Calculate combined length of Log and Message strings */
len = 3; /* allow for end of line characters + null */
if (LogStr != NULL)
len += strlen (LogStr);
if (MsgStr != NULL)
len += strlen (MsgStr);
/* Concatenate the strings */
if ((hMem = GlobalAlloc (GPTR, len)) != 0)
{
ErrorStr = GlobalLock (hMem);
sprintf (ErrorStr, "%s\n%s", LogStr, MsgStr);
/* Display message in a Windows message box */
MessageBox ((HWND)NULL, ErrorStr, "Essbase Error",
MB_OK);
GlobalUnlock (hMem);
GlobalFree (hMem);
}
}
return (sts);
}
Visual Basicにおけるメッセージ処理
Visual BasicのAPIでは、メッセージ処理メカニズムは多少異なります。ここでも、初期化呼出し、EsbInit()の間に、パラメータをAPIへ渡します。呼出しは、(Essbaseデフォルト処理を抑制して)カスタム・メッセージ処理を始め、メッセージ・スタックを設定します。その後、プログラムでエラーが発生した場合(API関数呼出しからの0以外の戻り値によって示される)、内部エラー処理関数を呼び出す必要があります。その関数は次に、EsbGetMessage()を呼び出して、スタックからメッセージを取得し、ユーザーが選択した方法でメッセージを表示します。詳細は、Visual BasicのAPIメッセージの処理についての説明を参照してください。
Visual Basicにおけるメッセージ処理関数の例を次に示します:
' VB Example of message handler
Dim hInst As Long
Dim hCtx As Long
Dim sts As Long
Dim Server As String * ESB_SVRNAMELEN
Dim User As String * ESB_USERNAMELEN
Dim Password As String * ESB_PASSWORDLEN
Dim Appname As String * ESB_APPNAMELEN
Dim Dbname As String * ESB_DBNAMELEN
Dim Access As Integer
Dim Init As ESB_INIT_T
' GetMessage Variables
Dim Count As Integer
Dim TestApp As String
Dim TestDb As String
Dim TestFtrName As String
Dim ErrMsg As String * 256
Dim ErrNum As Long
Dim ErrLev As Integer
ESB_TRUE = Chr$(1)
ESB_FALSE = Chr$(0)
Init.Maxhandles = 10
Init.ClientError = ESB_TRUE
Init.ErrorStack = 100
sts = EsbInit(Init, hInst)
sts = EsbAutoLogin(hInst, Server, User, Password, Appname, Dbname,
ESB_AUTO_NOSELECT, Access, hCtx)
If sts <> 0 Then
sts = EsbGetMessage(hInst, ErrLev, ErrNum, ErrMsg, 256)
MsgBox ErrMsg & Chr(13) & "Program Ending"
End If
TestApp = "Sample"
TestDb = "Basic"
TestFtrName = "Anything"
'This function call should return an error and then be picked up by EsbGetMessage
sts = EsbGetFilterList(hCtx, TestApp, TestDb, TestFtrName, Count)
If sts <> 0 Then
sts = EsbGetMessage(hInst, ErrLev, ErrNum, ErrMsg, 256)
MsgBox "Program Ending" & Chr(13) & Chr(13) & ErrMsg
End If
sts = EsbLogout(hCtx)
sts = EsbTerm(hInst)
End