EssLoadBufferInit

Creates a temporary data load buffer, which provides temporary storage for tuples during a data load into an aggregate storage database. Applies only to aggregate storage databases.

Syntax

ESS_FUNC_M EssLoadBufferInit (hCtx, AppName, DbName, ulBufferId, ulDuplicateAggregationMethod, 
ulOptionFlags, ulSize);

Parameter

Data Type

Description

hCtx

ESS_HCTX_T

API context handle.

AppName

ESS_STR_T

Name of the application for which to create the load buffer.

DbName

ESS_STR_T

Name of the database for which to create the load buffer.

ulBufferId

ESS_ULONG_T

ID number for the data load buffer (a number between 1 and 999,999, inclusive). If the ID is already in use, the operation fails.

ulDuplicateAggregationMethod

ESS_ULONG_T

One of the following constants for combining multiple values for the same cell within the buffer:

ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD: Add values when the buffer contains multiple values for the same cell.
```
#define ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ADD   0
```
ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ASSUME_EQUAL: Verify that multiple values for the same cells are identical; if they are, ignore the duplicate values. If the values for the same cell differ, stop the data load with an error message.
```
#define ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_ASSUME_EQUAL   1
```

ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_USE_LAST: Combines duplicate cells by using the value of the cell that was loaded last into the load buffer. This option is intended for relatively small data loads of up to 10,000s of cells.

#define ESS_ASO_DATA_LOAD_BUFFER_DUPLICATES_USE_LAST   2

When using data load buffers with the use_last option, data loads are significantly slower, even if there are not any duplicate values.

Caution!

The use_last method has significant performance impact, and is not intended for large data loads. If your data load is larger than one million cells, consider separating the numeric data into a separate data load process (from any typed measure data). The separate data load can use the add method instead.

ulOptionFlags

ESS_ULONG_T

One or more of the following load buffer options:

ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES: Ignores #MISSING values in the incoming data stream.
```
#define ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES   0x00000001
```
ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES: Ignores zeros in the incoming data stream.
```
#define ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES   0x00000002
```
ESS_ASO_DATA_LOAD_BUFFER_WAIT_FOR_RESOURCES: Tells Essbase to wait up to the amount of time specified by the ASOLOADBUFFERWAIT configuration setting in essbase.cfg for resources to become available in order to process load buffer operations.
```
#define ESS_ASO_DATA_LOAD_BUFFER_WAIT_FOR_RESOURCES   0x00000004
```

Use bitwise OR (|) to specify multiple ulOptions; for example:

ESS_ASO_DATA_LOAD_BUFFER_IGNORE_MISSING_VALUES | ESS_ASO_DATA_LOAD_BUFFER_IGNORE_ZERO_VALUES

ulSize

ESS_ULONG_T

Percentage of total load buffer resources this load buffer may use. Possible values: 0 to 100.

For a value of 0, Essbase uses a self-determined, default load buffer size.

If the total size of all load buffers exceeds 100, the operation fails.

Notes

Multiple buffers can exist on a single aggregate storage database; however, only one data load may use a given load buffer at a time.

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);

}