ICommandPrepare::Prepare

Validates and optimizes the current command.

HRESULT Prepare (
ULONGcExpectedRuns);

Parameters

cExpectedRuns

[in]
Using this parameter, the consumer can indicate how often the command execution plan, which is produced by Prepare, will be used; that is, how often the command is likely to be executed without renewed optimization. This guides the optimizer in determining tradeoffs 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_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 Prepare, because these properties might be relevant to preparing the command.

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

If 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 11.