EssLoadBufferTerm

Destroys the temporary data-load memory buffer(s) allocated by EssLoadBufferInit for loading data into an aggregate storage database. Optionally, the data can be committed first.

Applies only to aggregate storage databases.

Syntax

ESS_FUNC_M EssLoadBufferTerm (hCtx, AppName, DbName, ulBufferCnt, *ulBufferIdAry, ulCommitType, 
ulActionType, ulOptions);

Parameter

Data Type

Description

hCtx

ESS_HCTX_T

API context handle.

AppName

ESS_STR_T

Name of the application.

DbName

ESS_STR_T

Name of the database.

ulBufferCnt

ESS_ULONG_T

Number of buffers in the list.

*ulBufferIdAry

ESS_ULONG_T

Array of buffer IDs that will be affected by this operation.

ulCommitType

ESS_ULONG_T

One of the following constants for combining the values stored in the buffer with the values already stored in the database:

ESS_ASO_DATA_LOAD_BUFFER_STORE_DATA: Replace existing cell values in the database with the new values from the load buffer. Cells in the database that do not have corresponding values in the buffer are not updated.
```
#define ESS_ASO_DATA_LOAD_BUFFER_STORE_DATA   0
```
ESS_ASO_DATA_LOAD_BUFFER_ADD_DATA: Add new values to the existing ones.
```
#define ESS_ASO_DATA_LOAD_BUFFER_ADD_DATA   1
```
ESS_ASO_DATA_LOAD_BUFFER_SUBTRACT_DATA: Subtract new values from the existing ones.
```
#define ESS_ASO_DATA_LOAD_BUFFER_SUBTRACT_DATA   2
```
ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_ALL_DATA: Atomically destroy all existing data cells in the database (even cells in the database that do not have corresponding values in the load buffer) and load the contents of the load buffer in one operation.
```
#define ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_ALL_DATA   3
```
When using the override all data option, the ulOptions setting is ignored. Essbase always writes the data currently stored in the buffer to the main slice in the database.
ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_INCREMENTAL_DATA: Atomically destroy all data cells currently stored in any incremental slice and load the contents of the load buffer.
```
#define ESS_ASO_DATA_LOAD_BUFFER_OVERRIDE_INCREMENTAL_DATA   4
```
When using the override incremental data option and the ulOptions setting is main slice, Essbase ignores the ulOptions setting and writes the data currently stored in the buffer to a new slice in the database.

When committing multiple buffers, the values from different buffers are always combined using the add operation, regardless of this ulCommitType setting or how the buffers themselves are configured.

Note:

If the ulActionType setting is abort, the ulCommitType setting is ignored.

ulActionType

ESS_ULONG_T

One of the following constants:

ESS_ASO_DATA_LOAD_BUFFER_COMMIT: Load the data from the load buffer to the database; then destroy the buffer.
```
#define ESS_ASO_DATA_LOAD_BUFFER_COMMIT   1
```
ESS_ASO_DATA_LOAD_BUFFER_ABORT: Destroy the load buffer. All data in the buffer is lost.
```
#define ESS_ASO_DATA_LOAD_BUFFER_ABORT   2
```
When using the abort option, the ulCommitType and ulOptions settings are ignored

ulOptions

ESS_ULONG_T

One of the following constants:

ESS_ASO_DATA_LOAD_INCR_TO_MAIN_SLICE: Write the data currently stored in the buffer to the main slice in the database.
```
#define ESS_ASO_DATA_LOAD_INCR_TO_MAIN_SLICE   0
```
When using the incremental to main slice option, and the ulCommitType setting is override incremental data, Essbase ignores the ulOptions setting and writes the data currently stored in the buffer to a new slice in the database.
ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE: Write the data currently stored in the buffer to a new slice in the database. This operation speeds up the data load.
```
#define ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE   1
```
ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE_LIGHTWEIGHT: Write the data currently stored in the buffer to a new slice in the database, as a lightweight operation. This option is intended only for very small data loads of up to 1,000s of cells that occur concurrently (for example, spreadsheet lock and send operations).
```
#define ESS_ASO_DATA_LOAD_INCR_TO_NEW_SLICE_LIGHTWEIGHT   2
```

Note:

If the ulCommitType setting is override all data, the ulOptions setting is ignored. Essbase always writes the data currently stored in the buffer to the main slice in the database. If the ulActionType setting is abort, the ulOptions setting is ignored

Notes

This function destroys the specified set of load buffers (usually a single load buffer). If the specified action type is "commit," data currently stored in the buffer is applied to the database before the buffers are destroyed.

Return Value

Returns zero if successful; otherwise, returns an error code.

Example

void TestBeginDataloadASO(ESS_HCTX_T hCtx, ESS_STR_T AppName, ESS_STR_T DbName)
{
        ESS_STS_T       sts = ESS_STS_NOERR;
        ESS_BOOL_T      Store;
        ESS_BOOL_T      Unlock; 
        ESS_BOOL_T      abortOnError;
        ESS_STR_T       loadString;
        ESS_OBJDEF_T rulesFile; 
        ESS_PMBRERR_T pMbrErr;
        ESS_ULONG_T ulBufferId;
        ESS_ULONG_T     ulDuplicateAggregationMethod;
        ESS_ULONG_T     ulOptionsFlags;
        ESS_ULONG_T     ulSize;
        ESS_ULONG_T     ulBufferCnt;
        ESS_ULONG_T     ulCommitType ;
        ESS_ULONG_T     ulActionType;
        ESS_ULONG_T     ulOptions;
        ESS_ULONG_T ulBufferIdAry[1];

        /* EssLoadBufferInit */
        ulDuplicateAggregationMethod = ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD;
        ulOptionsFlags = ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES;
        ulSize = 100;
        ulBufferId = 201;
        sts = EssLoadBufferInit(hCtx, AppName, DbName, ulBufferId, ulDuplicateAggregationMethod, 
                ulOptionsFlags, ulSize);
        printf("EssLoadBufferInit sts: %ld\n", sts);

        /* EssBeginDataloadASO, EssSendString, EssEndDataload */
        Store  = ESS_TRUE;
        Unlock = ESS_FALSE;
        abortOnError = ESS_FALSE;
        loadString = "Mar Sale \"Curr Year\" \"Original Price\" \"017589\" \"13668\" Cash \"No Promotion\" \"1 to 13 Years\" \"Under 20,000\" \"Digital Cameras\" 111";                   
        sts = EssBeginDataloadASO (hCtx, Store, Unlock, abortOnError, ESS_NULL, ulBufferId);  
        printf("EssBeginDataloadASO sts: %ld\n",sts);
        sts = EssSendString(hCtx, loadString);
        printf("EssSendString sts: %ld\n",sts);
        sts = EssEndDataload(hCtx, &pMbrErr);
        printf("EssEndDataload sts: %ld\n",sts);

        /* EssLoadBufferTerm */
        ulBufferCnt = 1;
        ulBufferIdAry[0] = ulBufferId;
        ulCommitType = ESS_ASO_DATA_LOAD_BUFFER_STORE_DATA;
        ulActionType = ESS_ASO_DATA_LOAD_BUFFER_COMMIT;
        printf("\Commit data to main slice and destroy buffer:\n");
        ulOptions = ESS_ASO_DATA_LOAD_INCR_TO_MAIN_SLICE;
        sts = EssLoadBufferTerm(hCtx, AppName, DbName, ulBufferCnt, ulBufferIdAry, ulCommitType,
                ulActionType, ulOptions);
        printf("EssLoadBufferTerm sts: %ld\n",sts);

}