EssOtlQueryMembersExArray

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 EssOtlQueryMembersExArray (hOutline, pszFieldSelection, queryCount, pszMemberSelectionArr, pMaxCountArr, pphMemberArr, ppqryErrorList)

Parameter	Data Type	Description
hOutline	ESS_HOUTLINE_T	Outline handle returned from EssOtlOpenOutlineQuery().
pszFieldSelection	ESS_STR_T	Selects the member fields that the queries return. The same selections are used for all queries in the array.
queryCount	ESS_SHORT_T	Count of members in the input array.
pszMemberSelectionArr	ESS_STR_T	Array of queryCount query strings for member selection. 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.
pMaxCountArr	ESS_PULONG_T	Array of queryCount values for how many members each query in the array at most should return. Each value is replaced with the actual returned count.
pphMemberArr	ESS_PPHMEMBER_T	queryCount array of returned member handle arrays (each with pMaxCountArr[i] values).
ppqryErrorList	ESS_OTLQUERYERRORLIST_T	List of members with errors.

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.
EssOtlQueryMemberExArray() 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.

Return Value

Returns zero (0) if successful.

Example

The following code snippet returns the name, consolidation and formula for each member that is a child of Market and for each member that is a child of Product in two separate member arrays. It combines what would have been two queries in EssOtlQueryMembersEx into just one call to EssOtlQueryMembersExArray. Note that the member fields returned will be the same for all queries in the array, and that the size of all arrays must match queryCount.

Upon return, MaxCountArray[i] contains the number of members returned in each query, and phMemberArrayArray[i] contains the array of handles for the set of members returned for each query. Further Outline API calls allow interrogation of the members using the returned array of member handles in phMemberArrayArray[i].

member_fields = "<SelectMbrInfo ( MemberName, Consolidation, MemberFormula ) ";
queryCount = 2;
member_selectionArray[0] = "@ichild(Product)";
member_selectionArray[1] = "@ichild(Market)";
MaxCountArray[0] = -1;
MaxCountArray[1] = -1;
phMemberArrayArray[0] = ESS_NULL;
phMemberArrayArray[1] = ESS_NULL;
pqryErrorListArray[0] = ESS_NULL;
pqryErrorListArray[1] = ESS_NULL;
 
sts = EssOtlQueryMembersExArray(hOutline, member_fields, queryCount, member_selectionArray, MaxCountArray, &phMemberArrayArray, pqryErrorListArray);
 
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().