ICommandText::GetCommandText

Returns the text command set by the last call to SetCommandText.

HRESULT GetCommandText (
   GUID *            pguidDialect,
   LPOLESTR *   ppwszCommand);

Parameters

pguidDialect

[in/out]
A pointer to memory containing a GUID that specifies the syntax and general rules for parsing the command text—that is, the dialect that will be used by the provider to interpret the statement. This is generally the dialect specified in SetCommandText. However, if DBGUID_DEFAULT is specified in SetCommandText, the provider returns the particular dialect that it will use to interpret the statement. If the provider determines between multiple dialects at execution time for a command that has been set with DBGUID_DEFAULT, or if the provider is returning some provider-specific syntax that may be different from the command set in SetCommandText, it returns DBGUID_DEFAULT. Providers can define GUIDs for their own dialects.

For more information about dialects, see "Using Commands" in Chapter 3, "Commands."

If GetCommandText returns an error, *pguidDialect is set to DB_NULLGUID.

ppwszCommand

[out]
A pointer to memory in which to return the command text. The command object allocates memory for the command text and returns the address to this memory. The consumer releases this memory with IMalloc::Free when it no longer needs the text. If GetCommandText returns an error, *ppwszCommand is set to a null pointer.

Return Code

S_OK
The method succeeded.

DB_S_DIALECTIGNORED
The method succeeded, but the input value of pguidDialect was ignored. The text is returned in the dialect specified in SetCommandText or the dialect that makes the most sense to the provider. The value returned in *pguidDialect represents that dialect.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
ppwszCommand was a null pointer.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return the command text.

DB_E_NOCOMMAND
No command text was currently set on the command object.

See Also

ICommandText::SetCommandText

Comments

The GUID returned in GetCommandText is the dialect that will be used by the provider to interpret the statement. This is generally the dialect specified in SetCommandText. However, if DBGUID_DEFAULT is specified in SetCommandText, the provider should return the particular dialect that it will use to interpret the statement. If the provider determines between multiple dialects at execution time for a command that has been set with DBGUID_DEFAULT, or if the provider is returning some provider-specific syntax that may be different from the command set in SetCommandText, it returns DBGUID_DEFAULT.