Handling Messages

The API includes a mechanism for intercepting error messages and other messages generated at the server and for displaying the appropriate messages automatically on the client program's screen. This mechanism, although generally useful, can be turned off if desired. The API allows your program to prevent those messages from appearing and to trap them for processing within your program. You can choose which messages to display and then display the messages in a way that is consistent with your program's internal message and error handling. This mechanism provides seamless integration of Essbase with your program.

The default message processing in Essbase is platform-dependent, but typically generates a dialog box with the log information (application and database name, username, timestamp, and so on) and the message text.

Every Essbase message has a unique identification number, a message level number, and an associated text string (that is not necessarily unique). By default, Essbase displays error messages only for serious errors, not for warnings and not for information messages.

Message Handling in C

In the C API, you can define a Custom Message Handling function and pass a pointer to that function during the initialization call, EssInit(). This custom function is then called when the API receives a message from the server. The custom function can examine the function return code either to process the message internally or to pass the message back to the API for default message processing. For more details see, C Main API Message Handling.

An example of a message handling function for Windows and C is given below:

/* 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);
}

Message Handling in Visual Basic

In the Visual Basic API the message handling mechanism is slightly different. Again, you pass a parameter to the API during the initialization call, EsbInit(). The call initiates custom message processing (suppressing the Essbase default processing) and sets up a message stack. Then, when an error occurs in your program (indicated by a non-zero return value from an API function call), you should call an internal error handling function. That function should in turn call EsbGetMessage() to retrieve any messages from the stack and then display the messages in whichever way you choose. For more details, see Visual Basic API Message Handling.

An example of a message handling function in Visual Basic is given below:

' 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