IRowset::RestartPosition

Repositions the next fetch position used by IRowset::GetNextRows or IRowsetFind::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 designating the rows on which to reposition. For nonchaptered rowsets, the caller must set hChapter to DB_NULL_HCHAPTER. For chaptered rowsets, DB_NULL_HCHAPTER designates the entire rowset.

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, the consumer will see its own changes. If the properties DBPROP_OWNINSERT or DBPROP_OWNUPDATEDELETE are VARIANT_FALSE, 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

IRowset::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 IRowsetNofity in the consumer that had not yet returned, and the provider does not support reentrancy in this method.

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 IRowset::GetNextRows.

If the underlying command contains output parameters, IRowset::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 to satisfy the call to IRowset::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, IRowset::RestartPosition should not reexecute it.

How expensive IRowset::RestartPosition is depends on the provider, the rowset characteristics, and the tables underlying the rowset. If the rowset supports IRowsetLocate, IRowset::RestartPosition is always an inexpensive operation.

If the rowset is sequential, IRowset::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, 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 IRowset::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 IRowset::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 IRowset::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 IRowset::RestartPosition was called. If such accessors are subsequently used, such as in a call to IRowset::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.