After updating any data in the database it is essential to perform a recalculation to ensure that the consolidated totals are correct. To recalculate a database, you can either perform the default calculation, or send a specific calculation script. You can also set a calculation script to be the default calc script. Calc scripts can be sent either as a single string, a series of strings, or a file. Calc script files can reside either on the client machine, or on the Essbase Server.
Sending a Calc Script as a Single String
To send a calc script as a single string, call EssCalc() passing the entire string as an argument (note that in MS-Windows, the string must not be greater than 32 KB long). Set the Calculate flag to TRUE in the call to EssCalc() so that the calc script will be executed. You will then need to check on the progress of the calculation at regular intervals.
Sending a Calc Script as a Series of Strings
To send a calc script as a series of strings, first call EssBeginCalc(), then call EssSendString() repeatedly to send all the strings in the calc script (note that in MS-Windows, each individual string must not be greater than 32 KB long). Finally, terminate the script by calling EssEndCalc(). Set the Calculate flag to TRUE in the call to EssBeginCalc() so that the database will be recalculated. You will then need to check on the progress of the calculation at regular intervals (see "Checking the Progress of Calculations").
Sending a Calc Script as a File
To send a calc script as a file, use the EssCalcFile() function, passing the calc script file name. Set the Calculate flag to TRUE in the call to EssCalcFile() so that the database will be recalculated. You will then need to check on the progress of the calculation at regular intervals (see "Checking the Progress of Calculations").
To recalculate a database using the current default calc script, use the EssDefaultCalc() function. To set the default calc script for a database, use EssSetDefaultCalc(), passing the calc script as a single string. To set the default calc script from a file, use the EssSetDefaultCalcFile() function, passing the calc script file name. Use EssGetProcessState() to determine when the calculation is finished (see "Checking the Progress of Calculations").
Checking the Progress of Calculations
After a database calculation is started, check the progress of the calculation at regular intervals (five seconds is recommended) by calling the EssGetProcessState() function. This function returns a structure indicating the calculation state. Call EssGetProcessState() until it indicates that the calculation is finished or that an error has occurred. You may also cancel a calculation in progress with the EssCancelProcess() function.
Caution! | While a calculation is in progress, do not attempt to call any API functions other than EssGetProcessState() or EssCancelProcess() using the same context handle, until the calc operation has completed successfully or has been canceled. After EssGetProcessState() indicates the calc has finished, your program may continue performing other API operations with that context handle. |