4.12 Record Locking

There are different sets of functions for locking records. One set locks a specified record number. A second set locks the current data record. A third set is used when inserting new records into an RMSfile. The first two sets (record number and current record) are interchangeable: either set locks and unlocks a single record. Insert locks are only used for inserting new records.

The record number set has three functions. The first of these functions is drlock(C-3). Calling this function attempts to lock a single record in an RMSfile so that other programs attempting to lock the same record are notified that they must wait. A sample call to drlock might be:

The recno parameter is a record number returned by some previous RMS function call. If the record was unlocked prior to the call to drlock, drlock returns a 1. This means that all other programs attempting to lock the same record will be refused. Drlock returns a zero if another program has already locked the entire RMSfile using dflock, or has locked the requested record. At this point, your program can wait and try again or notify the user that the desired record is locked and require the user to try again. Drlock always returns immediately to your program. It does not wait if the record is locked. Instead, an error is returned.

A program may lock more than one record in the same RMSfile, or it may lock records in several different RMSfiles by making multiple calls to drlock. It is possible to create a deadlock where two programs attempt to lock records that are already locked by the other. See the section, "Using File and Record Locking", later in this chapter for a more detailed explanation.

Drlockw(C-3) is identical to drlock except that it waits if the record is locked before returning. Calling this function attempts to lock the record so that other programs attempting to lock the same record are notified that they must wait. A sample call to drlockw might be:

The recno parameter is a record number returned by some previous RMS function call. Normally, drlockw returns 1 indicating that the record is locked. However, it is possible because of some error conditions that drlockw would return an error code of zero, so the return value should always be checked. The drlockw function attempts to discover deadlock conditions and returns a zero if a deadlock would occur by waiting to lock the requested record.

Drunlock unlocks a record that has been locked by either drlock or drlockw. Calling this function removes the lock placed on the record by the calling program. Previously the program must have successfully locked the record. A sample call to drunlock might be:

This allows other users to access the unlocked data record.

The second set of record locking functions lock or unlock the current record. As previously defined, the current record is the last record accessed by your program in the given RMSfile. Many RMS functions set the current data record (all find and read functions, dinsert and dupdate). For this set of functions to work properly, there must be a current record.

The first of these functions is dclock(C-3). Calling this function attempts to lock the current record in an RMSfile so that other programs attempting to lock the same record are notified that they must wait. A sample call to dclock might be:

If the record was unlocked prior to the call to dclock, 1 is returned by dclock. This means that all other programs attempting to lock the same record will be refused.

If there is no current record, if another program has already locked the entire RMSfile using dflock or if another program has locked the requested record, dclock returns a zero. At this point your program either wait and try again, or it can notify the user that the desired record is locked and the user must try the operation again. Dclock always returns immediately to your program. It does not wait if the record is locked. Instead, an error is returned.

Dclockw(C-3) is identical in function to dclock except that it waits if the record is locked. Calling this function attempts to lock the record so that other programs attempting to lock the same record will be notified that they must wait. A sample call to dclockw might be:

Normally, dclockw returns a 1 indicating that the record is locked. However, it is possible, because of some error condition, for dclockw to return an error code of zero, so the return value should always be checked. The dclockw function attempts to discover deadlock conditions and returns a zero if a deadlock would occur by waiting to lock the requested record.

Dcunlock(C-3) unlocks a record that has been locked by dclock or dclockw. Calling this function removes the lock placed on the record by your program. Previously, your program must have successfully locked the record. A sample call to dcunlock might be:

This allows other users to access the data record that has been unlocked. Dcunlock returns an error if there is no current record or if the current record has not been locked.