This documentation is archived and is not being maintained.

CRecordset::SetBookmark

Positions the recordset on the record containing the specified bookmark.

void SetBookmark( 
   const CDBVariant& varBookmark  
);

varBookmark

A reference to a CDBVariant object containing the bookmark value for a specific record.

To determine if bookmarks are supported on the recordset, call CanBookmark. To make bookmarks available if they are supported, you must set the CRecordset::useBookmarks option in the dwOptions parameter of the Open member function.

NoteNote:

If bookmarks are unsupported or unavailable, calling SetBookmark will result in an exception being thrown. Bookmarks are not supported on forward-only recordsets.

To first retrieve the bookmark for the current record, call GetBookmark, which saves the bookmark value to a CDBVariant object. Later, you can return to that record by calling SetBookmark using the saved bookmark value.

NoteNote:

After certain recordset operations, you should check the bookmark persistence before calling SetBookmark. For example, if you retrieve a bookmark with GetBookmark and then call Requery, the bookmark may no longer be valid. Call CDatabase::GetBookmarkPersistence to check whether you can safely call SetBookmark.

For more information about bookmarks and recordset navigation, see the articles Recordset: Bookmarks and Absolute Positions (ODBC) and Recordset: Scrolling (ODBC).

This method can throw exceptions of type CDBException* and CMemoryException*.

Header: afxdb.h

Show: