EssOtlAddMember
Description
EssOtlAddMember() adds a member to the outline and sets
the member's attributes.
Syntax
ESS_FUNC_M EssOtlAddMember (hOutline, pMemberInfo, hParent, hPrevSibling, phMember);
ESS_HOUTLINE_T |
hOutline;
|
ESS_PMBRINFO_T
|
pMemberInfo;
|
ESS_HMEMBER_T |
hParent;
|
ESS_HMEMBER_T |
hPrevSibling;
|
ESS_PHMEMBER_T |
phMember;
|
Parameters
hOutline | Outline context handle.
|
pMemberInfo | Member information structure defining the member and its attributes.
|
hParent | Handle of parent. This field is used only if the hPrevSibling field is ESS_NULL.
|
hPrevSibling | Handle of previous sibling.
|
phMember | Handle of new member returned from the API.
|
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
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.
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);
}
See Also
EssOtlAddDimension()
EssOtlDeleteMember()
EssOtlDeleteDimension()
EssOtlSetMemberInfo()
EssOtlFindMember()