EssOtlAddMember

Adds a member to the outline and sets the member's attributes.

Syntax

ESS_FUNC_M EssOtlAddMember (hOutline, pMemberInfo, hParent, hPrevSibling, 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.
hParent;	ESS_HMEMBER_T	Handle of parent. This field is used only if the hPrevSibling field is ESS_NULL.
hPrevSibling;	ESS_HMEMBER_T	Handle of previous sibling.
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.
The member name must be unique unless you are creating a shared member.
Position of the added member:
- The new member is inserted following the hPrevSibling member.
- If the hPrevSibling field is ESS_NULL, the new member becomes the first child of the parent specified by hParent.
- If both hParent and hPrevSibling are ESS_NULL, the new member becomes the first dimension in the outline.
To add a shared member:
- The shared member must be a zero-level (leaf node) member. (Shared members cannot have children.)
- The actual member must already exist in the dimension.
- Set the usShare field of the ESS_MBRINFO_T structure to ESS_SHARE_SHARE.
To add a LABEL member:
- You must first add the member without the label attribute set.
- Next, add its children. (A label member must have children.)
- Then, use EssOtlSetMemberInfo() to set the label tag of the label member.

To add an attribute member, 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	For an attribute dimension or zero-level (leaf node) attribute member, set one of the following data types: ESS_ATTRMBRDT_BOOL ESS_ATTRMBRDT_DATETIME ESS_ATTRMBRDT_DOUBLE ESS_ATTRMBRDT_STRING You may instead set a zero-level (leaf node) attribute member to ESS_ATTRMBRDT_AUTO. You may set attribute members that are not zero level to ESS_ATTRMBRDT_NONE or ESS_ATTRMBR_AUTO.

Notes on Adding an Attribute Member:
- Adding a zero-level attribute member that is not of type ESS_ATTRMBRDT_STRING also sets the szMember field of the ESS_MBRINFO_T structure to the attribute member's long name, using the specifications for the outline in the ESS_ATTRSPECS_T structure.
- You must set usCategory and usStorageCategory for an attribute member, as well as an attribute dimension. (You need not set usCategory and usStorageCategory for a base member. You must set them for a base dimension only.)
- Do not set the szDimName field of the ESS_MBRINFO_T structure.
- For a zero-level attribute member that is not of type ESS_ATTRMBRDT_STRING, do not set the Attribute.value field of the ESS_ATTRIBUTEVALUE_T structure. The attribute value is derived internally by converting the attribute member long name.
- If you set an attribute member's data type to ESS_ATTRMBRDT_AUTO, Essbase does the following:
  - Sets the member's data type to the data type of its dimension, if the member name can be converted to a value of that type.
  - If the member name cannot be converted to a value of the dimension's data type, sets the member's data type to ESS_ATTRMBRDT_NONE.
  - For the first child member converted from ESS_ATTRMBRDT_AUTO to a data type other than ESS_ATTRMBRDT_NONE, converts the parent's long name to a short name.

To add a dimension:
- To add an attribute dimension, call EssOtlAddDimension(). Do not call EssOtlAddMember().
- To add a dimension that is not an attribute dimension, call either EssOtlAddDimension() 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 assigned the data values associated with the existing dimensions.

Return Value

Returns 0 if successful; otherwise one of the following:

OTLAPI_BAD_CONSOL
OTLAPI_BAD_MBRNAME
OTLAPI_ERR_ADDNAMEUSED
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_NOSHAREPROTO
OTLAPI_ERR_NOTIMEDIM

Example

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

ESS_STS_T          sts = 0; 
ESS_OBJDEF_T       Object; 
ESS_HOUTLINE_T     hOutline; 
ESS_MBRINFO_T      MbrInfo; 
ESS_HMEMBER_T      hMemberProfit; 
ESS_HMEMBER_T      hNewMember; 
ESS_APPNAME_T      szAppName; 
ESS_DBNAME_T       szDbName; 
ESS_OBJNAME_T      szFileName;

memset(&Object, '\0', sizeof(Object));
Object.hCtx = hCtx; 
Object.ObjType = ESS_OBJTYPE_OUTLINE; 
strcpy(szAppName, "Sample"); 
strcpy(szDbName, "Basic"); 
strcpy(szFileName, "Basic"); 
Object.AppName = szAppName; 
Object.DbName = szDbName; 
Object.FileName = szFileName;

sts = EssOtlOpenOutline(hCtx, &Object,
 ESS_TRUE, ESS_TRUE, &hOutline);

if (!sts) 
{ 
   sts = EssOtlFindMember(hOutline, "Profit",
         &hMemberProfit);
}
if (!sts && hMemberProfit) 
{ 
   memset(&MbrInfo, '\0', sizeof(MbrInfo)); 
   strcpy(MbrInfo.szMember, "Inventory"); 
   sts = EssOtlAddMember(hOutline, &MbrInfo,
         ESS_NULL, hMemberProfit, &hNewMember); 
}