DbiSetToBookMark

C syntax

DBIResult DBIFN DbiSetToBookMark (hCur, pBookMark);

Delphi syntax

function DbiSetToBookMark (hCur: hDBICur; pBookMark: Pointer): DBIResult stdcall;

Description

DbiSetToBookMark positions the cursor to the position saved in the specified bookmark.

Parameters

hCur Type: hDBICur (Input)
Specifies the cursor handle. hCur must be compatible with the cursor used when the bookmark was obtained.

pBookMark Type: pBYTE (Input)
Pointer to the bookmark. The bookmark is obtained by a prior call to DbiGetBookMark.

Usage

This function is used to position the cursor to a saved position. To determine if the bookmark is stable, call DbiGetCursorProps and examine the bBookMarkStable property.

Prerequisites

DbiGetBookMark must have been called to retrieve a valid bookmark. The supplied cursor can be different from the one used to retrieve the bookmark information, but the cursor must be opened on the same table, with the same index order, if any.

Note:

DbiSwitchToIndex may make bookmarks obtained under a different index order unusable with the new order.

Completion state

The cursor is positioned at the bookmark location. If the record pointed to by the bookmark has been deleted, the cursor is positioned on a crack where the original record was.

Note:

If the bookmark is unstable, the cursor may be in an unexpected position.

DbiResult	Meaning
DBIERR_NONE	The call was successful; however, the position may not be the expected one if the record has been deleted, or if the bookmark was unstable.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL, or the pointer to the bookmark is NULL, or the specified bookmark is NULL.
DBIERR_INVALIDBOOKMARK	The specified bookmark is not from the same table, or the bookmark is corrupt.