Asynchronous Rowset Population

OLE DB Programmer's Reference

Consumers wishing to asynchronously populate a rowset set the DBPROPVAL_ASYNCH_SEQUENTIAL or DBPROPVAL_ASYNCH_RANDOM bits of the DBPROP_ROWSET_ASYNCH property prior to opening the rowset.

During the DBASYNCHPHASE_POPULATION phase, even though the rows are not fully populated, the rowset itself is fully initialized; that is, all interfaces supported by the rowset are available and fully functional (although the set of rows returned may be restricted).

An asynchronously populated rowset is distinct from a lazily populated rowset. A lazily populated rowset may return a rowset prior to completely populating the rows, but methods that return rows wait, if necessary, in order to return the requested rows. Therefore, a lazily populated rowset appears as a synchronously populated rowset to the consumer. In contrast, an asynchronously populated rowset returns from a request to retrieve rows immediately with as many of the requested rows as are available at the moment. If fewer than the requested number of rows are available at the time of the call, the method returns DB_S_ENDOFROWSET even though additional rows may appear later. The consumer must request notifications or call IDBAsynchStatus to determine when population is complete. Unless the consumer explicitly requests asynchronous population, the provider must behave as if the rowset is fully populated upon creation. The method used to request rows waits to return until the requested number of hRows are obtained or the end of the rowset is reached.

Asynchronously populated rowsets may be sequentially asynchronously populated, if rows are always appended to the end of the rowset, or randomly asynchronously populated, if new rows can be inserted randomly within the rowset.

Sequentially asynchronously populated rowsets call IDBAsynchNotify::OnProgress to signal the addition of new rows to the end of the rowset as a result of asynchronous population. Randomly asynchronously populated rowsets call IRowsetNotify::OnRowChange with DBREASON_ROW_ASYNCHINSERT to signal the addition of new rows as a result of asynchronous population.

1998-2001 Microsoft Corporation. All rights reserved.