4 Database Manipulation

The DBLOCK Statement

DBLOCK locks all or a part of a database and provides either exclusive write access or read access which excludes all write access.

DBLOCK (base name, qualifier, mode, status)

The parameters are:

base name
The same string variable used when opening the database.
qualifier
A variable which references a data set or a string expression that describes the lock to be applied (see table below).
mode
A numeric expression defining type of lock (see table below).
status
An integer array variable that returns status information after DBLOCK is executed. The array must contain at least ten elements in its right-most dimension.
 
MODES QUALIFIER COMMENTS
1,2,11,12Ignored.Database level locks.
3,4,13,14Data set name or number.Data Set level locks.
5,6,15,16String expression lock descriptor.General-purpose lock entry level.

DBLOCK locks the section requested if no other user currently has a conflicting lock. If the lock cannot be granted immediately and a "wait" (odd) mode is used, the request is placed in a queue to wait for access. Access is granted only after all conflicting locks ahead in the queue have been granted and released. (Although the section requested is not locked but is in queue, no other request which would lock a subsection and hold up the first request is granted. Refer to Database Locking in page 141 ).

Even mode numbers request a lock without wait; if the lock cannot be granted immediately, no lock is made. The reason for the lock failure is indicated in the condition word of the status array. The request is not queued.

If a program has a lock in effect, additional locks can be made only with even modes ("no-wait" modes). If additional locks are made with odd modes ("wait" modes), the "wait" modes are automatically changed to "no-wait" modes. If these "no-wait" modes cannot be granted, a status error is returned. Using "no-wait" modes prevents successive lock requests from causing a deadlock error. All databases currently opened are checked.

A write lock is exclusive. No other locks may be made on that section. A read lock may be made on a section that already has a read lock.

Summary of DBLOCK Modes

Type of Access
Mode Wait Write Read
1yesEntire database. 
3yesData set. 
5yesPredicate. 
11yes Entire database.
13yes Data set.
15yes Predicate.
2noEntire database. 
4noData set. 
6noPredicate. 
12no Entire database.
14no Data set.
16no Predicate.

For example, the following statement requests without wait a write lock on the data set PARTS: 

100 DBLOCK (BASE$,"PARTS",4,STATUS(*))
However, the following statement requests with wait a read lock on the data sets and data entries specified in the string formed by the concatenation of the lock descriptors in P$ and Q$: 

110 DBLOCK (Base$,P$&Q$,15,Status(*))

DBLOCK Status Array

A DBLOCK error assigns a non-zero conditional word (CW) to the first element of the status array. A list of all CW values and their meanings appears in page 197 . The following table describes the status array contents after a successful DBLOCK.

Type of Access
Array Element Value Description
1Conditional Word0 for successful lock.
2Descriptor NumberNumber causing failure.
 1For successful lock in modes 1 through 4.
30If CW=20, database locked.
 1If CW=20, data set or data entries locked.
4Reserved 
50 
6Bits 0 through 11The DBLOCK identification number 409.
 Bits 12 through 15The mode value used to open the database.
7Program line number 
80 
9Mode numberThe mode parameter value.
10Any valueReserved.

Eloquence Database Manual - 19 DEC 2002