Syntax:

Set result = object.FindByName( name, [first [, maxElements [, depth ]]])

IDL definition:

[id(18), helpstring("method FindByName")] 
HRESULT FindByName(	[in] BSTR bstrName,
			[in,defaultvalue(1)] long lFirst,
			[in,defaultvalue(1)] long lMax,
			[in,defaultvalue(-1)] long lDepth,
			[out,retval] IDispatch** ppResult);

Parameters:

object - Previously created VarDictionary object

name - String - the name to search

first - (optional, number) specifies first element found to be returned (1- based). For example if there are 10 elements with this name and first is set to 5 - then the first 4 elements will not be returned. The default value is 1.

maxElement - (optional, number, default is 1) Maximum elements to return. Search will end when the maxElements are found.

depth - (optional, number, default is -1) If the VarDictionary is a collection of collections - i.e. some items in the collection are other VarDictionary objects you could think about the VarDictictionary object being searched as for a root node in a tree.

 depth specifies how deep the search will be. Value of -1 means unlimited, 0 means - only the current collection, positive number specifies the maximum levels to be searched.

Returns (result): A collection of the items found. Even if the found item is only one it will be placed in a collection containing one item (e.g. it will be its first element). The returned collection is new VarDictionary object. Thus you could determine the actual number of the found items by using the Count property and the found items can be enumerated using For Each ... constructions or indexing the items from 1 to result.Count. The retuned collection enumerates the items (not their names).

Examples:

' Fill some data to prepare the example
Set coll = CreateObject("newobjects.utilctls.VarDictionary")
coll.Add "A", 15
coll.Add "B", 32
coll.Add "C", coll.CreateNew
coll("C").Add "A", 12
coll("C").Add "B", "Blah"
Set found = coll.FindByName("A",1,100)
For k = 1 To found.Count
  Response.Write "Found A = " & found(k) & "<BR>"
Next

This example will output:
A = 15
A = 12

Let change the search criteria:
...
Set found = coll.Find("C",1,100)

This will return 1 item in the result collection. The item will be the sub-collection we added under the name "C". In the "real world" if you expect items returned to contain values and objects as well, and if the difference is important, the code inspecting the results will need to test the type of each returned item:

' Fill some data to prepare the example
Set coll = CreateObject(" newobjects.utilctls.VarDictionary")
coll.Add "A", 15
coll.Add "B", coll.CreateNew
coll("B").Add "X", "Blah blah"
coll("B").Add "C", coll.CreateNew
coll("B")("C").Add "C", 121
coll.Add "C", coll.CreateNew
coll("C").Add "A", 12
coll("C").Add "B", "Blah"
Set found = coll.FindByName("C",1,100)
For k = 1 To found.Count
  If IsObject(result(k)) Then
    Response.Write "Found object (subtree) <BR>"
  Else
    Response.Write "Found value C = " & found(k) & "<BR>"
  End If
Next

Remarks:

VarDictionary object is a flexible collection tool thus it is possible to use it to represent different structures and not only simple collections of values. For example ASP Compiler's parser returns the object model of the page as tree of VarDictionaries, ConfigFile object returns or expects VarDictionary trees - then they could be saved as entire branch in the registry or to a file.

Ability to search through such structures helps to build simple code that will not need to trace the tree itself in order to find single item (or a few) items. You are able to prepare similar complex structures on your own and represent a structured data and then search through it. 

The method returns a collection. This may look a bit hard to deal with but note the following statement:

Set found = coll.FindByName("C")(1)

As the result of the method call is a collection, we could get its first element immediately - in the same statement. Thus the (1) after the function call refers the result's first element! What will happen if nothing is found? The returned collection is a VarDictionary object too thus referring non-existent element (suppose the item with name "C" is not found) will not cause script error. The value of the Missing property will be returned instead. Thus the application may check what the result is and understand if the searched item is found or not. Usually most of the applications use Empty or Null for the missing property and respectively one of these values is returned. If the tree you are searching is returned by another object check its documentation to see how the collections are configured by the object. Let's illustrate the above - suppose Empty is returned:

Set found = coll.FindByName("C")(1)
If IsEmpty(found) Then
  ' Deal with the case when nothing is found
Else
  ' Ok - found the item
End IF

In many cases the application will expect the found item to be an object. For example you may want to find an item containing a sub-collection (branch of the tree) only. Then the above test of the result could become:

If IsObject(found) Then
  '....

The above shows illustrates the benefits of returning a collection from the FindByName method (the same is the case with FindByValue method). The same method call is good for the both cases - one item found and many items found.

See also FindByValue method. 

Applies to: VarDictionary