Using Commands

Before a consumer can use a command, it must determine whether commands are supported by the session. To do this, the consumer calls QueryInterface for IDBCreateCommand on the session object. If this interface is exposed, the provider supports commands. To create a command, the consumer then calls IDBCreateCommand::CreateCommand on the session. A consumer can use a single session to create multiple commands.

When the command is first created, it does not contain command text. The consumer sets the command text with ICommandText::SetCommandText. Because the text command syntax is provider-specific, the consumer passes the GUID of the syntax to use. This can be one of the following dialect values, or it can be a provider-specific value specifying some provider specific syntax.

Dialect value	Meaning
DBGUID_DEFAULT	The command text is to be interpreted according to the provider's default grammar. If the command text is an SQL statement and the provider supports SQL, the provider must recognize and process the command text as an SQL statement, even if the provider's default grammar is not SQL. This is required for maximum interoperability.
DBGUID_SQL	The command text is to be interpreted according to a superset of SQL syntax rules. To determine the level of SQL syntax supported by a provider, a consumer calls IDBProperties::GetProperties for the DBPROP_SQLSUPPORT property. Providers reporting this syntax are free to use extensions to SQL, or any subset of SQL according to their reported level of support, but must comply with the rules defined in SQL for any supported syntax defined in that specification. Note DBGUID_SQL was added in OLE DB version 1.5 and is not supported in earlier providers. Consumers should use DBGUID_SQL only when calling a version 1.5 or greater provider that supports DBPROP_SQLSUPPORT. In most cases, unless the provider is trying to distinguish between different dialects, the consumer can just pass DBGUID_DEFAULT. (See above for DBGUID_DEFAULT.)

To execute the command, the consumer calls ICommand::Execute. If the command text specifies a rowset, such as an SQL SELECT statement, Execute creates an instance of the rowset and returns an interface pointer to it.

By calling ICommandProperties::SetProperties before executing a command that creates a rowset, the consumer can request properties that control execution of the command and affect the behavior of the resulting rowset (such as the interfaces to expose). For more information, see Creating a Rowset with a Command. The consumer can also get information about the columns of the rowset by calling IColumnsInfo::GetColumnInfo, which all providers must support, or IColumnsRowset::GetColumnsRowset, which providers may support, on the command.

Before calling GetColumnInfo or GetColumnsRowset, the consumer must set the command text and, if the provider supports command preparation, prepare the command object.

If a command is to be executed multiple times with the same text command or if the consumer needs information about the rowset it will create, the consumer can prepare the command by calling ICommandPrepare::Prepare. This is equivalent to compiling the command.

Prepared commands can be used with parameters, which are variables in the text command. For example, if the provider supports SQL, the consumer might prepare and repeatedly execute the following parameterized SQL statement to update the salaries of a number of employees:

UPDATE Employees SET (Salary = ?) WHERE EmployeeID = ?

Support for parameterized commands is optional. Providers that support them must expose ICommandWithParameters on command objects. To use parameters, the consumer first describes the parameters to the provider by calling ICommandWithParameters::SetParameterInfo. Some providers themselves can describe parameters and do not need consumers to call SetParameterInfo. The consumer then creates an accessor that specifies the structure of a buffer and places parameter values in this buffer. Finally, it passes the handle of the accessor and a pointer to the buffer to ICommand::Execute. On later calls to Execute, the consumer simply places new parameter values in the buffer and calls ICommand::Execute with the accessor handle and buffer pointer. For more information, see Getting and Setting Data.