DbiGetBookMark

C syntax

DBIResult DBIFN DbiGetBookMark (hCur, pBookMark);

Delphi syntax

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

Description

DbiGetBookMark saves the current position of a cursor in the client-supplied bookmark buffer. This position is called a bookmark.

Parameters

hCur Type: hDBICur (Input)
Specifies the cursor handle.

pBookMark Type: pBYTE (Output)
Pointer to the client-allocated bookmark buffer.

Usage

A bookmark contains internal information about the current position of the cursor. This information can be passed to DbiSetToBookMark to reposition the same or compatible cursor. If a bookmark is stable, it is guaranteed that the cursor can be repositioned there. Whether or not the bookmark is stable can be determined from the bBookMarkStable property returned by DbiGetCursorProps.

dBASE and FoxPro: For dBASE and FoxPro tables, the bookmark is always stable.

Paradox: For Paradox tables, the bookmark is stable only if the table has a primary key.

SQL: For SQL tables, the bookmark is stable only if the table has a unique index or unique row identifier.

Prerequisites

DbiGetCursorProps should be called to retrieve the iBookMarkSize property and the bookmark buffer should be allocated to accommodate the bookmark.

Note:

The size of a bookmark depends on the current index and can change if DbiSwitchToIndex is called.

Completion state

The bookmark buffer pointed to by pBookMark contains the saved cursor position. The bookmark is valid only with a cursor that is using the same table and ordered with the same index.

DbiResult	Meaning
DBIERR_NONE	The bookmark was returned successfully.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL, or the pointer to the bookmark buffer is NULL.