DbiSetRange

C syntax

DBIResult DBIFN DbiSetRange (hCursor, bKeyItself, [iFields1], [iLen1], [pKey1], bKey1Incl, iFields2, iLen2, [pKey2], bKey2Incl);

Delphi syntax

function DbiSetRange (hCursor: hDBICur; bKeyItself: Bool; iFields1: Word; iLen1: Word; pKey1: Pointer; bKey1Incl: Bool; iFields2: Word; iLen2: Word; pKey2: Pointer; bKey2Incl: Bool): DBIResult stdcall;

Description

DbiSetRange constrains the result set to the subset bounded by two keys.

Parameters

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

bKeyItself Type: BOOL (Input)
Defines the key buffer type. If set to TRUE, pKey1 and pKey2 contain the keys directly; if set to FALSE, pKey1 and pKey2 point to record buffers from which the keys can be extracted.

iFields1 Type: UINT16 (Input)
Specifies the number of fields to be used for composite keys, for the beginning of the range. Optional. The iFields1 and iLen1 parameters together indicate how much of the key is to be used for matching. If both are zero, 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 be included. Only character fields can be matched for a partial key; all other field types must be fully matched.

For partial key matches, iFields1 must be equal to the number (if any) of key fields preceding the field being partially matched. iLen1 specifies the number of characters in the partial key to be matched.

iLen1 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.

pKey1 Type: pBYTE (Input)
Pointer to the key value or record buffer for the beginning of the range. Optional. If NULL, no low limit is set.

bKey1Incl Type: BOOL (Input)
Specifies whether to include the beginning key value in the range. bKey1Incl can be either TRUE or FALSE.

iFields2 Type: UINT16 (Input)
Specifies the number of fields to be used for composite keys, for the end of the range. Optional. The iFields2 and iLen2 parameters together indicate how much of the key is to be used for matching. If both are zero, 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. Only character fields can be matched for a partial key; all other field types must be fully matched.

For partial key matches, iFields2 must be equal to the number (if any) of key fields preceding the field being partially matched. iLen2 specifies the number of characters in the partial key to be matched.

iLen2 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.

pKey2 Type: pBYTE (Input)
Pointer to the key value or record buffer for the end of the range. Optional. If NULL, no high limit is set.

bKey2Incl Type: BOOL (Input)
Specifies whether to include the end key value in the range. bKey2Incl can be either TRUE or FALSE.

Prerequisites

There must be an active index.

Completion state

DbiSetRange positions the cursor at the beginning of the range, not on the first record in the range.

After this function is called, the cursor allows access only to records in the table that fall within the defined range. Any attempt to reference records outside the range results in a BOF or EOF error condition.

Paradox: DbiGetRecordCount now reflects only the records in the range. DbiGetSeqNo is relative to the beginning of the range, rather than the beginning of the table.

DbiResult	Meaning
DBIERR_NONE	The range was set successfully.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL.
DBIERR_OUTOFRANGE	(iField iLen) is less than the whole key.
DBIERR_NOASSOCINDEX	The specified cursor does not have an active index.