# EssOtlQueryMembersEx

Description

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)

ESS_HOUTLINE_T | hOutline
ESS_STR_T | pszFieldSelection
ESS_STR_T | pszMemberSelection
ESS_PULONG_T | pMaxCount
ESS_PPHMEMBER_T | ppMemberArray
ESS_PPOTLQUERYERRORLIST_T | ppqryErrorList

Parameters

hOutline | Essbase outline handle. This must have been returned from EssOtlOpenOutlineQuery().
pszFieldSelection | The query string which defines the set of fields that will be returned for each member. The syntax of pszFieldSelection is shown below.
pszMemberSelection | 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 | Input: A pointer to the maximum number of member handles to be returned. Output: A pointer to the number of member handles returned.
pphMemberArray | Reference to a pointer to the first in an array of member handles returned.
ppQueryErrorList | Reference to a pointer to a structure containing the list of errors in the query.

Return Value

The return value is zero if the function was successful.

Notes

- 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 */
      AttrDimensionNames            /* Attribute dimensions associated with this member's dimension *
      MemberAttributed              /* Whether this member is attributed */
      AttributeDataType             /* Attribute data type for this member */
      AttributeDataValue            /* Attribute data value for this member */

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

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 for an example that uses EssOtlQueryMembersEx(), EssOtlGetMemberField(), and ESS_OTLQUERYERRORLIST_T, and includes calls to EssOtlFreeMembers() and EssFree().

See Also

EssOtlFreeMembers()
EssOtlGetDimensionUserAttributes()
EssOtlGetMemberField()
EssOtlOpenOutlineQuery()
EssOtlQueryMembers()
EssOtlQueryMembersByName()