7.7.10.Rowset MetaData
IRowsetInfo enables consumers to query the properties of a rowset through IRowsetInfo::GetProperties. Consumers can get an interface pointer to the object that created the rowset by calling IRowsetInfo::GetSpecification.
IRowset provides methods for fetching rows sequentially, exposing data from those rows to consumers, and managing the rows in the rowset. IRowset contains five methods: AddRefRows, GetData, GetNextRows, ReleaseRows, and RestartPosition.
Incrementing the Reference Count on Row Handles
AddRefRows increments the reference count on the row handles supplied by the caller. AddRefRows enables consumers to make multiple references to a row in the data cache.
Populating the Data Cache
IRowset::GetNextRows gets the next sequence of rows from the datasource and places them in the rowset's data cache. When GetNextRows is first called, it starts at the beginning of the rowset. After that, GetNextRows maintains information about its current position so it can proceed forward from that position. The OpenLink provider also provides support for IRowset::RestartPosition, which repositions the next fetch position to the beginning of the rowset.
Retrieving Data from the Data Cache
IRowset::GetData enables consumers to retrieve data from the data cache. GetData uses the bindings in the accessor to determine how the data should be returned and what data should be returned to the consumer's buffer. Then, GetData converts the data in the cache to the type specified in the binding and transfers the converted data to the consumer.
Decrementing the Reference Count on Row Handles
IRowset::ReleaseRows decrements the reference count on the rows specified. A consumer must call ReleaseRows once for each time a row was fetched or each time the row had its reference count incremented by AddRefRow. When the reference count reaches zero, the row is released if the rowset is in immediate update mode.
In providers that implement IRowsetUpdate, rows are released unless there are pending changes on the row. The OpenLink provider does not implement this interface; the OpenLink provider always performs rowset updates in immediate mode, which means that changes are immediately applied to the underlying data source. Therefore, the OpenLink provider does not recognize any changes as pending.
Returning to the First Row of the Rowset
IRowset::RestartPosition moves the next fetch position used by GetNextRows to the first row of the rowset.
Updating Rows
IRowsetChange enables consumers to change the values of columns in a row of data. If the consumer wants to change the data, it must first construct an accessor for the columns to be changed. IRowsetChange contains three methods: DeleteRows, InsertRow, and SetData.
Deleting Rows
IRowsetChange also enables consumers to delete rows from the rowset. IRowsetChange::DeleteRows deletes rows from the rowset and are applied to the data source immediately.
IRowsetChange
IRowsetChange is implemented using the UDBC/ODBC function SQLSetPos. It therefore can be exposed only when the underlying datasource supports SQLSetPos. Newly inserted rows cannot be updated.