EssOtlQueryMembersEx

Queries the outline for specific members and member fields, and returns an array of member handles. The returned member handles can be used with other Outline API functions such as EssOtlGetMemberInfo(). (EssOtlGetMemberInfo() can retrieve any of the individual fields contained in ESS_MEMBERINFO_T and ESS_MBRINFO_T.)

Syntax

ESS_FUNC_M EssOtlQueryMembersEx (hOutline, pszFieldSelection, pszMemberSelection,
                                   pMaxCount, ppMemberArray, ppqryErrorList)

Parameter	Data Type	Description
hOutline	ESS_HOUTLINE_T	Essbase outline handle. This must have been returned from EssOtlOpenOutlineQuery().
pszFieldSelection	ESS_STR_T	The query string which defines the set of fields that will be returned for each member. The syntax of pszFieldSelection is shown in Notes.
pszMemberSelection	ESS_STR_T	The query string which defines the set of members to be returned. The syntax of this query string is the syntax for member selection; that is, the query string can be anything that you can use in a FIX() statement.
pMaxCount	ESS_PULONG_T	Input: A pointer to the maximum number of member handles to be returned. Output: A pointer to the number of member handles returned.
ppMemberArray	ESS_PPHMEMBER_T	Reference to a pointer to the first in an array of member handles returned.
ppqryErrorList	ESS_OTLQUERYERRORLIST_T	Reference to a pointer to a structure containing the list of errors in the query.

Notes

In an outline that allows duplicate member names, this function returns the fully qualified names of shared members. For example, in Sample Basic, any query that includes the shared member 100-20 would return its fully qualified name, [Diet].[100-20].
Use of UniqueName as part of the member fields selection automatically includes ShareOption as part of the field selection.
EssOtlQueryMemberEx() takes an outline handle and returns an array of member handles specified by pszMemberSelection.
The caller should call EssOtlFreeMembers() when the returned pphMembers member array is no longer needed.
Each member handle element of the array can only be used in calls that are listed in EssOtlOpenOutlineQuery(). For example, a returned member handle cannot be used to call EssOtlGetSibling().

The syntax of pszFieldSelection is the following:

QueryString ==: <SelectMbrInfo ( FieldName {, FieldName}, ... )

where FieldName is one of the following:

MemberName                    /* Member name */        
MemberLevel                   /* Member level number */
MemberGeneration              /* Member generation number */
Cosolidation                  /* Whether this member is consolidated */
TwoPass                       /* Whether this member undergoes a two pass operation */
Expense                       /* Whether this is an expense member */
CurrencyConvType              /* Currency conversion type */
CurrencyMember                /* Whether this is a currency member */
TimeBalance                   /* Time balance measure */
SkipOption                    /* Whether this member skips the time balance operation */
ShareOption                   /* Whether this is a shared member*/
StorageType                   /* Dimension's storage type */
DimensionCategory             /* Dimension category: accounts, time, currency, etc. */
DimensionStorageCategory      /* Dimension storage category: time, units, scenario, etc. */
Comment                       /* Member comment */
ChildrenCount                 /* Number of children */
MemberNumber                  /* Member number */
DimensionName                 /* Dimension name */
DimensionNumber               /* Dimension number */
MemberAliasName               /* Alias for this member */
ParentMemberName              /* Parent's name */
ChildMemberName               /* Child's name */
PreviousMemberName            /* Left sibling's name */
NextMemberName                /* Right sibling's name */
CurrencyConversionDatabase    /* Whether this database has currency conversion */
MemberStatus                  /* Member status */
UDAList                       /* List of UDAs attached to this member */
MemberFormula                 /* Formula for this member */
MemberValidity                /* Whether this member is valid */
Attributes                    /* All attribute fields. If the member is not attributed, then attribute name is set to NULL */
UniqueName                    /* If the member is duplicate, its fully qualified, unique name.  */

Note:

There is no leading '<' character for the individual fieldnames.

To use this function with EssOtlGetMemberField(), include in this function's pszFieldSelection string the same fields that you will specify using the MbrFieldID constants of EssOtlGetMemberField(). Otherwise, EssOtlGetMemberField() returns the error OTLAPI_ERR_MBRINVALID.

Return Value

The return value is zero if the function was successful.

Example

The following code snippet return the name, consolidation and formula for each menmber which is a child of Market or a child of Product. Upon return, MaxCount contains the number of members returned, and phMemberArray contains the array of handles for the set of members returned. Further Outline API calls allow interrogation of the members using the returned array of member handles in phMemberArray.

member_fields     = "<SelectMbrInfo ( MemberName, Consolidation, MemberFormula ) ";
member_selection  = "@ichild(Product), @ichild(Market)";
MaxCount          = -1;
phMemberArray     = ESS_NULL;
pqryErrorList     = ESS_NULL;

sts = EssOtlQueryMembersEx(hOutline,
                           member_fields,
                           member_selection,
                           &MaxCount,
                           &phMemberArray,
                           &pqryErrorList);
                                                   
if (sts != 0) goto error_exit;

See Extended Member Query Code Example for an example that uses EssOtlQueryMembersEx(), EssOtlGetMemberField(), and ESS_OTLQUERYERRORLIST_T, and includes calls to EssOtlFreeMembers() and EssFree().