EssAsyncBuildDim

Issues an asynchronous dimension build request.

If you use asynchronous data loads and dimension builds, you can query for the following information during the process:

The state of dimension build/data load process: whether it is in progress, in the final stages, or completed
The stage of the dimension build/data load process: whether opening the data source, reading the outline, building dimensions, verifying an outline, or writing an outline
The number of data records processed and rejected so far
The name and location of the error file
The data records processed and rejected so far

Syntax

ESS_FUNC_M EssAsyncBuildDim(hCtx, RulesObj, DataObj, MbrUser, bOverwrite, usBuildOption, szTmpOtlFile)

Parameter	Data Type	Description
hCtx	ESS_HCTX_T	Essbase API context handle.
RulesObj	ESS_POBJDEF_T	Pointer to rules file object definition structure.
DataObj	ESS_POBJDEF_T	Pointer to data file object definition structure.
MbrUser	ESS_PMBRUSER_T	SQL user structure (if data source is SQL database). A NULL SQL user structure indicates a non SQL data source.
bOverwrite	ESS_BOOL_T	Indicates overwrite or append error message to the error file.
usBuildOption	ESS_USHORT_T	Valid values: ESS_INCDIMBUILD_BUILD Build members only. ESS_INCDIMBUILD_VERIFY Build members and verify the outline. ESS_INCDIMBUILD_SAVEOTL Build members and save the outline to a temp outline file. ESS_INCDIMBUILD_ALL Build members, verify the outline, and restructure. ESS_INCDIMBUILD_ABORT Abort the build process.
szTmpOtlFile	ESS_STR_T	The temporary outline file name. No extension or path is needed. Essbase creates a temporary outline file in the app/db directory, with an extension of .otb, if the resulting outline in this round of dimension build has outline verification errors.

Notes

This function returns an error if the data object is located on the client. The network connection between client and server remains active even if an error is returned.

You must call EssCloseAsyncProc to close the connection; otherwise, the server request handler blocks further requests from the same login session.

Return Value

Returns zero if successful; error code if unsuccessful.

Example

void ESS_AsyncBuildDim()
{
	ESS_STS_T sts = 0;
	ESS_OBJDEF_T Rules;
	ESS_OBJDEF_T Data;
	ESS_PMBRUSER_T pMbrUser; 
	ESS_BOOL_T bOverwrite;
	ESS_USHORT_T usBuildOption;
	ESS_STR_T szTmpOtlFile;
	ESS_STR_T bldDimErrFile;
	ESS_STR_T asyncProcErrLog;
	ESS_BLDDL_STATE_T procState;
	ESS_BOOL_T errFileOverWrite;

	szAppName = "Sample";
	szDbName = "Basic";
	ESS_SetActive();
	
	AddMember("800");

	sts = EssBeginIncrementalBuildDim(hCtx);
	printf("EssBeginIncrementalBuildDim sts: %ld\n",sts);

	memset(&Rules,0,sizeof(ESS_OBJDEF_T));
	memset(&Data,0,sizeof(ESS_OBJDEF_T));
	Rules.hCtx     = hCtx;
	Rules.FileName = "apgeibl"; 
	Rules.AppName  = szAppName;
	Rules.DbName   = szDbName;
	Rules.ObjType  = ESS_OBJTYPE_RULES;
	Data.hCtx      = hCtx;
	Data.AppName   = szAppName;
	Data.DbName    = szDbName;
	Data.ObjType   = ESS_OBJTYPE_TEXT;    
	Data.FileName  = "apgeibl1";

	pMbrUser = ESS_NULL; 	   
	bOverwrite = ESS_TRUE; 
	usBuildOption = ESS_INCDIMBUILD_BUILD; 
	szTmpOtlFile = "asyncBldTmp";
	sts = EssAsyncBuildDim(hCtx, &Rules, &Data, pMbrUser, bOverwrite, usBuildOption, szTmpOtlFile);
	printf("EssAsyncBuildDim sts: %ld\n",sts);

	sts = EssGetAsyncProcLog (hCtx, ".\\AsyncProc.log", ESS_TRUE);
	printf("EssGetAsyncProcLog sts: %ld\n",sts);

	sts = EssGetAsyncProcState(hCtx, &procState);
	printf("EssGetAsyncProcState sts: %ld\n",sts);
	if(!sts)
	{
		do
		{
			DisplyProcesStateInfo(procState);
			if(procState.ilProcessStatus)
			{
				sts = EssCancelAsyncProc(hCtx, asyncProcErrLog, errFileOverWrite);
				printf("EssCancelAsyncProc sts: %ld\n",sts);
			}
			else
			{
				sts = EssGetAsyncProcState(hCtx, &procState);
				printf("EssGetAsyncProcState sts: %ld\n",sts);
			}

		}while(procState.usProcessState != ESS_BLDDL_STATE_DONE);
		
		if(!procState.ilProcessStatus)
		{
			sts = EssCloseAsyncProc(hCtx, &procState);
			printf("EssCloseAsyncProc sts: %ld\n",sts);
		}
	}

	bldDimErrFile = "F:\\testArea\\mainapi\\BldDim.err";
	sts = EssEndIncrementalBuildDim(hCtx, ESS_DOR_ALLDATA, szTmpOtlFile, bldDimErrFile, ESS_FALSE);
	printf("EssEndIncrementalBuildDim sts: %ld\n",sts);
}