Using Message Handling in Visual Basic Programs

To implement message handling in Visual Basic Programs, first follow these steps as you code your program:

Set the ClientError field of the ESB_INIT_T structure to ESB_TRUE, and define a value for the ErrorStack field of ESB_INIT_T when it calls the initialization function EsbInit().

To define a custom message handler,

Define it using the following function signature (the function name can be changed):

        Public Function EsbErrorHandler 
        (ByVal MsgNum As Long, ByVal Level As Long, 
        ByVal uLog As String, ByVal uMsg As String) As Long

Initialize the vbCallbackFuncAddress field of the ESB_INIT_T structure to the address of the custom message handler function. Example:

Sub ESB_Init()
   Dim Init As ESB_INIT_T
   Dim lx As Long
  
   ESB_FALSE = 0
   ESB_TRUE = 1

   Init.Version = ESB_API_VERSION
   Init.MaxHandles = 10
   Init.LocalPath = "C:\Hyperion\products\Essbase"
   Init.MessageFile = ""
   'This must be set to True
   Init.ClientError = ESB_TRUE
   Init.ErrorStack = 100
   'This is where the address of the custom function is set for Init.vbCallbackFuncAddress
   Init.vbCallbackFuncAddress = GetProcAddress(AddressOf EsbErrorHandler)
  
   sts = EsbInit(Init, hInst)
   Debug.Print "EsbInit: sts = " & sts

End Sub

Public Function GetProcAddress(ByVal lngAddressOf As Long) As Long
  GetProcAddress = lngAddressOf
End Function

Public Function EsbErrorHandler(ByVal MsgNum As Long, ByVal Level As 
Long, ByVal uLog As String, ByVal uMsg As String) As Long
  ' [ YOUR CODE GOES HERE ]
  MsgBox " Info " & MsgNum & ": Level: " & Level & ": " & uLog & ": " & uMsg
End Function

To use the Essbase provided message handling, call the function EsbGetMessage() to retrieve any information returned after a call to the Essbase API. After the information is retrieved, your program can display or handle the information as necessary.

Setting the ClientError and ErrorStack Fields

The following code fragment shows the ClientError and ErrorStack fields set.

Dim Init As ESB_INIT_T

.

.

.

Init.ClientError = ESB_TRUE

Init.ErrorStack = 100

Calling EsbGetMessage()

All information, warning, and error messages accumulate in a message stack when an API function executes. When ClientError is set to ESB_TRUE, EsbGetMessage() can be used to retrieve the top message from the stack. When successful, EsbGetMessage() returns a pointer to a message level, a pointer to a message number, and a message string. It also decrements the internal message stack pointer. To ensure that no data is lost, you should call EsbGetMessage() until the function returns an empty string in the message parameter, and zeros in the number parameter. See EsbGetMessage for more details.

Visual Basic programs should call EsbGetMessage() to retrieve any information that may be generated by a call to the API. It is important to do this when the return code generated by an API call is not zero, to obtain any error or status information returned. Additionally, you should call EsbGetMessage() when the return code is zero when there is likely to be additional information returned. For example, successful calls to EsbLogin() or EsbAutoLogin() return useful information about the last login.

Note:

If you initialize a custom error-handling function, EsbGetMessage cannot be used to retrieve.