Using Function Return Codes

One of the first things you need to know is how to handle the status codes returned by API functions. In general, a zero return code indicates successful completion and a non-zero return code indicates an error. In the latter case, the program should abort the operation in progress and return to the default state, only calling those API functions that are needed to clean up. Every time a program makes a call to the API, it should check the return code and handle it properly.

The API provides a type declaration for status return codes (ESS_STS_T) and a constant declaration (ESS_STS_NOERR). The constant declaration can be used to test the status return codes from API functions in an implementation-independent way.

/* C Example of checking return value from an API function */
ESS_STS_T       sts;
if ((sts = EssSomeFunction (.....)) == ESS_STS_NOERR)
{
        do something else;
}
else
{
        process error;
}
' VB Example of checking return value from an API function */
Dim     sts as ESB_STS_T
if ((sts = EsbSomeFunction (.....)) == ESB_STS_NOERR)
        do something else
else
        process error
endif

The nested programming model is good for releasing resources if an Essbase function fails and returns an error return value. Consider the following example:

allocate resource 1
begin action 1
        allocate resource 2
        begin action 2
                action 2
        end action 2
        free resource 2
end action 1
free resource 1