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

ICommandPrepare::Prepare

Validates and optimizes the current command.

HRESULT Prepare (
   ULONG cExpectedRuns);

Parameters

cExpectedRuns

[in]
Using this parameter, the consumer can indicate how often the command execution plan, which is produced by ICommandPrepare::Prepare, will be used—that is, how often the command is likely to be executed without renewed optimization. This guides the optimizer in determining trade-offs between search effort and run-time processing effort. A value of zero indicates that the consumer is unable to provide an estimate and leaves it to the optimizer to choose a default value.

Return Code

S_OK

The method succeeded.

DB_S_ERRORSOCCURRED

The command was prepared but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. The consumer calls ICommandProperties::GetProperties to determine which properties were set.

E_FAIL

A provider-specific error occurred.

E_OUTOFMEMORY

The provider ran out of memory while preparing the command.

DB_E_ABORTLIMITREACHED

Preparation has been aborted because a resource limit has been reached. For example, the preparation timed out.

DB_E_ERRORSINCOMMAND

The command text contained one or more errors. Providers should use OLE DB error objects to return details about the errors.

DB_E_ERRORSOCCURRED

The command was not prepared because one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED—were not set. The consumer calls ICommandProperties::GetProperties to determine which properties were not set.

DB_E_NOCOMMAND

No command text was currently set on the command object.

DB_E_NOTABLE

The specific table or view does not exist in the data store.

DB_E_OBJECTOPEN

A rowset was open on the command.

DB_SEC_E_PERMISSIONDENIED

The consumer did not have sufficient permission to prepare the command.

Comments

Although they are not required to do so, consumers should set any properties before calling ICommandPrepare::Prepare because these properties might be relevant to preparing the command.

If ICommandPrepare::Prepare is called redundantly, the provider determines whether command optimization is reinvoked; the provider returns S_OK.

If ICommandPrepare::Prepare returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer can immediately call ICommandProperties::GetProperties with the DBPPROPSET_PROPERTIESINERROR property set to return the properties that could not be set. For more information, see "Property Sets" in Chapter 14, “Properties.”

When a call to ICommandProperties::SetProperties follows a call to ICommandPrepare::Prepare, the command should remain prepared even if the provider must re-prepare the command.