Initializing the C Main API

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

The calling program must pass the EssInit() function an initialization structure. This structure is defined in ESSAPI.H as type ESS_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 EssInit().

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

Declaring the Initialization Structure

The initialization structure passed to EssInit() can usually be declared as a local (i.e. stack) variable in the calling function, as it is usually not required once it has been passed to EssInit(). Alternatively, you can allocate the structure before calling EssInit(), then free it after returning.

If the initialization structure points to custom memory management functions in the initialization call, make sure your program frees the structure using the correct memory allocation scheme.

If any of the fields of the initialization structure are set to zero values or NULL pointers, the API will use the internal default values for those fields.

It is a good idea to clear out all structures (set to 0) before setting fields and calling the API function.