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

ICommandText::GetCommandText

Returns the text command set by the last call to ICommandText::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 usually the dialect specified in ICommandText::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 must choose 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 ICommandText::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 ICommandText::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 ICommandText::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 ICommandText::SetCommandText or in 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.

Comments

The GUID returned in ICommandText::GetCommandText is the dialect that will be used by the provider to interpret the statement. This is usually the dialect specified in ICommandText::SetCommandText.

See Also

ICommandText::SetCommandText