description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: IRowsetLocateImpl Class |
IRowsetLocateImpl Class |
11/04/2016 |
|
|
a8aa3149-7ce8-4976-a680-2da193fd3234 |
Implements the OLE DB IRowsetLocate interface, which fetches arbitrary rows from a rowset.
template <
class T,
class RowsetInterface,
class RowClass = CSimpleRow,
class MapClass = CAtlMap < RowClass::KeyType, RowClass* >,
class BookmarkKeyType = LONG,
class BookmarkType = LONG,
class BookmarkMapClass = CAtlMap < RowClass::KeyType, RowClass* >>
class ATL_NO_VTABLE IRowsetLocateImpl : public IRowsetImpl<
T,
RowsetInterface,
RowClass,
MapClass>
T
A class derived from IRowsetLocateImpl
.
RowsetInterface
A class derived from IRowsetImpl
.
RowClass
The storage unit for the HROW
.
MapClass
The storage unit for all row handles held by the provider.
BookmarkKeyType
The type of the bookmark, such as a LONG or a string. Ordinary bookmarks must have a length of at least two bytes. (Single-byte length is reserved for the OLE DB standard bookmarksDBBMK_FIRST
, DBBMK_LAST
, and DBBMK_INVALID
.)
BookmarkType
The mapping mechanism for maintaining bookmark-to-data relationships.
BookmarkMapClass
The storage unit for all row handles held by the bookmark.
Header: atldb.h
Name | Description |
---|---|
Compare | Compares two bookmarks. |
GetRowsAt | Fetches rows starting with the row specified by an offset from a bookmark. |
GetRowsByBookmark | Fetches the rows that match the specified bookmarks. |
Hash | Returns hash values for the specified bookmarks. |
Name | Description |
---|---|
m_rgBookmarks | An array of bookmarks. |
IRowsetLocateImpl
is the OLE DB Templates implementation of the IRowsetLocate interface. IRowsetLocate
is used to fetch arbitrary rows from a rowset. A rowset that does not implement this interface is a sequential
rowset. When IRowsetLocate
is present on a rowset, column 0 is the bookmark for the rows; reading this column will obtain a bookmark value that can be used to reposition to the same row.
IRowsetLocateImpl
is used to implement bookmark support in providers. Bookmarks are placeholders (indices on a rowset) that enable the consumer to return quickly to a row, allowing high-speed access to data. The provider determines what bookmarks can uniquely identify a row. Using IRowsetLocateImpl
methods, you can compare bookmarks, fetch rows by offset, fetch rows by bookmark, and return hash values for bookmarks.
To support OLE DB bookmarks in a rowset, make the rowset inherit from this class.
For information on implementing bookmark support, see Provider Support for Bookmarks in the Visual C++ Programmer's Guide and Bookmarks in the OLE DB Programmer's Reference in the Platform SDK.
Compares two bookmarks.
STDMETHOD (Compare )(HCHAPTER /* hReserved */,
DBBKMARK cbBookmark1,
const BYTE* pBookmark1,
DBBKMARK cbBookmark2,
const BYTE* pBookmark2,
DBCOMPARE* pComparison);
See IRowsetLocate::Compare in the OLE DB Programmer's Reference.
Either of the bookmarks can be a standard OLE DB-defined standard bookmark (DBBMK_FIRST
, DBBMK_LAST
, or DBBMK_INVALID
). The value returned in pComparison
indicates the relationship between the two bookmarks:
-
DBCOMPARE_LT (
cbBookmark1
is beforecbBookmark2
.) -
DBCOMPARE_EQ (
cbBookmark1
is equal tocbBookmark2
.) -
DBCOMPARE_GT (
cbBookmark1
is aftercbBookmark2
.) -
DBCOMPARE_NE (The bookmarks are equal and not ordered.)
-
DBCOMPARE_NOTCOMPARABLE (The bookmarks cannot be compared.)
Fetches rows starting with the row specified by an offset from a bookmark.
STDMETHOD (GetRowsAt )(HWATCHREGION /* hReserved1 */,
HCHAPTER hReserved2,
DBBKMARK cbBookmark,
const BYTE* pBookmark,
DBROWOFFSET lRowsOffset,
DBROWCOUNT cRows,
DBCOUNTITEM* pcRowsObtained,
HROW** prghRows);
See IRowsetLocate::GetRowsAt in the OLE DB Programmer's Reference.
To fetch from the cursor position instead, use IRowset::GetRowsAt.
IRowsetLocateImpl::GetRowsAt
does not change the cursor position.
Fetches one or more rows that match the specified bookmarks.
STDMETHOD (GetRowsByBookmark )(HCHAPTER /* hReserved */,
DBCOUNTITEM cRows,
const DBBKMARK rgcbBookmarks[],
const BYTE* rgpBookmarks,
HROW rghRows[],
DBROWSTATUS* rgRowStatus[]);
hReserved
[in] Corresponds to hChapter parameter to IRowsetLocate::GetRowsByBookmark.
For other parameters, see IRowsetLocate::GetRowsByBookmark in the OLE DB Programmer's Reference.
The bookmark can be a value you define or an OLE DB standard bookmarks (DBBMK_FIRST
or DBBMK_LAST
). Does not change the cursor position.
Returns hash values for the specified bookmarks.
STDMETHOD (Hash )(HCHAPTER /* hReserved */,
DBBKMARK cbBookmarks,
const DBBKMARK* rgcbBookmarks[],
const BYTE* rgpBookmarks[],
DBHASHVALUE rgHashValues[],
DBROWSTATUS rgBookmarkStatus[]);
hReserved
[in] Corresponds to hChapter parameter to IRowsetLocate::Hash.
For other parameters, see IRowsetLocate::Hash in the OLE DB Programmer's Reference.
An array of bookmarks.
CAtlArray<DBROWCOUNT> m_rgBookmarks;
OLE DB Provider Templates
OLE DB Provider Template Architecture
IRowsetLocate:IRowset
Provider Support for Bookmarks
Bookmarks