EssOtlAddDimension

Adds a dimension to the outline and sets the member's attributes. The call also specifies a member of the new dimension to associate data with when the outline is restructured.

Syntax

ESS_FUNC_M EssOtlAddDimension (hOutline, pMemberInfo, hPrevSibling, pszDataMbr, phMember);

Parameter	Data Type	Description
hOutline;	ESS_HOUTLINE_T	Outline context handle.
pMemberInfo;	ESS_MBRINFO_T	Member information structure defining the member and its attributes.
hPrevSibling	ESS_HMEMBER_T	Handle of previous sibling. If this field is ESS_NULL, the dimension becomes the first dimension in the outline. Otherwise, the dimension is placed after the dimension specified in hPrevSibling.
pszDataMbr;	ESS_STR_T	Member name of a member in the new dimension that will receive the data values when the outline is restructured. If this field is ESS_NULL, the dimension member itself is used.
phMember	ESS_PHMEMBER_T	Handle of new member returned from the API.

Notes

The ESS_MBRINFO_T structure must be created and filled before calling this function.
To add an attribute dimension, you must call this function.
To add a dimension that is not an attribute dimension, you can call this function or EssOtlAddMember().
- EssOtlAddDimension() gives you the benefit of selecting any member in the added dimension to be assigned the data values associated with the existing dimensions.
- If EssOtlAddMember() is used, the top member (dimension) of the added dimension is used.
In order for the pszDataMbr field to take effect, the outline must have been opened using EssOtlOpenOutline() with the fKeepTrans flag set to ESS_TRUE.
The member referred to in the pszDataMbr field is added to the new dimension using EssOtlAddMember() after the dimension is created. If the referred to member doesn't exist when restructuring takes place, the dimension member is used instead.

For an attribute dimension, you must set the fields of ESS_MBRINFO_T as follows:

Field	Setting
usConsolidation	ESS_UCALC_NOOP
fTwoPass	ESS_FALSE
fExpense	ESS_FALSE
usConversion	ESS_CONV_NONE
usTimeBalance	ESS_TIMEBAL_NONE
usSkip	ESS_SKIP_NONE
usShare	ESS_SHARE_DYNCALCNOSTORE
usStorage	ESS_DIMTYPE_SPARSE
usCategory	ESS_CAT_ATTRIBUTE
usStorageCategory	ESS_STORECAT_ATTRIBUTE
Attribute.usDataType	One of the following attribute member data types: ESS_ATTRMBRDT_BOOL ESS_ATTRMBRDT_DATETIME ESS_ATTRMBRDT_DOUBLE ESS_ATTRMBRDT_STRING

An attribute dimension must be associated with a base dimension.
Attribute dimensions must be placed after base dimensions and standard dimensions.

Return Value

Returns 0 if successful; otherwise one of the following:

OTLAPI_BAD_CONSOL
OTLAPI_BAD_MBRNAME
OOTLAPI_ERR_ADDNAMEUSEDTLAPI_ERR_ADDDELETEDIMDYNAMICCALC
OTLAPI_ERR_BADSHARE
OTLAPI_ERR_BADSKIP
OTLAPI_ERR_BADSTORAGE
OTLAPI_ERR_BADSTORAGECATEGORY
OTLAPI_ERR_BADTIMEBAL
OTLAPI_ERR_CURTOOMANYDIMS
OTLAPI_ERR_ILLEGALBOOLEAN
OTLAPI_ERR_ILLEGALCURRENCY
OTLAPI_ERR_ILLEGALDATE
OTLAPI_ERR_ILLEGALNUMERIC
OTLAPI_ERR_ILLEGALTAG
OTLAPI_ERR_LEAFLABEL
OTLAPI_ERR_NONATTRDIMFOLLOWED
OTLAPI_ERR_NOSHAREPROTO
OTLAPI_ERR_NOTIMEDIM

Example

#include <essapi.h>
#include <essotl.h> 

ESS_STS_T           sts = 0;
ESS_OUTLINEINFO_T  NewInfo; 
ESS_HOUTLINE_T     hOutline;
ESS_MBRINFO_T      MbrInfo; 
ESS_HMEMBER_T      hDimMeasures;

memset (&NewInfo,'\0', sizeof(NewInfo));
sts = EssOtlNewOutline(hCtx, &NewInfo,
      &hOutline);
if (!sts) 
{
memset(&MbrInfo, '\0', sizeof(MbrInfo));
strcpy(MbrInfo.szMember, "Measures");
MbrInfo.usStorage = ESS_DIMTYPE_SPARSE; 
MbrInfo.usCategory = ESS_CAT_ACCOUNTS;
sts = EssOtlAddDimension(hOutline, &MbrInfo, 
ESS_NULL, "Profit",&hDimMeasures);
}