Initializing the Visual Basic API

A program must initialize the API by calling the EsbInit() function before calling any other Essbase API functions. EsbInit() initializes all internal API state variables, and also allows you to tailor the API to your program's requirements.

The only function you can call before EsbInit() is EsbGetAPIVersion().

The calling program must pass the EsbInit() function an initialization structure. This structure is defined in ESB32.BAS as ESB_INIT_T. It contains a series of fields which are used to customize the API and set up certain API defaults. You must declare an instance of this structure and initialize the relevant fields before calling EsbInit().

The EsbInit() function returns an instance handle, which should then be passed as an argument to the API login function.

Declaring the Visual Basic Initialization Structure

In Visual Basic, you can declare the initialization structure in the procedure that uses it. The structure shown below is taken from ESB32.BAS.

Type ESB_INIT_T
   Version     As Long                  ' version of API
   MaxHandles  As Integer               ' maximum number of context handles required
   LocalPath   As String * ESB_PATHLEN  ' local path to use for file operations
   MessageFile As String * ESB_PATHLEN  ' full path name of message database file
   HelpFile    As String * ESB_PATHLEN  ' full path name of help file
   ClientError As Integer               ' allows use of a pseudo client error handler
   ErrorStack  As Integer               ' size of the error message stack
End Type

In this code, the fields are defined as follows:

The Version field indicates the current version of the API.
The MaxHandles field contains the maximum number of simultaneous context handles required by the program. The default is 255.
The LocalPath field contains the default local path name to use for file and object operations on the client. The default is $ESSBASEPATH\CLIENT, where $ESSBASEPATH is defined by the ESSBASEPATH environment variable.
The MessageFile field contains the fully qualified path name of the message database file ESSBASE.MDB. If this is not set explicitly, Essbase first tries to use the fully qualified path in the ARBORMSGPATH environment variable. Otherwise, it uses $ESSBASEPATH\BIN\ESSBASE.MDB, where $ESSBASEPATH is defined by the ESSBASEPATH environment variable. If the ESSBASEPATH variable is not set, an error message is returned at run time.
The HelpFile field contains the fully-qualified name of the application help file. By default, clicking the Help button displays the Essbase System Login help topic shipped with the Oracle Essbase Spreadsheet Add-in User's Guide online help.
If ESSBASEPATH is not defined, the help file name is set to null.
The ClientError field contains the value ESB_FALSE or ESB_TRUE to indicate whether EsbGetMessage() can be used to retrieve messages.
The ErrorStack field contains the size of the message stack used by EsbGetMessage(). The default value is 100.