ICommandPrepare::Prepare
Validates and optimizes the current command.
Syntax
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.