Repositions the next fetch position used by GetNextRows or FindNextRow to its initial position; that is, its position when the rowset was first created.
HRESULT RestartPosition (
HCHAPTER hChapter);
Parameters
hChapter
[in]
The chapter handle. For nonchaptered rowsets, hChapter is ignored.
Return Code
S_OK
The method succeeded. The provider did not have to reexecute the command, either because the rowset supports positioning on the first row without reexecuting the command or because the rowset is already positioned on the first row.
DB_S_COLUMNSCHANGED
The order of the columns was not specified in the object that created the rowset. The provider had to reexecute the command to reposition the next fetch position to its initial position, and the order of the columns changed.
The provider had to reexecute the command to reposition the next fetch position to its initial position, and columns were added or removed from the rowset. This is generally due to a change in the underlying schema and is extremely uncommon.
This return code takes precedence over DB_S_COMMANDREEXECUTED. That is, if the conditions described here and in those described in DB_S_COMMANDREEXECUTED both occur, the provider returns this code. A change to the columns generally implies that the command was reexecuted.
DB_S_COMMANDREEXECUTED
The command associated with this rowset was reexecuted. If the properties DBPROP_OWNINSERT and DBPROP_OWNUPDATEDELETE are VARIANT_TRUE, then the consumer will see its own changes. If the properties DBPROP_OWNINSERT or DBPROP_OWNUPDATEDELETE are VARIANT_FALSE, then the rowset may see its changes. The order of the columns remains unchanged.
E_FAIL
A provider-specific error occurred.
E_UNEXPECTED
ITransaction::Commit or ITransaction::Abort was called and the object is in a zombie state.
DB_E_BADCHAPTER
The rowset was chaptered and hChapter was invalid.
The rowset was single-chaptered and the specified chapter was not the currently open chapter. The consumer must use the currently open chapter or release the currently open chapter before specifying a new chapter.
DB_E_CANCELED
RestartPosition was canceled during notification. The next fetch position remains unmodified.
DB_E_CANNOTRESTART
The rowset was built over a live data stream (for example, a stock feed) and the position cannot be restarted.
DB_E_NOTREENTRANT
The provider called a method from IRowsetNotify in the consumer and the method has not yet returned.
DB_E_ROWSNOTRELEASED
The provider requires release of existing rows before restarting because the Rowset will be regenerated. This may be required even if the provider supports a value of VARIANT_TRUE for DBPROP_CANHOLDROWS. For more information, see DBPROP_CANHOLDROWS and DPPROP_QUICKRESTART in "Rowset Properties" in Appendix C.
DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to reposition the next fetch position.
Comments
For information about the next fetch position when the rowset is first created, see GetNextRows.
If the underlying command contains output parameters, RestartPosition should not reset those parameters.
If the rowset was generated as a result of a procedure call, and the rowset is forward-only, the procedure may be reexecuted in order to satisfy the call to RestartPosition. This may cause other side effects. Additionally, if the stored procedure has been changed, the rowset may have a different schema. If the rowset is able to restart the next fetch position without reexecuting the procedure, RestartPosition should not reexecute it.
How expensive RestartPosition is depends on the provider, the rowset characteristics, and the tables underlying the rowset. If the rowset supports IRowsetLocate, then RestartPosition is always an inexpensive operation.
If the rowset is sequential, then RestartPosition might require reexecution of the underlying command. For some providers, this is always the case. For other providers, a rule of thumb is that rowsets built from a single table are not expensive to restart, but rowsets built by joining two or more tables are expensive to restart. If the provider reexecutes the command to restart the next fetch position, then the new rowset might return a different set of rows, differently ordered columns, and, in extreme cases, a different set of columns. Reexecution of a command by RestartPosition does not reinherit accessors.
A provider that reports DBPROP_QUICKRESTART as VARIANT_FALSE may require that all existing row handles are released prior to successfully processing a call to RestartPosition.
A consumer can determine whether a provider can quickly restart the next fetch position by attempting to set DBPROP_QUICKRESTART to VARIANT_TRUE. Setting this property to VARIANT_TRUE does not guarantee that the rowset can be quickly restarted because the provider is not required to honor the property. This behavior is necessary because the provider cannot evaluate the command at the time the property is set. For example, the consumer can set DBPROP_QUICKRESTART to VARIANT_TRUE and then change the command text.
In implementations that require reexecution of a command to reposition the next fetch position to its initial position, the provider is responsible for caching all parameters required by the command.
If RestartPosition returns DB_S_COLUMNSCHANGED and the consumer subsequently calls methods in IColumnsInfo or IColumnsRowset, these methods must reflect the new metadata. Existing rowset accessors are not updated to reflect the new metadata. That is, IAccessor::GetBindings returns exactly the same information it would have returned before RestartPosition was called. If such accessors are subsequently used, such as in a call to GetData, the provider must revalidate them. If none of the columns bound by the accessor have changed, the accessor can be used successfully. If any of the columns have changed, the appropriate error or warning is returned.
See Also