EsbOtlQueryMembersByName

Queries the outline.

Syntax

EsbOtlQueryMembersByName (hOutline, pszMember, pPredicate, pCounts)
ByVal hOutline   As Long 
ByVal pszMember  As String
      pPredicate As ESB_PREDICATE_T
      pCounts    As ESB_MBRCOUNTS_T

Parameter	Description
hOutline	Essbase outline handle. This must have been returned from EsbOtlOpenOutlineQuery().
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: ESB_NAMEDGENERATION ESB_NAMEDLEVEL ESB_USERATTRIBUTE ESB_SEARCH ESB_WILDSEARCH
pPredicate	Structure defining the query. The fields of this structure are described in Notes.
pCounts	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.

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 EsbOtlFreeMember() 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 EsbOtlOpenOutlineQuery(). For example, a returned member handle cannot be used to call EsbOtlGetSibling().
The programmer should call EsbGetNextItem() once for each member handle returned.
The fields of the pPredicate structure are used as follows:
- ulQuery—Value defining the operation to perform. It can be one of the following:
  - ESB_CHILDREN
  - ESB_DESCENDANTS
  - ESB_BOTTOMLEVEL
  - ESB_SIBLINGS
  - ESB_SAMELEVEL
  - ESB_SAMEGENERATION
  - ESB_PARENT
  - ESB_DIMENSION
  - ESB_NAMEDGENERATION
  - ESB_NAMEDLEVEL
  - ESB_SEARCH
  - ESB_WILDSEARCH
  - ESB_USERATTRIBUTE
  - ESB_ANCESTORS
  - ESB_DTSMEMBERS
  - ESB_DIMUSERATTRIBUTES
- ulOptions—Value defining any options. It is used with the following query options:
  - ESB_SEARCH, ESB_WILDSEARCH—One of the following values:
    ESB_MEMBERSONLY
    ESB_ALIASESONLY
    ESB_MEMBERSANDALIASES
  - All Options—ESB_COUNTONLY: Returns no member handles, but only fills in the pTotalCount field in the pCounts structure
- szDimension—Dimension to limit the scope of the query. It is used with the following query options and ignored otherwise:
  - SB_NAMEDGENERATION
  - ESB_NAMEDLEVEL
  - ESB_USERATTRIBUTE
  - ESB_SEARCH—Set to NULL to search through all dimensions
  - ESB_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:
  - ESB_NAMEDGENERATION - The name of the generation
  - ESB_NAMEDLEVEL - The name of the level
  - ESB_SEARCH - The string to search for. The string is defined as an exact
  - ESB_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.
  - ESB_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:
  - ESB_USERATTRIBUTE—User defined attribute.
  - ESB_SEARCH, ESB_WILDSEARCH—If the options are set to look in the alias tables, specifies the alias table to search in. If it's null, all alias tables will be searched.

Return Value

The return value is zero if the function was successful.

Example

Declare Function EsbOtlQueryMembersByName Lib "ESBOTLN" 
(ByVal hOutline As Long, ByVal pszMember As String,
pPredicate As ESB_PREDICATE_T, pCounts As ESB_MBRCOUNTS_T) As Long
Declare Function EsbOtlFreeMember Lib "ESBOTLN" 
(ByVal hOutline As Long, ByVal hMember As Long) As Long

Sub ESB_OtlQueryMembersByName()
   Dim sts As Long
   Dim hOutline As Long
   Dim pszMember As String
   Dim ihMember As Long
   Dim Object As ESB_OBJDEF_T
   Dim MbrInfo As ESB_MBRINFO_T
   Dim Predicate As ESB_PREDICATE_T
   Dim Counts As ESB_MBRCOUNTS_T
   Dim Access As Integer
   Dim AppName As String
   Dim DbName As String
   
   pszMember =  "Qtr1"
   AppName = "Sample"
   DbName = "Basic"
   sts = EsbOtlOpenOutlineQuery(hCtx, Object, hOutline)   'open outline
   If sts = 0 Then                                        'proceed if open successful
                                                          'else message with error
      Predicate.ulQuery = ESB_CHILDREN
      Predicate.pszDimension = "Year"
      Counts.ulStart = 0
      Counts.ulMaxCount = 10
      If sts = 0 Then
         sts = EsbOtlQueryMembersByName(hOutline, pszMember, Predicate, Counts)
        If sts = 0 And Counts.ulReturnCount <> 0 Then
          For n% = 1 To Counts.ulReturnCount
             sts = EsbGetNextItem(hCtx, ESB_HMEMBER_TYPE, ihMember)
          If sts = 0 And ihMember <> 0 Then
                   sts = EsbOtlFreeMember(hOutline, ihMember)
          End If
          Next
        End If
      End If
   Else
     msgbox "Outline open failed with error: " & sts
   Endif
End Sub