ICommandText::SetCommandText

OLE DB Programmer's Reference

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

See Also

ICommand::Execute | ICommandPrepare::Prepare | ICommandText::GetCommandText | ICommandWithParameters::SetParameterInfo | ICommandStream::SetCommandStream

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