DBLOCK(base,qualifier,mode,status)

base

is the name of an array used as the base parameter when opening the database. The first element of the array must contain the base ID returned by DBOPEN. (Refer to DBOPEN for more information about the base ID.)

qualifier

The qualifier argument depends on the mode:

• Modes 1,2,11,12: Ignored
• Modes 3,4,13,14: An integer variable referencing the data set number or the name of an array containing a data set name. Could also be "@" when applying a database lock.
• Modes 5,6,15,16: The name of the array containing the lock descriptors.

mode

contains an integer indicating the type of locking desired. Valid modes are 1 to 6 and 11 to 16.

status

is the name of an array of 10 halfwords in which the database returns status information about the procedure. If the procedure executes successfully, the status array contents are:

Element	Contents
1	If the procedure succeeds, the return status is 0. Otherwise it provides a status code to describe the failure.
2	The number of lock descriptors that were successfully applied in the DBLOCK request. For successful locks in modes 1 through 4 and 11 through 14 this will be 1.
3	Zero. TurboIMAGE used to return additional information for a return status 20 which is not available with Eloquence: If the return status is 20, this element contains 0 if the database is locked, 1 if the data set or entries are locked.
4	Unchanged from previous procedure call using this array.
5-10	Information about the current procedure call and its results.

DBLOCK modes:

Lock Mode	Lock Level	Locking Type	Description
1	Base	Unconditional	DBLOCK applies an unconditional lock to the entire database, returning to the calling program only after the lock is successful (or if an error occurs). The qualifier parameter is ignored.
2	Base	Conditional	DBLOCK applies a conditional lock to the entire database and returns immediately. A return status of zero indicates success. A non-zero return status indicates the reason for failure.
3	Set	Unconditional	DBLOCK applies an unconditional lock to a data set. The qualifier parameter must specify the name of an array containing the left-justified name of the data set or the name of an integer referencing the data set number. The data set name can be 16 characters long or, if shorter, terminated by a semicolon or blank. The data set need not be accessible for read or write access to the user requesting the lock.
4	Set	Conditional	DBLOCK applies a conditional lock of the same type as mode 3. It always returns to the calling program immediately. A return status of zero indicates success and a non-zero return status indicates a reason for failure.
5	Entry	Unconditional	DBLOCK applies unconditional locks to the data entries specified by lock descriptors. The qualifier parameter must specify the name of an array containing the lock descriptors. It returns only when all the locks have been acquired.
6	Entry	Conditional	DBLOCK applies conditional locks of the same type as mode 5. If multiple lock descriptors are specified and DBLOCK encounters a lock descriptor that it cannot apply, it returns. All locks that have been applied until that point are released.

Modes 1 through 6 request a write lock. Modes 11 through 16 are identical but request a read lock. A write lock does block any concurrent read or write lock. A read lock blocks concurrent write locks but allows current read locks.

Notes:

• With the Eloquence database, locking is optional. DBLOCK is not enforced to allow read or write access.

• Multiple locks are allowed. Details are subject to the server configuration (eloqdb6.cfg):
  • AllowSecondaryBlockingLock needs to be set to 1 to allow secondary blocking ("Unconditional") locks. For historic reasons they are not enabled by default.

    If set, secondary blocking locks are allowed. Normally, secondary locks in a blocking (odd) mode will fail with database status -135 ("Second lock is not allowed in modes 1,3,5,11,13 and 15.") instead of blocking. Enabling this setting could result in a deadlock detected by the database when programs use an incompatible lock strategy.

  • LockConflictingItems needs to be set to 1 to allow DBLOCK to assume different items locking an entry do not conflict. By default this is set to 0.

    If set, predicate locks with conflicting items are granted, however any write attempt to data where another process owns a lock will result in a status error -12. By default Eloquence does not allow a predicate lock with a conflicting item, because this could lead to a situation where two processes own a lock on an overlapping subset of data.

  We recommend to set AllowSecondaryBlockingLock = 1 and LockConflictingItems = 0 in the server configuration.

• Subsequent "unconditional" locks will return a database status when they would cause a deadlock. However a deadlock condition is never returned for a program only using a single lock or only conditional locks.

• A compound lock descriptor is applied atomically. There is no need to DBUNLOCK in case of a failed lock request.

• Additional modes 11-16 are available for read locking.

• Due to a bug in the IMAGE3K library, status element 2 currently returns zero instead of the number of lock descriptors. However, since Eloquence applies lock descriptors atomically, a zero status indicates all lock descriptors are granted and a failure indicates no lock descriptor was accepted.

• With TurboIMAGE status element 3 indicates for a return status 20 if the database is locked (0) or if the data set or entries are locked (1). With Eloquence this is always zero.