ICommandTree : ICommand

[This is preliminary documentation and subject to change.]

This 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 ICommandText.

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 SetCommandTree or ICommandText::SetCommandText, it replaces the command object's command, regardless of 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, GetCommandText must be able to convert a command tree into command text, and GetCommandTree 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 fuller representation, the command tree can consist of a single text node.

Most providers will not permit setting a new command tree while there is a rowset open that was created by the command object (and thus directly reflects the result table of the current command tree). Some providers, however, may support this operation even while a rowset is open. If so, the new command tree's output schema (set of columns) must include all column for which there currently are accessors, and all rowsets' accessors remain valid. Currently open rowsets must be modified dynamically to reflect the new command tree's result table. HROWs remain valid, meaning that a new sort order or a new selection predicate are not reflected for those rows, and that all accessors that may be 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.