DBCOMMANDTREE
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 DBCOMMANDTREE structure is the primary data structure used to represent any node in an OLE DB command tree, as described in the Data Manipulation Operators and Data Definition Operators section of this reference. This structure is used for each data manipulation language (DML) or data definition language (DDL) node in an OLE DB command tree.
typedef struct tagDBCOMMANDTREE {
DBCOMMANDOP op; // Operator identifier (2 bytes)
WORD wKind; // Discriminator for the following union (2 bytes)
struct tagDBCOMMANDTREE * pctFirstChild; // Pointer to first child (4 bytes)
struct tagDBCOMMANDTREE * pctNextSibling; // Pointer to sibling (4 bytes)
union { // Union directly represents fields that fit within 8 bytes.
// Comments list DBVALUEKIND and DBTYPE corresponding to each field.
__int64 llValue; // DBVALUEKIND_I8 (DBTYPE_I8)
unsigned __int64 ullValue; // DBVALUEKIND_UI8 (DBTYPE_UI8)
BOOL fValue; // DBVALUEKIND_BOOL (DBTYPE_BOOL)
unsigned char uchValue; // DBVALUEKIND_UI1 (DBTYPE_UI1)
signed char schValue; // DBVALUEKIND_I1 (DBTYPE_I1)
unsigned short usValue; // DBVALUEKIND_UI2 (DBTYPE_UI2)
short sValue; // DBVALUEKIND_I2 (DBTYPE_I2)
LPOLESTR pwszValue; // DBVALUEKIND_WSTR (DBTYPE_WSTR)
LONG lValue; // DBVALUEKIND_I4 (DBTYPE_I4)
ULONG ulValue; // DBVALUEKIND_UI4 (DBTYPE_UI4)
float flValue; // DBVALUEKIND_R4 (DBTYPE_R4)
double dblValue; // DBVALUEKIND_R8 (DBTYPE_R8)
CY cyValue; // DBVALUEKIND_CY (DBTYPE_CY)
DATE dateValue; // DBVALUEKIND_DATE (DBTYPE_DATE)
DBDATE dbdateValue; // DBVALUEKIND_DBDATE (DBTYPE_DBDATE)
DBTIME dbtimeValue; // DBVALUEKIND_DBTIME (DBTYPE_DBTIME)
SCODE scodeValue; // DBVALUEKIND_ERROR (DBTYPE_ERROR)
BSTR * pbstrValue; // DBVALUEKIND_BSTR (DBTYPE_BSTR)
ICommand * pCommand; // DBVALUEKIND_COMMAND (DBTYPE_IUNKNOWN)
IDispatch * pDispatch; // DBVALUEKIND_IDISPATCH (DBTYPE_IDISPATCH)
IMoniker * pMoniker; // DBVALUEKIND_MONIKER (DBTYPE_MONIKER)
IRowset * pRowset; // DBVALUEKIND_ROWSET (DBTYPE_ROWSET)
IUnknown * pUnknown; // DBVALUEKIND_IUNKNOWN (DBTYPE_IUNKNOWN)
DBBYGUID * pdbbygdValue; // DBVALUEKIND_BYGUID
DBCOLUMNDESC * pcoldescValue; // DBVALUEKIND_COLDESC
DBID * pdbidValue; // DBVALUEKIND_ID
DBLIKE * pdblikeValue; // DBVALUEKIND_LIKE
DBCONTENT * pdbcntntValue; // DBVALUEKIND_CONTENT
DBCONTENTSCOPE * pdbcntntscpValue; // DBVALUEKIND_CONTENTSCOPE
DBCONTENTTABLE * pdbcntnttblValue; // DBVALUEKIND_CONTENTTABLE
DBCONTENTVECTOR * pdbcntntvcValue; // DBVALUEKIND_CONTENTVECTOR
DBCONTENTPROXIMITY * pdbcntntproxValue;// DBVALUEKIND_CONTENTPROXIMITY
DBGROUPINFO * pdbgrpinfValue; // DBVALUEKIND_GROUPINFO
DBPARAMETER * pdbparamValue; // DBVALUEKIND_PARAMETER
DBPROPSET * pdbpropValue; // DBVALUEKIND_PROPERTY
DBSETFUNC * pdbstfncValue; // DBVALUEKIND_SETFUNC
DBSORTINFO * pdbsrtinfValue; // DBVALUEKIND_SORTINFO
DBTEXT * pdbtxtValue; // DBVALUEKIND_TEXT
DBVECTOR * pdbvectorValue; // DBVALUEKIND_VECTOR | *
SAFEARRAY * parrayValue; // DBVALUEKIND_ARRAY | *
VARIANT * pvarValue; // DBVALUEKIND_VARIANT (DBTYPE_VARIANT)
GUID * pGuid; // DBVALUEKIND_GUID (DBTYPE_GUID)
BYTE * pbValue; // DBVALUEKIND_BYTES (DBTYPE_BYTES)
char * pzValue; // DBVALUEKIND_STR (DBTYPE_STR)
DB_NUMERIC * pdbnValue; // DBVALUEKIND_NUMERIC (DBTYPE_NUMERIC)
DBTIMESTAMP * pdbtsValue; // DBVALUEKIND_DBTIMESTAMP (DBTYPE_DBTIMESTAMP)
void * pvValue; // a generic DBVALUEKIND_BYREF
DBPROBABILISTIC * pdbprobValue; // DBVALUEKIND_PROBABILISTIC
DBRELEVANTDOC * pdbreldocValue; // DBVALUEKIND_RELEVANTDOCUMENT
} value;
HRESULT hrError; // Error indicator, details in Extended Error info (4 bytes)
} DBCOMMANDTREE;
Members
Term | Description |
---|---|
op |
A value of type DBCOMMANDOP from the DBCOMMANDOPENUM enumeration. It specifies an operator from the Data Manipulation Operators or the Data Definition Operators that defines the operation to take place on the associated field. |
wKind |
A value of type DBVALUEKIND from the DBVALUEKINDENUM enumerated type. It defines the data type of the associated union member so that the command processor knows how to interpret it. |
pctFirstChild |
A pointer to the DBCOMMANDTREE structure that represents the first child of this node of the command tree. |
pctNextSibling |
A pointer to the DBCOMMANDTREE structure that represents the next child of this node of the command tree. |
llvalue |
A union to hold the value for every data type supported by this OLE DB provider. For any union member data type that holds 8 bytes or less, the value itself is stored here. Otherwise, llvalue is a pwszValue member, a pointer to the data. A pwszValue member is a string; its interpretation is left to the provider. In other words, the consumer must understand the provider's method of name resolution. For command components "passed through" to another provider, it is left to the receiving provider to interpret the string. The pMoniker member is used for unresolved linked objects, in particular tables and functions. The pRowset member is used to reference a currently open rowset as input for a command. Most providers will fail if an IPersist method is invoked while the command tree refers to an open rowset. The pCommand member references another command object as input for a command. Most providers will fail if an IPersist method is invoked while the command tree refers to a command object that does not support monikers. |
Remarks
Many operations create a binding environment. For example, a DBOP_select operation has two inputs — a table and a Boolean predicate. (For more information on this operation, see Operators with Two Variants for Ordered and Non-Ordered Tables.) By virtue of the "select" operation, the table becomes the binding environment for the predicate. That means that the predicate may freely reference column names defined in the table. Note that not all bindings must come from the nearest table operation. For example, there might be multiple table operations within an "exist" expression, and any predicate may reference a column defined outside the "exist" expression. (In SQL, this is called a "correlated subquery.")
The typical size of a DBCOMMANDTREE structure for a node is 24 bytes. However, operators may store some specific information in the value field of the node. For programming convenience, the union field includes branches representing some common types that can fit within 8 bytes. Variable-length types are referenced via a pointer to the corresponding structure (such as DBTEXT). The discriminator for the union is of type WORD rather than DBVALUEKIND so that it is possible to store node values such as DBVALUEKIND_VECTOR | DBVALUEKIND_GUID, DBVALUEKIND_BYREF | DBVALUEKIND_UI4, or DBVALUEKIND_SAFEARRAY | DBVALUEKIND_I4.