FindNext Method

Finds the next matching category label in a report.

Syntax

Report.FindNext (SearchText [, Pattern [, AllLayers [, Dimension]]])

Applies To

Report Object

Discussion

Use this method to locate categories within reports. Use the Execute method to locate categories within a cube.

FindNext looks for the next category in the report that matches the value prescribed by the parameters. If a match is found, True is returned; otherwise, False is returned.

The method's four parameters set the search options. Once the required parameter SearchText is given, the three optional parameters let you determine:

  • if the search string is to be found anywhere in a word, at the start of a word only, or the end of a word only
  • if pattern matching is set on or off
  • if the search text is to match the whole word or any part of the word
  • if the search is to be case sensitive
  • if the current layer or all layers are to be searched
  • if labels in rows, columns, layers or a combination of these are to be searched

If you search all three report dimensions (rows, columns, layers), the search progresses downward one layer at a time in the following order:

  • rows in the current layer
  • columns in the current layer
  • the current layer label

The search ignores any hidden categories inside the report.

When a search returns True (that is, a match was found), the cursor is positioned on the matching label.

In nested crosstabs, FindNext searches for labels in each dimension, beginning at the current cursor position, and moves downward through the hierarchy to the lowest level.

When you set one of the three optional parameters, you must also set any optional parameters to its left, even if just the default is given. For example, to search just the rows dimension (value = 1) for the next label that contains "GO" in the current layer, your code looks like this:

FindNext("GO", 1, FALSE, 1)

Even though the second and third parameters use the defaults, they are needed as placeholders when changing the fourth. However, you can omit parameters if you need just the left-hand parameters and those to the right remain at their default settings.

To turn on more than one search option for the Pattern or Dimension parameters, add up the search option values. For example, to search just columns in the current layer for the next label beginning with "GO" with case sensitivity turned on, the code looks like this:

FindNext("GO", 34)

If you also want to search all rows, columns, and layers (Dimension = 7), the code looks like this:

FindNext("GO", 34, FALSE, 7)

Unless you specifically include a value for a parameter, the search option is not in effect. For example, to make a search case sensitive, you must include the value 32.

Adding values that cannot be used together causes an exception error. For example, don't combine the Contains, Begins With, or Ends With values since they are mutually exclusive. Do not use any of these with MatchWhole. Pattern Matching (Pattern = 8) cannot be used with MatchCase (Pattern = 16) or MatchWhole (Pattern = 32).

Examples of valid combinations include:

  • MatchCase + Pattern Matching = (40)
  • MatchCase + Contains = (33)
  • MatchCase + Begins With = (34)
  • MatchCase + Ends With = (36)
  • MatchCase + MatchWhole = (48)

When the Pattern Matching value is used (Pattern = 8), the Find operation recognizes some characters in the text string as wildcards and some metacharacters are treated as reserved characters. If the metacharacters are included, an error message appears. If pattern matching is not used, wildcards and metacharacters are treated as normal characters.

Parameter

Description

SearchText

Required. Specifies the text to search for. Can contain wildcards if pattern matching (8) is turned on. An empty string is invalid.

Type: String

Pattern

Optional. Specifies the search options. (There are certain reserved characters noted below.) Values are added to set option variations.

1 = Contains: the search text can be found anywhere in a word 2 = Begins With: the search text must be found at the start of a word 4 = Ends With: the search text must be found at the end of a word 8 = Pattern Matching: certain characters are treated as wildcards (these are listed in the table below) 16 = MatchWhole: the search text must match the whole word 32 = MatchCase: the search is case sensitive

Default: 1

Type: Integer

AllLayers

Optional. Specifies whether or not all layers or just the current layer are searched. Valid options are

True = all layers False = current layer

Default: False

Type: Boolean

Dimension

Optional. Specifies the scope of the search.

1 = row labels only 2 = column labels only 3 = row and column labels only 4 = layer labels only 5 = layer and row labels only 6 = layer and column labels only 7 = all labels

Default: 3

Type: Integer

Return Type

Boolean

Example

This example searches for the next row beginning with "Star", if no row is found it tries to find the previous row containing "Star". A message is returned confirming whether a matching row was found.

Sub Main()
   Dim objPPRep As Object
   Dim intFound As Integer
   Const begins_with = 2
   Const current_layer = False
   Const rows = 1
   Set objPPRep = GetObject(, "CognosPowerPlay.Report")
   intFound = objPPRep.FindNext("Star", begins_with,
_
      current_layer, rows)
   If intFound = 0 Then
      intFound = objPPRep.FindPrevious("Star", _
         begins_with, current_layer, rows)
   End If
   If intFound <> 0 Then
      objPPRep.Rows.Active.Select
      MsgBox "A row was found and has been selected."
   Else
      MsgBox "No rows found matching criteria."
   End If
   Set objPPRep = Nothing
End Sub

Related Topics