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 EsbCalc() passing the entire string as an argument (note that the string must not be greater than 32 KB long). Set the Calculate flag to TRUE in the call to EsbCalc() so that the calc script will be executed. You 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 EsbBeginCalc(), then call EsbSendString() repeatedly to send all the strings in the calc script (note that each individual string must not be greater than 32 KB long). Finally, terminate the script by calling EsbEndCalc(). Set the Calculate flag to TRUE in the call to EsbBeginCalc() so that the database will be recalculated. You then need to check on the progress of the calculation at regular intervals.
Sending a Calc Script as a File
To send a calc script as a file, use the EsbCalcFile() function, passing the calc script file name. Set the Calculate flag to TRUE in the call to EsbCalcFile() so that the database will be recalculated. You then need to check on the progress of the calculation at regular intervals.
To recalculate a database using the current default calc script, use the EsbDefaultCalc() function. To set the default calc script for a database, use EsbSetDefaultCalc(), passing the calc script as a single string. To set the default calc script from a file, use the EsbSetDefaultCalcFile() function, passing the calc script file name. Use EsbGetProcessState() to determine when the calculation is finished.
Checking the Progress of Calculations
After a database calculation is started, you should check the progress of the calculation at regular intervals (five seconds is recommended) by calling the EsbGetProcessState() function. This function returns a structure indicating the calculation state. You should call EsbGetProcessState() until it indicates that the calculation is complete or that an error has occurred. You may also cancel a calculation in progress at any time by using the EsbCancelProcess() function.
Caution! | While a calculation is in progress, do not attempt to call any API functions other than EsbGetProcessState() or EsbCancelProcess() using the same context handle, until the calc operation has completed successfully or has been canceled. After EsbGetProcessState() indicates the calc has finished, your program may continue performing other API operations with that context handle. |