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

C syntax

DBIResult DBIFN DbiSwitchToIndex (phCursor, pszIndexName, pszTagName, iIndexId, bCurrRec);

Delphi syntax

function DbiSwitchToIndex (var hCursor: hDBICur; pszIndexName: PChar; pszTagName: PChar; iIndexId: Word; bCurrRec: Bool): DBIResult stdcall;

Description

DbiSwitchToIndex changes the active index order of the given cursor.

Parameters

phCursor                Type: phDBICur                (Input/Output)
On input, phCursor specifies the original cursor handle; on output, pointer to the new cursor handle.

pszIndexName                Type: pCHAR                (Input)
Pointer to the name of the index or pseudo-index. The pszIndexName string is limited to 127 bytes in length.

pszTagName                Type: pCHAR                (Input)
Pointer to the tag name string. Used for dBASE and FoxPro tables only.

iIndexId                Type: UINT16                (Input)
Specifies the index ID.

bCurrRec                Type: BOOL                (Input)
If TRUE, positions the new cursor on the current record of the original cursor.

Usage

This function allows the user to change the index order of a cursor without closing the cursor and opening another cursor. The original cursor is passed into the function, and a new cursor handle is returned with the new ordering. The original cursor handle becomes invalid and cannot be used.

Setting pszIndexName, pszTagName, and iIndexId to NULL is equivalent to changing the order to the default order. As a result, the cursor is set to one of the following orders:

If bCurrRec is set to TRUE, the new cursor is positioned on the same record as the original cursor. If bCurrRec is set to FALSE, the new cursor is positioned at BOF. If the original cursor is not positioned on a valid record (for example, the current record has been deleted and the cursor has not been advanced), this function with bCurrRec set to TRUE fails. If this function is used to switch to the same index, then no action is taken.

Pseudo-indexes: To describe a pseudo-index rather than an existing physical index, replace the pszIndexName parameter with a string composed of field names. The marker character @ denotes the use of a pseudo-index. For example, "@Customer Number@Order Number" describes a pseudo-index on a key formed by concatenating the Customer Number field with the Order Number field.

Each field identifier in the pseudo-index name must be preceded by the @ character. This character is illegal in "true" index names. No new index is generated at the server; the behavior of the pseudo-index is simulated entirely by use of the proper ORDER BY clauses on the query populating the local BDE record cache.

Fields can be identified by field numbers as well as by field names. For example,  the string "@2@3@11" describes a pseudo-index consisting of the second, third, and eleventh field of the table, concatenated to make up a single key.

Each of the component fields within a pszIndexName is assumed to be in ASCENDING order. Ordering is case-sensitive (unless case-sensitivity is not supported on the specific server). If the fields in the pszIndexName represent a real unique index on the server, the pseudo-index becomes unique; otherwise, it is non-unique.

Prerequisites

A valid cursor handle must be obtained on a table; not on a query or an in-memory table. If the given index is not open, it is automatically opened by this function before switching to that index order. (Therefore, all error return codes for DbiOpenIndex apply.)

Completion state

Switching the index may change some properties of the cursor, such as bookmark size and the key buffer size. Existing bookmarks on the original cursor cannot be used in the new cursor, so any saved positions will no longer be applicable to the new cursor.

See also

DbiAddIndex, DbiOpenIndex, DbiRegenIndex, DbiRegenIndexes, DbiOpenTable