A bug affecting the .NET (C# and VB.NET) implementations of the Chilkat.Xml.Search* methods was introduced in v9.4.1. The problem has to do with passing a null (in C#) or Nothing (in VB.NET) for the first argument in the Chilkat.Xml.Search* methods. Passing a null should be a valid and common practice — it means to begin searching at the root node of the XML document.
In v9.4.1, the null is incorrectly seen as an input error and the Xml.Search* method immediately returns a failed status. The solution is to pass a reference to the root node of the XML document. For example:
Chilkat.Xml xmlFound = xmlRoot.SearchForTag(xmlRoot,"xyz");
Chilkat.Xml xmlFound = xmlSomeNode.SearchForTag(xmlSomeNode.GetRoot(),"xyz");
This post clarifies the meaning of “child”. An XML node may have 0 or more child nodes. A child node is a direct descendent of the parent (i.e. it is one level below the parent node).
Methods such as NumChildrenHavingTag will return the number of direct descendents (i.e. nodes that are exactly one level below the calling node) that match the specified requirements.
For more information, see this XML Child Tutorial
The Chilkat XML component library (for C#, VB.NET, ASP.NET, ASP, VB6, FoxPro, Delphi, C++, C, Perl, Ruby, Python, Java, etc.) has a number of Search* methods. These methods search for a node in the XML document matching a specific criteria. For example, SearchForTag searches for the 1st node that has a tag with a specific value.
The general form of a Search* method is this:
foundNode = subTreeRoot.SearchMethod(startNode, ...)
The part of the XML document that is searched is the sub-tree rooted at the calling node (subTreeRoot). The method does a breadth-first traversal of the XML sub-tree (see http://en.wikipedia.org/wiki/Breadth-first_search for more information about breadth-first traversal). The startNode indicates where the search should begin in the traversal. Any nodes found matching the requirement(s) are ignored until the startNode is traversed. To search the entire sub-tree, pass a NULL reference in startNode. If a matching node is found, a reference (or pointer) to it is returned, otherwise a NULL is returned.
A Chilkat XML object represents a single node within an XML document. The “root” is the topmost node in the XML document tree. As long as at least a single reference to a node (anywhere in the tree) exists, the entire XML tree remains in memory.
Typically, an XML API returns a new node object when navigating. Chilkat XML does this also. For example:
// Get the 1st child:
Chilkat.Xml childNode = xmlDoc.GetChild(0);
For efficiency, Chilkat provides alternate methods such that instead of returning a new object, the internal pointer of the Chilkat XML object is updated. This can vastly reduce the proliferation of objects that might need to be allocated/deallocated or garbage collected. For example:
// xmlDoc now references the 1st child.
// xmlDoc is now back to where it began.
// Regardless of the location of an XML object in the tree,
// you may always return to the document root like this: