EssOtlQueryMembers

Queries the outline.

Syntax

ESS_FUNC_M EssOtlQueryMembers (hOutline, hMember, pPredicate, pMbrCounts, phMemberArray);

Parameter	Data Type	Description
hOutline	ESS_HOUTLINE_T	Essbase outline handle. This must have been returned from EssOtlOpenOutlineQuery.
hMember	ESS_HMEMBER_T	The handle of the member on which execute the operation. If this value is NULL, it is assumed to be the very top of the outline, representing the logical parent of the dimensions. If the handle is a shared member, this function executes on the stored member on which it is based. This value will be ignored for the following options: ESS_NAMEDGENERATION ESS_NAMEDLEVEL ESS_USERATTRIBUTE ESS_SEARCH ESS_WILDSEARCH
pPredicate	ESS_PREDICATE_T	Structure defining the query. The fields of this structure are described in Notes.
pMbrCounts	ESS_MBRCOUNTS_T	Structure defining information about 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	ESS_PPHMEMBER_T	An array of member handles returned from the query.

Notes

The call takes a member handle 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 be used only in calls that are listed in EssOtlOpenOutlineQuery. For example, a returned member handle cannot be used to call EssOtlGetSibling.
The fields of the pPredicate 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
- ulOptions—Value defining search options. Valid values:
  - ESS_COUNTONLY—Returns no member handles, but 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
  To specify multiple values, use bitwise OR ( | ); for example:
```
ESS_FORCECASESENSITIVE | ESS_MEMBERSONLY
```
- 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—Name of the generation
  - ESS_NAMEDLEVEL—Name of the level
  - ESS_SEARCH—String to search for. The string is defined as an exact match.
  - ESS_WILDSEARCH—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—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—User defined attribute.
  - ESS_SEARCH, ESS_WILDSEARCH—If the options are set to look in the alias tables, this string specifies the alias table in which to search. If null, all alias tables are searched.

Return Value

The return value is zero if the function was successful.

Example

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

ESS_STS_T          sts = ESS_STS_NOERR; 
ESS_HOUTLINE_T     hOutline; 
ESS_OBJDEF_T       Object;
ESS_HMEMBER_T      hMember = 0;
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;

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 = EssOtlQueryMembers(hOutline, hMember, 
           &Predicate, &Counts, &phMemberArray);

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