MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

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 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::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.

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.