EssOtlQueryMembersByName

Description

EssOtlQueryMembersByName() queries the outline.

Syntax

ESS_FUNC_M EssOtlQueryMembersByName (hOutline, pszMember, pPredicate,
                                     pMbrCounts, phMemberArray);
ESS_HOUTLINE_ThOutline
ESS_STR_TpszMember
ESS_PPREDICATE_T pPredicate
ESS_MBRCOUNTS_TpMbrCounts
ESS_PPHMEMBER_TphMemberArray

Parameters

hOutlineEssbase outline handle. This must have been returned from EssOtlOpenOutlineQuery().
pszMemberThe 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
pPredicateStructure 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 any options. It is used with the following query options:
ESS_SEARCH, ESS_WILDSEARCH - One of the following values:
ESS_MEMBERSONLY
ESS_ALIASESONLY
ESS_MEMBERSANDALIASES
All Options - One of the following values:
ESS_COUNTONLY - returns no member handles, but only fills in the pTotalCount field in the pMbrCounts structure

szDimension
Dimension to limit the scope of the query. It is used with the following query options and ignored otherwise:
ESS_NAMEDGENERATION
ESS_NAMEDLEVEL
ESS_USERATTRIBUTE
ESS_SEARCH - set to NULL to search through all dimensions
ESS_WILDSEARCH - set to NULL to search through all dimensions

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.

phMemberArrayAn array of member handles returned from the query.

Return Value

The return value is zero if the function was successful.

Notes

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