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

C syntax

DBIResult DBIFN DbiAcqPersistTableLock (hDb, pszTableName, [pszDriverType]);

Delphi syntax

function DbiAcqPersistTableLock (hDb: hDBIDb; pszTableName: PChar; pszDriverType: PChar): DBIResult stdcall;

Description

DbiAcqPersistTableLock acquires an exclusive persistent lock on the table that prevents other users from using the table or creating a table of the same name.

Parameters

hDb                Type: hDBIDb                (Input)
Specifies the database handle.

pszTableName                Type: pCHAR                (Input)
Specifies the pointer to table name. For Paradox , 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)
Specifies the 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.

For Paradox tables, pszDriverType is required if the client application wants to overwrite the default file extension, including the situation where pszTableName is terminated with a period(.) pszDriverType must be szPARADOX.

If pszTableName does not supply the default extension, and pszTableType 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.

Usage

This function can be used to acquire an exclusive lock on a non-existent table as a way to reserve the table name. The function fails if the table is already in use. You cannot use DbiSetLockRetry to retry persistent locks.

dBASE and FoxPro: This function is not supported for dBASE and FoxPro tables.

Access: This function is not supported for Access tables.

SQL: This function depends on the capabilities of the server. Some servers provide non-blocking table locks; others provide blocking table locks only; others don't provide table locking. In no case is table locking truly persistent, however. If table locking is supported for the server but locks are not held across transactions, the lock is automatically reacquired after transaction commit. If the application requires a commit, it is responsible for insuring that the window of exposure between lock release and reacquisition has not impacted its consistency requirements. This function is provided to enable a degree of consistency with other drivers. It is recommended that transactions or transactions combined with explicit locking be used for SQL.

Prerequisites

The client application must have exclusive access to the table; if another user is accessing the table, the attempt to lock the table fails.

Completion state

The acquired persistent lock must be explicitly released by the client application. To release the lock, the client application that placed the lock must call DbiRelPersistTableLock.

See also

DbiOpenLockList