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

C syntax

DBIResult DBIFN DbiOpenTable (hDb, pszTableName, [pszDriverType], pszIndexName, pszIndexTagName, iIndexId, eOpenMode, eShareMode, exltMode, [bUniDirectional], [pOptParams], phCursor);

Delphi syntax

function DbiOpenTable (hDb: hDBIDb; pszTableName: PChar; pszDriverType: PChar; pszIndexName: PChar; pszIndexTagName: PChar; iIndexId: Word; eOpenMode: DBIOpenMode; eShareMode: DBIShareMode; exltMode: XLTMode; bUniDirectional: Bool; pOptParams: Pointer; var hCursor: hDBICur): DBIResult stdcall;

Description

DbiOpenTable opens the given table for access and associates a cursor handle with the opened table.

Parameters

hDb                Type: hDBIDb                (Input)
Specifies the database handle associated with the database where the table exists.

pszTableName                Type: pCHAR                (Input)
Pointer to the table name. For Paradox, FoxPro, and dBASE, 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, pszTableName can be a fully qualified name that includes the owner name, in the form <owner>.<tablename>.

If not specified, <owner> is supplied from the database handle. Extensions are not valid for SQL table names.

pszDriverType                Type: pCHAR                (Input)
Pointer to the driver type. Optional. pszDriverType can be one of the following values: szDBASE, szMSACCESS, szPARADOX, or szASCII (for importing or exporting data to/from text files; see the Usage section).

For Paradox, FoxPro, and dBASE tables, this parameter is required if pszTableName has no extension, or if the client application wants to overwrite the default file extension, including the situation where pszTableName is terminated with a period(.). If pszTableName does not supply the default extension, and pszDriverType is NULL, DbiOpenTable tries to open the table with the default file extension of all file-based drivers listed in the configuration file in the order that the drivers are listed.

This parameter is ignored if the database associated with hDb is a SQL or Access database.

pszIndexName                Type: pCHAR                (Input)
Pointer to the name of the index or pseudo-index to be used to order the records in the result set. Optional. For SQL tables, the index name does not have to be qualified with the owner for servers supporting naming conventions with owner qualification. The pszIndexName string is limited to 260 bytes in length.

pszIndexTagName                Type: pCHAR                (Input)
Pointer to the tag name of the index in a .MDX or .CDX file used to order the records in the result set. Optional; used for dBASE and FoxPro tables only. This parameter is ignored if the index given by pszIndexName is a .NDX index.

iIndexId                Type: UINT16                (Input)
Specifies the index identifier, which is the number of the index to be used to order the records in the result set. Optional; used for Paradox, Access, and SQL tables only.

Paradox: For Paradox tables, the range for the index identifier is 1 to 511. This parameter is ignored if pszIndexName is specified.

SQL: For SQL tables, this field is used only to specify that the table should be opened with no default index. This is done by setting iIndexId to NODEFAULTINDEX and is useful when opening a table read-only to speed up record access time.

Access: For Access tables, the range for the index identifier is 1 to the number of valid indexes. This parameter is ignored if pszIndexName is specified.

eOpenMode                Type: DBIOpenMode                (Input)
Specifies the table open mode. If the mode is read-only, updates to the table are not permitted.

eShareMode                Type: DBIShareMode                (Input)
Specifies the table share mode, and determines whether other users or other cursors are able to open the table.

exltMode                Type: XLTMode                (Input)
Specifies the data translation mode.

bUniDirectional                Type: BOOL                (Input)
Specifies the scan mode of the cursor for SQL only.

pOptParams                Type: pBYTE                (Input)
Not currently used.

phCursor                Type: phDBICur                (Output)
Pointer to the cursor handle for the opened table.

Usage

Text: The DbiOpenTable call can be used to open a text file for import/export of data. The pszDriverType argument is used differently to indicate whether the fields in the text file are fixed length or delimited. The field separator and delimiter are passed through the pszDriverType argument.

dBASE: If no index is specified, the table is opened in physical order. If pszIndexTagName specifies an index tag, the table is opened with that tag active. The index name and the tag name are specified to open the index.

FoxPro: If no index is specified, the table is opened in physical order. If pszIndexTagName specifies an index tag, the table is opened with that tag active. The index name and the tag name are specified to open the index. To see if a cursor is referencing a FoxPro table, retrieve CURProps using DbiGetCursorProps.

Access: If a cursor is opened exclusively in the active session, no other cursors may be opened in that session.

Paradox: If all index parameters are NULL, the table is opened in primary key order, if a primary key exists. If a secondary key is specified, the table is opened in that key. Either pszIndexName or iIndexId can be used to specify a composite or non-composite secondary index. A single-field index that is case-insensitive is classified as a composite index. See also: szName

SQL: An index can be specified only in pszIndexName. The index name can be qualified or unqualified. SQL provides limited support for exclusive opens, depending on the level of server explicit lock support.

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.

Referential integrity descriptions: By default, DbiOpenTable does not retrieve referential integrity information (primary keys, foreign keys, and so on) when opening a table. This improves performance. To retrieve referential integrity information, use DbiSetProp to set curGETEXTENDEDINFO to True, then call DbiGetCursorProps

Prerequisites

If the database is opened read-only, the table cannot be opened read-write.

Completion state

After the table has been successfully opened, the cursor is opened and positioned on the crack at the beginning of the file. A valid cursor is returned.

See also

DbiCloseCursor