DbiCloneCursor

C syntax

DBIResult DBIFN DbiCloneCursor (hCurSrc, bReadOnly, bUniDirectional, phCurNew);

Delphi syntax

function DbiCloneCursor (hCurSrc: hDBICur; bReadOnly: Bool; bUniDirectional: Bool; var hCurNew: hDBICur): DBIResult stdcall;

Description

DbiCloneCursor creates a new cursor (cloned cursor) that is similar to the given cursor (source cursor).

Parameters
hCurSrc	Type: hDBICur	(Input)
Specifies the cursor handle of the source cursor.
bReadOnly	Type: BOOL	(Input)
Specifies whether the cloned cursor access mode is to be read-only or read-write. TRUE specifies read-only and FALSE specifies read-write.
The client is able to choose the access mode of the cloned cursor only if the access mode of the source cursor is dbiREADWRITE. If the access mode of the source cursor is dbiREADONLY, then the access mode of the cloned cursor must be read-only.
bUnidirectional	Type: BOOL	(Input)
Specifies whether the cloned cursor movement is unidirectional or bidirectional (applies to SQL tables only). TRUE specifies unidirectional; FALSE specifies bidirectional.
Generally, bidirectional movement is preferable. However, if the client application knows that the cloned cursor is to access data solely from beginning to end, unidirectional movement might deliver better performance.
The client is able to choose the type of cursor movement for the cloned cursor only if the source cursor's bUnidirectional parameter is FALSE (bidirectional). If the source cursor's bUnidirectional parameter is TRUE (unidirectional), the cloned cursor can be only unidirectional.
phCurNew	Type: phDBICur	(Output)
Pointer to the cursor handle for the cloned cursor.

Usage

DbiCloneCursor provides the client a relatively quick way to get a cursor for a table that is already opened. The source cursor can be opened on a table or a query. The cloned cursor can then be used as a regular cursor, inheriting certain properties from the source cursor, but remaining completely independent in terms of position and ordering.

The cloned cursor inherits the following properties from the source cursor:

•Current index

•Range

•Translate mode

•Share mode

•Position

•Field maps

•Filters

Putting a field map or a filter on a cloned cursor does not affect the source cursor. The filters of a cloned cursor do not have the same filter handles as the original cursor, however, the filter ID (obtained with DbiGetFilterInfo) is invariant to the clone. This can be used to obtain the new filter handle for a given filter.

Positional commands (for example, DbiGetNextRecord) performed on the source cursor have no effect on the cloned cursor and vice versa.

dBASE and FoxPro: All indexes open on the source cursor are open on the clone.

Access: A cursor that references a table that is opened exclusively cannot be cloned.

Completion state

The returned cursor inherits certain properties from the source cursor but is completely independent in terms of position and ordering. The cloned cursor must be closed separately.

DbiResult	Meaning
DBIERR_NONE	The cloned cursor was created successfully.
DBIERR_CURSORLIMIT	The maximum number of cursors has been exceeded.
DBIERR_INVALIDHNDL	The specified source cursor handle is invalid or NULL, or the pointer to the new cursor handle is NULL.