ICommandText::SetCommandText
Sets the command text, replacing the existing command text.
Syntax
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 (and command stream object, if it exists) is cleared and the command is put in an initial 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::GetColumnInfo, 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.DB_SEC_E_SAFEMODE_DENIED
The provider was called within a safe mode or context, and the command text specified a FROM SCOPE= clause with an unsafe URL.
Comments
A command object contains a single text command, usually an SQL statement. The new command text is copied into the command object; therefore, 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. ICommandText::SetCommandText verifies only 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 ICommandText::SetCommandText, the command object is left in an unprepared state.
ICommandText::SetCommandText does not alter the value of any properties. That is, ICommandProperties::GetProperties returns the same value for a property whether or not it is called before or after ICommandText::SetCommandText and whether or not SetCommandText succeeded or failed. Furthermore, setting the command text does not reset parameter information set through ICommandWithParameters::SetParameterInfo.