ICommandTree::FreeCommandTree

[This is preliminary documentation and subject to change.]

Walks a command tree and deallocates all DBCOMMANDTREE node structures as well as all variants in those structures, and finally sets the root pointer to a null pointer.

HRESULT FreeCommandTree(
  DBCOMMANDTREE ** ppRoot
);
 

Parameters

ppRoot

[in] Address of a variable that receives the pointer to the root of the command tree on successful exit.

Return Value

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

ppRoot was a null pointer.

DB_E_CANNOTFREE

The consumer called SetCommandTree with fCopy = FALSE, therefore relinquishing ownership of the memory to the provider.

Comments

FreeCommandTree can be used by a consumer to free their copy of the command tree constructed locally or obtained by GetCommandTree. It does not free the copy of the tree owned by the command object. When a consumer calls SetCommandTree with fCopy = FALSE, the consumer relinquishes ownership of the memory to the provider. Therefore, if the consumer calls FreeCommandTree after having called SetCommandTree with fCopy = FALSE, FreeCommandTree returns an error code DB_E_CANNOTFREE meaning the consumer does not have ownership of the tree to free it.