Edit

ICommandTree interface (cmdtree.h)

  • Article

Note

Indexing Service is no longer supported as of Windows XP and is unavailable for use as of Windows 8. Instead, use Windows Search for client side search and Microsoft Search Server Express for server side search.

The ICommandTree interface is optional for providers that support commands. It contains methods for manipulating query trees. Providers that support command trees must also support specifying the same functionality through the ICommandText interface.

A command object can have only one command; that command can be in the form of a command tree (specified in ICommandTree) or a text command (specified in ICommandText). Thus, if a command is specified through the SetCommandTree or ICommandText::SetCommandText methods, it replaces the command of the command object, whether that command was in text or tree form. If a command is retrieved through GetCommandTree or ICommandText::GetCommandText, it is retrieved in the specified form, regardless of how the command was set. Thus, the GetCommandText method must be able to convert a command tree into command text, and the GetCommandTree method must be able to convert command text into a command tree. Note that in the latter conversion, the provider should return a navigable command tree representation of the text, which is not necessarily in optimized form. If the provider cannot create a full representation, the command tree can consist of a single text node.

Most providers will not permit an ICommandTree method to set a new command tree while there is a rowset open that was created by the command object. (The rowset directly reflects the result table of the original command tree). Some providers, however, may support this operation even while a rowset is open. If so, the output schema (set of columns) of the new command tree must include all columns for which there currently are accessors, and the accessors for all rowsets must remain valid. Open rowsets must be modified dynamically to reflect the result table of the new command tree. Return row handles (hRows) remain valid. This means that a new sort order or a new selection predicate are not effective for those rows, and that all accessors created after the command-tree modification will work with hRows obtained before the command-tree modification. If an error occurs while replacing or modifying a command tree with open rowsets, the command object, its command tree, the rowsets, hRows, and accessors remain unchanged.

Inheritance

The ICommandTree interface inherits from the IUnknown interface. ICommandTree also has these types of members:

Methods

The ICommandTree interface has these methods.

 
ICommandTree::FindErrorNodes

The ICommandTree::FindErrorNodes method traverses a command tree and returns an array of nodes with errors in them.
ICommandTree::FreeCommandTree

The ICommandTree::FreeCommandTree method traverses a command tree and deallocates all DBCOMMANDTREE node structures, as well as all variants in those structures. It then sets the root pointer to a NULL pointer.
ICommandTree::GetCommandTree

The ICommandTree::GetCommandTree method echoes the current command as a tree, including all post-processing operations that have been added.
ICommandTree::SetCommandTree

The ICommandTree::SetCommandTree method sets a command object's command tree, replacing the existing one or replacing a text command specified with the ICommandText interface.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header cmdtree.h