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.

See Also

Reference

ICommand::Execute

ICommandPrepare::Unprepare

ICommandWithParameters::SetParameterInfo