<< Click to Display Table of Contents >> Navigation:  »No topics above this level« DbiSetToKey

C syntax

DBIResult DBIFN DbiSetToKey (hCursor, eSearchCond, bDirectKey, [iFields], [iLen], pBuf);

Delphi syntax

function DbiSetToKey (hCursor: hDBICur; eSearchCond: DBISearchCond; bDirectKey: Bool; iFields: Word; iLen: Word; pBuff: Pointer): DBIResult stdcall;

Description

DbiSetToKey positions an ordered cursor based on the given key value.

Parameters

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

eSearchCond                Type: DBISearchCond                (Input)
Specifies the search condition: keySEARCHEQ, keySEARCHGT, or keySEARCHGEQ.

bDirectKey                Type: BOOL                (Input)
Specifies whether the key is supplied directly in pBuff or not. If set to TRUE, pBuf specifies the pointer to the key in physical format; if set to FALSE, pBuf specifies the pointer to the record buffer.

iFields                Type: UINT16                (Input)
Specifies the number of complete fields to be used for composite keys. Optional. If iFields and iLen are both 0, the entire key is used.

iLen                Type: UINT16                (Input)
Specifies the length into the last field to be used for composite keys. If not zero, the last field to be used must be a character type.

pBuf                Type: pBYTE                (Input)
Pointer to either the record buffer or the key itself, determined by bDirectKey.

Usage

If no index is currently associated with the cursor, an error is generated and no cursor movement occurs.

There are three possible search conditions: keySEARCHEQ, keySEARCHGT, and keySEARCHGEQ. Searches always result in the cursor being positioned on the crack before the record of the specified key value. Assuming all the arguments are specified correctly, only the (=) search condition can return a DBIERR_RECNOTFOUND error.

(> or >=) always succeeds.

You can specify the key either by setting the key fields in a record buffer and supplying the record buffer or by specifying the key buffer directly as a string of bytes. To construct the key buffer, use DbiExtractKey.

The iFields and iLen parameters together indicate how much of the key is to be used for matching. If both are 0, the entire key is used. If a partial match is required on a given field of the key, all the key fields preceding it in the composite key must also be specified for match. Only character fields can be matched for a partial key; all other field types must be fully matched.

Prerequisites

A cursor handle must be ordered using an index.

Completion state

A search using keySEARCHEQ or keySEARCHGEQ positions the cursor on the crack just prior to the specified key; using keySEARCHGT positions the cursor on the crack just after the specified key.

See also

DbiSetRange, DbiSwitchToIndex, DbiSetToBookMark, DbiGetNextRecord, DbiGetPriorRecord