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

C syntax

DBIResult DBIFN DbiGetRecordForKey (hCursor, bDirectKey, iFields, iLen, pKey, [pRecBuf]);

Delphi syntax

function DbiGetRecordForKey (hCursor: hDBICur; bDirectKey: Bool; iFields: Word; iLen: Word; pKey: Pointer; pRecBuff: Pointer): DBIResult stdcall;

Description

DbiGetRecordForKey finds a record matching pKey and positions the cursor on that record.

Parameters

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

bDirectKey                Type: BOOL                (Input)
Determines whether pKey is used to specify the key directly or not. If TRUE, the value in pKey is used to specify the key directly. If FALSE, pKey specifies the record buffer.

iFields                Type: UINT16                (Input)
Specifies the number of fields to be used for composite keys. 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 0, the last field to be used must be a character type.

pKey                Type: pBYTE                (Output)
If bDirectKey is TRUE, the pKey specifies the pointer to the record key; otherwise, pKey specifies the pointer to the record buffer. DbiExtractKey can be used to construct the record key when bDirectKey is TRUE. The iFields and iLen Parameters together indicate how much of the key should be used for matching. If both are 0, the entire key is used. If a match is required on a given field of the key, all the key fields preceding it in the composite key must also be supplied for a match. Only character fields can be matched for a partial key; all other field types must be fully matched.

For partial key matches, iFields must be equal to the number of keyfields preceding the field being partially matched. iLen specifies the number of characters in the (iFields+1) field.

pRecBuf                Type: pBYTE                (Output)
Pointer to the record buffer where the new current record is returned.

Usage

SQL: For SQL tables, if the active index is not unique, DbiGetRecordForKey may return different records with the same key value.

Prerequisites

A valid cursor handle must be obtained.

Completion state

The cursor is positioned on the found record. If pRecBuf is supplied, the new current record is retrieved. If there is no key in the index that matches the given key, an error is returned.

See also

DbiSetToKey, DbiExtractKey