ICommandText::SetCommandText

Sets the command text, replacing the existing command text.

HRESULT SetCommandText (
   REFGUID         rguidDialect,
   LPCOLESTR   pwszCommand);

Parameters

rguidDialect

[in]
A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. For a complete description of dialects, see GetCommandText.

pwszCommand

[in]
A pointer to the text of the command.

If *pwszCommand is an empty string ("") or pwszCommand is a null pointer, the current command text is cleared and the command is put in an unprepared state. Any properties that have been set on the command are unaffected; that is, they retain their current values. Methods that require a command, such as ICommand::Execute, ICommandPrepare::Prepare, or IColumnsInfo::GetColumnsInfo, will return DB_E_NOCOMMAND until a new command text is set.

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

DB_E_DIALECTNOTSUPPORTED
The provider did not support the dialect specified in rguidDialect.

DB_E_OBJECTOPEN
A rowset was open on the command.

Comments

A command object contains a single text command, usually an SQL statement. The new command text is copied into the command object; thus, the consumer can delete the original text without affecting the command object. All meaningful error checking, such as syntax checking and parsing, is deferred until ICommandPrepare::Prepare or ICommand::Execute is called. SetCommandText only verifies that the command text can be copied into the command object's space.

If the text of a prepared or unprepared command is overwritten with new command text, by calling SetCommandText, the command object is left in an unprepared state.

SetCommandText does not alter the value of any properties. That is, ICommandProperties::GetProperties returns the same value for a property regardless of whether it is called before or after SetCommandText and whether SetCommandText succeeded or failed. Furthermore, setting the command text does not reset parameter information set through SetParameterInfo.