Name

Generic Prototype

C Prototype

dt_Boolean dt_thor_settdtlocking(dt_Handle database, dt_Integer plen, dt_String password, dt_Integer enforce_locking)

FORTRAN Prototype

integer*4 dt_f_thor_settdtlocking(database, password, enforce_locking)

integer*4 database
character*() password
integer*4 enforce_locking

Description

- dt_thor_tdtget(3) is used to lock records: If a TDT is retrieved from a writable database, a lock is automatically set on that TDT.

- dt_thor_tdtput(3) is used to unlock records: The "how" parameter has values that allow you to write, merge, unlock, and rollback records.

The parameter 'enforce_locking' indicates whether to enable or disable record locking. If it is TRUE, record locking is enforced; if it is FALSE, record locking is disabled. Record locking is a permanent property of the database (i.e. it is retained when the database is closed and reopened), and it applies to all client programs using the database.

This function will fail if any other client program has the database open. You can't change record locking enforcement while the database is in use.

When a client program locks a record, the record is said to be "owned" by that client. The owner of a record has exclusive write access to that record; no other client can modify or delete that record (although they can read the record). A record can only be locked by one client at a time.

It is possible to lock records that don't exist. For example, if dt_thor_tdtget(3) is called with the 'writable' parameter TRUE, then that record will be locked whether or not the record actually exists. Similarly, a record can be locked and then deleted from the database; the lock remains in effect until it is explicitly removed (see dt_thor_tdtput(3)), even though the record is no longer in the database.

Changes made to a locked record are invisible to other clients until that record is unlocked ("committed"). For example, if a client locks a record, then deletes it, other clients will still "see" the original record, but to the client holding the lock the record will appear to be gone.

It is possible undo changes made to a locked record (do a "rollback") at any time before it is unlocked ("committed"). See dt_thor_tdtput(3) for details.

A client loses all locks when it closes the database or disconnects from the server. Locks can only be retained while a client actually has the database open.

Record locking is not necessary in most situations. Thor's ability to merge records makes it possible for users to simultaneously modify records with little chance of conflicts. On the rare occasion when conflicts arise, Thor's timestamp facility provides adequate warning.

Related Topics