C Main API Common Problems and Solutions

The Essbase API gives you unrestricted access to many of the same functions that Essbase Administration Server and MaxL use.

This section is a quick reference to help you in identifying and solving the most common problems.

Problem	Solution
Your program is generating protection faults when allocating or freeing memory.	Here are some things C programmers can check: Check that any memory returned from the API is being freed using the EssFree() function. Check the declared indirection level of any pointers being passed to the API. Use a memory checking program, such as Bounds Checker™ or Purify™, to determine the affected module. Even if the errors are occurring when accessing memory not used by Essbase, there may be some interference between the Essbase memory management scheme and your own. You might consider defining your own custom memory management functions.
Your program generates an Essbase error when calling an API function.	Most of the Essbase error messages are self-explanatory, and it should be fairly obvious where the problem lies. However a couple of common errors to watch out for are (%n indicates a message argument which is replaced by a context-specific string): "NULL argument (%1) passed to ESSAPI function %2". This message indicates that one or more arguments passed to the API function %2 were NULL. The %1 indicates the number of the first null argument (1-based). "Invalid call sequence in ESSAPI function %1". This message indicates that you have made a call to an API function (%1) when another function call was required. For example, if you have executed a report function, such as EssReport(), make sure that you call EssGetString() repeatedly until a NULL string is returned; or if you have executed a calculation function, e.g. EssCalc(), that you repeatedly check the calculation state by calling EssGetProcessState() until the returned value indicates that the calc has completed. "Local operation not allowed in ESSAPI function %s". You have passed a local context handle to a function which does not allow it; use a login context handle instead. "Cannot open message database %s". The message database is not accessible on the machine on which your program is running. Ensure that the message database is where Essbase expects to find it. Essbase first examines the MessagePath field of the initialization structure passed to EssInit(), then the directory and file name specified by the ARBORMSGPATH environment variable, and finally, the $ESSBASEPATH\BIN directory where $ESSBASEPATH is an environment variable. If the message database is not available in any of these directories, Essbase returns an error message at run time. Verify which setting Essbase uses, and then verify that the message database is located where specified. See Integrating Essbase With Your Product for more information.
Your program is consistently receiving an Essbase error return code from an API function, but no message is displayed, or a message saying "No message for message #%1 in message database" is generated.	Certain internal API errors cannot display a message, typically because the user's context information is not available when the message occurs. In these cases, make a note of the error code returned from the function, then refer to the list of error messages in messages.txt to find the corresponding message text. The error constants themselves are contained in esserror.h.
When accessing fields in API-defined structures, they appear to contain the wrong values, or the values seem to be "shifted" by a few bytes.	Check your compiler defaults to ensure you have structures aligned on byte boundaries. If the problem still occurs, make sure you are compiling with the most recent versions of the API header files, and linking with the most recent API DLLs.