DbiAddIndex

C syntax

DBIResult DBIFN DbiAddIndex (hDb, hCursor, pszTableName, [pszDriverType], pIdxDesc, [pszKeyviolName]);

Delphi syntax

function DbiAddIndex (hDb: hDBIDb; hCursor: hDBICur; pszTableName: PChar; pszDriverType: PChar; var IdxDesc: IDXDesc; pszKeyviolName: PChar): DBIResult stdcall;

Description

DbiAddIndex creates an index on an existing table specified by pszTableName or associated with the cursor handle specified by hCursor.

Parameters
hDb	Type: hDBIDb	(Input)
Specifies the database handle.
hCursor	Type: hDBICur	(Input)
Specifies the cursor on the table. Optional. If hCursor is specified, the operation is performed on the table associated with the cursor. If hCursor is NULL, pszTableName and pszTableType determine the table to be used. This option is not supported with Access tables.
pszTableName	Type: pCHAR	(Input)
Pointer to the table name. Optional. If hCursor is NULL, pszTableName and pszDriverType determine the table to be used. (If both pszTableName and hCursor are specified, pszTableName is ignored.)
For Paradox, dBASE, and FoxPro, if pszTableName is a fully qualified name of a table, the pszDriverType parameter need not be specified. If the path is not included, the path name is taken from the current directory of the database associated with hDb.
For SQL databases, this parameter can be a fully qualified name that includes the owner name.
pszDriverType	Type: pCHAR	(Input)
Pointer to the driver type. Optional. For Paradox, dBASE, and FoxPro tables, this parameter is required if pszTableName has no extension. This parameter is ignored if the database associated with hDb is a SQL database. pszDriverType can be one of the following values: szDBASE, szMSACCESS, or szPARADOX.
pIdxDesc	Type: pIDXDesc	(Input)
Pointer to the index descriptor structure (IDXDesc). The IDXDesc elements required vary by database driver.
pszKeyviolName	Type: pCHAR	(Input/Output)
Optional. Pointer to a key violation table name (a buffer of DBIMAXPATHLEN+1 characters). You can specify a table name or use this parameter to retrieve the name generated by the BDE. This parameter is not supported for Access tables.

Usage

If a cursor handle is supplied, the function generally does not affect the order or the position of the cursor. However, adding Paradox primary indexes sets the cursor position to the beginning of the file.

Index descriptors vary by driver. For details, see IDXDesc and IDXType

dBASE: The client application must have permission to lock the table exclusively.

FoxPro: The client application must have permission to lock the table exclusively.

SQL: The client application must have the appropriate privileges to add indexes. Also, if an index is added to any SQL table, then any cursors open on that table must be closed and reopened, to allow for possible changes in the buffer size.

Paradox: The client application must have permission to lock the table exclusively. If adding a non-maintained Paradox index, only a read lock is required.

Access: You can't add indexes to an open cursor, and Access does not support key violation tables.

Oracle8: Not supported for object types (ADT, REF, nested table, and VARARRAY).

Prerequisites

If the table name or cursor handle is used to specify the table, the cursor must be opened exclusively on behalf of the client application, and is closed after the index has been created. If the index is a maintained or primary Paradox index, the cursor also must be opened exclusively.

Completion state

Before the cursor is reordered to reflect the newly added index, the application must use or switch to the index.

DbiResult	Meaning
DBIERR_NONE	The index was successfully added.
DBIERR_INVALIDHNDL	The specified database handle or the cursor handle (if specified) is invalid or NULL.
DBIERR_INVALIDPARAM	Neither hCursor nor pszTableName was specified.
DBIERR_UNKNOWNTBLTYPE	The parameter, pszDriverType is invalid.
DBIERR_PRIMARYKEYREDEFINE	The primary index already exists; illegal to define another.
DBIERR_INVALIDINDEXTYPE	The index descriptor is invalid.
DBIERR_INVALIDIDXDESC	The index descriptor is invalid.
DBIERR_INVALIDFLDTYPE	Attempting to index an invalid field type (that is, BLOB field)
DBIERR_INVALIDINDEXNAME	The index name or tag name is invalid (usually for dBASE or FoxPro tables)
DBIERR_NAMEREQUIRED	Index name is required.
DBIERR_NAMENOTUNIQUE	Index name was not unique.
DBIERR_MUSTUSBASEORDER	The default order must be used when adding an index.
DBIERR_NEEDEXCLACCESS	Table is opened in share mode when creating a maintained or primary index.