Command States

OLE DB Programmer's Reference

Commands can be in one of four states:

  • Initial—No command text is set. A command is in this state after IDBCreateCommand::CreateCommand is called.
  • Unprepared—The command text is set but the command is not prepared. A command is in this state after ICommandText::SetCommandText is called.
  • Prepared—The command text is set and the command is prepared. A command is in this state after ICommandPrepare::Prepare is called.
  • Executed—The command text is executed. A command is in this state after ICommand::Execute is called.

The following table lists each state and shows the value returned by each method in a command interface when it is called in that state. This table uses the following abbreviations:

OK = S_OK
NC = DB_E_NOCOMMAND
NP = DB_E_NOTPREPARED
OO = DB_E_OPENOBJECT

Method Initial Unprepared Prepared Executed
IColumnsInfo::GetColumnInfo NC OK (ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

OK OK (ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

IColumnsInfo::MapColumnIDs NC OK (ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

OK OK

(ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

IColumnsRowset::GetAvailableColumns NC OK (ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

OK OK

(ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

IColumnsRowset::GetColumnsRowset NC OK (ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

OK OK

(ICommandPrepare is not supported)

- or -

NP (ICommandPrepare is supported and the necessary information is not available to the command object)

ICommand::Cancel OK OK OK OK
ICommand::Execute NC OK OK OK
ICommand::GetDBSession OK OK OK OK
ICommandPrepare::Prepare NC OK OK OK (Execute did not create a rowset)

- or -

OO (Execute created a rowset, and the rowset is still open)

ICommandPrepare::Unprepare OK OK OK OK (Execute did not create a rowset)

- or -

OO (Execute created a rowset, and the rowset is still open)

ICommandProperties::GetProperties OK OK OK OK
ICommandProperties::SetProperties OK OK OK OK (Execute did not create a rowset)

- or -

OO (Execute created a rowset, and the rowset is still open)

ICommandText::GetCommandText NC OK OK OK
ICommandText::SetCommandText OK OK OK OK (Execute did not create a rowset)

- or -

OO (Execute created a rowset, and the rowset is still open)

ICommandWithParameters::GetParameterInfo OK (SetParameterInfo has been called)

- or -

NC (SetParameterInfo has not been called)

OK (SetParameterInfo has been called)

- or -

NP (ICommandPrepare is supported, and SetParameterInfo has not been called)

OK OK
ICommandWithParameters::MapParameterNames OK (SetParameterInfo has been called)

- or -

NC (SetParameterInfo has not been called)

OK (SetParameterInfo has been called)

- or -

NP (ICommandPrepare is supported, and SetParameterInfo has not been called)

OK OK
ICommandWithParameters::SetParameterInfo OK OK OK OK (Execute did not create a rowset)

- or -

OO (Execute created a rowset, and the rowset is still open)

The following figure illustrates the state transition for a command where the command text is set to an empty string and a non-empty string. Any call to ICommandText::SetCommandText with an empty command text must terminate in the Initial state, which is defined as command text not set. The only way to transition from Initial to Unprepared is to call ICommandText::SetCommandText with a non-empty command text. ICommand::Execute or ICommand::Prepare is called to transition to the Execute or Prepared states, respectively. In the Execute or Prepared states, calling ICommandText::SetCommandText with a non-empty command text returns the command to the Unprepared state, where the same call with a non-empty command text returns the command to the Unprepared state by using ICommandPrepare::Unprepare.

1998-2001 Microsoft Corporation. All rights reserved.



Microsoft Ole Db 2.0 Programmer's Reference and Data Access SDK
Microsoft OLE DB 2.0 Programmers Reference and Data Access SDK (Microsoft Professional Editions)
ISBN: 0735605904
EAN: 2147483647
Year: 1998
Pages: 1083

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net