Creating a Rowset with a Command

OLE DB Programmer's Reference

Providers that implement their own query or data definition language (DDL) can offer their consumers additional functionality by using a command.

To implement a query or DDL by using a command, a consumer should follow these steps:

1. Create a session. (For more information, see "Session Objects" in Chapter 2: Data Source and Session Objects.)
2. Call IDBCreateCommand::CreateCommand on the session to obtain a command object. When the command is first created, it does not contain command text. Set the command text by calling ICommandText::SetCommandText.

   The text command can be expressed in SQL or some other provider-specific language. For more information about creating command objects, see "Using Commands" in Chapter 3: Commands.

3. Call ICommandProperties::SetProperties to request properties that control execution of the command and affect the behavior of the resulting rowset (such as the interfaces to expose).
4. Call ICommand::Execute on the command.

   If the command is one that returns rows, such as an SQL SELECT statement, ICommand::Execute returns either a rowset or, if the consumer has requested IMultipleResults, a multiple results object. See the following illustration.

Creating a rowset through a command

The consumer calls ICommandProperties::SetProperties on the command object to request properties that control execution of the command and affect the behavior of the rowsets returned by ICommand::Execute. The most commonly requested properties are the interfaces the rowset must support.

All rowsets must support IRowset, IAccessor, IColumnsInfo, IRowsetInfo, and IConvertType. Providers can choose to return rowsets exposing additional interfaces if doing so does not break consumer code that is not expecting them. For example, IRowsetLocate can be exposed on the rowset even if the consumer does not request it, because this interface does not change the rowset's behavior. In contrast, IRowsetUpdate cannot safely be exposed if the consumer does not request it, because exposing IRowsetUpdate on the rowset changes the behavior of the rowset's IRowsetChange interface. In most cases, the riid parameter passed to ICommand::Execute is the IID for one of the interfaces listed in the TRowset cotype.

For a complete description of how consumers use properties, see Chapter 14: Properties.

1998-2001 Microsoft Corporation. All rights reserved.