# EssOtlQueryMembersByName

Description

EssOtlQueryMembersByName() queries the outline.

Syntax

    ESS_FUNC_M EssOtlQueryMembersByName (hOutline, pszMember, pPredicate,
                                         pMbrCounts, phMemberArray);

ESS_HOUTLINE_T | hOutline
ESS_STR_T | pszMember
ESS_PPREDICATE_T | pPredicate
ESS_MBRCOUNTS_T | pMbrCounts
ESS_PPHMEMBER_T | phMemberArray

Parameters

hOutline | Essbase outline handle. This must have been returned from EssOtlOpenOutlineQuery().
pszMember | The member name string of the member to do the operation on. If this value is NULL, it is assumed to be the very top of the outline, representing the logical parent of the dimensions. This value will be ignored for the following options: ESS_NAMEDGENERATION ESS_NAMEDLEVEL ESS_USERATTRIBUTE ESS_SEARCH ESS_WILDSEARCH
pPredicate | Structure defining the query. The fields of this structure are used as follows: ulQuery Value defining the operation to perform. It can be one of the following: ESS_CHILDREN ESS_DESCENDANTS ESS_BOTTOMLEVEL ESS_SIBLINGS ESS_SAMELEVEL ESS_SAMEGENERATION ESS_PARENT ESS_DIMENSION ESS_NAMEDGENERATION ESS_NAMEDLEVEL ESS_SEARCH ESS_WILDSEARCH ESS_USERATTRIBUTE ESS_ANCESTORS ESS_DTSMEMBERS ESS_DIMUSERATTRIBUTES ulOptions Value defining search options. One of the following values: ESS_COUNTONLY - returns no member handles, but only fills in the pTotalCount field in the pCounts structure ESS_NOTOTALCOUNTS ESS_INCLUDEHYBRIDANALYSIS ESS_EXCLUDEHYBRIDANALYSIS ESS_FORCECASESENSITIVE ESS_FORCEIGNORECASE When the Query type is set to ESS_SEARCH or ESS_WILDSEARCH three additional values for Option are valid: ESS_MEMBERSONLY ESS_ALIASESONLY ESS_MEMBERSANDALIASES pszString1 Input string that is determined by the option. It is used with the following query options and ignored otherwise: ESS_NAMEDGENERATION - The name of the generation ESS_NAMEDLEVEL - The name of the level ESS_SEARCH - The string to search for. The string is defined as an exact ESS_WILDSEARCH - The string to search for. The string is defined as an exact search string with an optional '*' at the end to mean any set of characters. ESS_USERATTRIBUTE - The user defined attribute pszString2 Input string that is determined by the option. It is used with the following query options and ignored otherwise: ESS_USERATTRIBUTE - The user defined attribute. ESS_SEARCH, ESS_WILDSEARCH - If the options are set to look in the alias tables, this string specifies the alias table to search in. If it's null, all alias tables will be searched.
pMbrCounts | Structure defining information about member counts. It contains the following fields: ulStart Starting number to return. ulMaxCount Maximum number of member handles to return. ulTotalCount Total number of members that are defined in the results of the query. pulReturnCount Number of member handles returned in this query.
phMemberArray | An array of member handles returned from the query.

Return Value

The return value is zero if the function was successful.

Notes

- The call takes a member name string to operate on and returns an array of member handles satisfying the criteria specified by the option value.
- The caller should call EssOtlFreeMembers() when the returned phMembers member array is no longer needed.
- Each hMember element in 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().

Example

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

    ESS_STS_T          sts = ESS_STS_NOERR;
    ESS_HOUTLINE_T     hOutline;
    ESS_OBJDEF_T       Object;
    ESS_STR_T          pszMember;
    ESS_PREDICATE_T    Predicate;
    ESS_MBRCOUNTS_T    Counts;
    ESS_PHMEMBER_T     phMemberArray = ESS_NULL;
    ESS_ULONG_T        i;
    ESS_ACCESS_T       Access;
    ESS_STR_T          AppName;
    ESS_STR_T          DbName;

    pszMember = "Qtr1";
    AppName = "Sample";
    DbName = "Basic";

    sts = EssSetActive(hCtx, AppName, DbName, &Access);

    if ( sts == 0)
    {
       memset(&Object, '\0', sizeof(Object));

       sts = EssOtlOpenOutlineQuery(hCtx, &Object, &hOutline);

       memset(&Predicate, '\0', sizeof(Predicate));
       Predicate.ulQuery           = ESS_CHILDREN;
       Predicate.pszDimension  = "Year";

       memset(&Counts, '\0', sizeof(Counts));
       Counts.ulStart          = 0;
       Counts.ulMaxCount = 10;

       if(!sts)
       {
         sts = EssOtlQueryMembersByName(hOutline, pszMember,
               &Predicate, &Counts, &phMemberArray);

         if (!sts && Counts.ulReturnCount)
         {
            sts = EssOtlFreeMembers(hOutline,
                  Counts.ulReturnCount, phMemberArray);
         }
       }
    }

See Also

EssOtlFreeMembers()
EssOtlGetDimensionUserAttributes()
EssOtlOpenOutlineQuery()
EssOtlQueryMembers()