ICommandTree::GetCommandTree

[This is preliminary documentation and subject to change.]

Echoes the current command as a tree, including all post-processing operations added.

HRESULT GetCommandTree(
  DBCOMMANDTREE ** ppRoot 
);
 

Parameters

ppRoot

[out] The command object allocates memory for the command tree and returns the address to this memory; the consumer releases this memory with IMalloc::Free, one node at a time, when it no longer needs the command tree. The provider sets ppRoot to a null pointer if an error occurs.

Return Value

S_OK

The method succeeded.

DB_S_ERRORSINTREE

The provider discovered non-fatal errors in the command text previously set by ICommandText::SetCommandText while building the command tree.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

ppRoot was a null pointer.

E_OUTOFMEMORY

The provider was unable to allocate sufficient memory in which to return the command tree.

DB_E_CANTTRANSLATE

The provider cannot represent the command text previously set by ICommandText::SetCommandText as a tree.

Comments

The returned tree reflects exactly the command set by the last invocation of ICommandTree::SetCommandTree or ICommandText::SetCommandText, as modified by subsequent calls to IQuery::AddPostProcessing. If the command is stored as a tree, the returned tree is a copy of the one stored in the command object. If a tree node was passed in with text, it is also echoed as text. If the command is stored as text, 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. For example, if the tree can be represented as a DBOP_SQL_select node, and the provider supports that node, it must be returned in that format. However, if the tree cannot be represented as a DBOP_SQL_select node, but can be represented in a non-trivial command tree (that is, other than the DBOP_text_command), the provider must return it as that non-trivial tree; the provider may only return the tree as the trivial DBOP_text_command node if that is the only command node it supports; otherwise, it must return a valid, non-trivial navigable tree or return DB_E_CANTTRANSLATE if the text cannot be represented in such a tree. The provider should not do any unnecessary validation, such as binding, at this time, but if in the course of parsing it discovers non-fatal errors in building the tree it should put the error information in the tree and return DB_S_ERRORSINTREE.

This method does not reveal a provider's internal, optimized translation (which may be different from a DBCOMMANDTREE structure) of text to (non-text) tree operations.

The returned tree includes the markings set by the validation methods invoked so far (ICommandValidate::ValidateSyntax and ICommandValidate::ValidateCompletely).