ICommandPrepare::Prepare

OLE DB Programmer's Reference

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 Appendix C: OLE DB 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.

See Also