Document revision date: 15 July 2002

Record-locking options can be divided into three groups:

• Options that specify the access allowed by other record streams
• Options that control record conflicts between record streams
• Miscellaneous options

All record-locking options are specified by RAB input to the accessing service. All record-locking options apply to the Get service and the Find service, and most record-locking options apply to the Put service. You can specify a different set of record-locking options each time the record stream accesses a record.

This section describe the types of record access allowed by each record locking option. It also provides some examples of when an application program might select a particular record-locking option. The following five record-locking options control record access by other record streams:

• Exclusive locking
• Write locking
• Read locking
• No locking
• No query locking

To update or delete a record, a record stream must have an exclusive lock or a write lock on the record.

7.2.2.1 Exclusive Locking

By default, RMS performs exclusive locking. With exclusive locking, only the initial record stream is permitted to access the record for reading or writing until the lock is released. Any other record stream that tries to read or write the record by applying a lock is denied access. When a record stream is denied access because of a locked record, the requesting service returns a locked-record status (RMS$_RLK).

A record stream can read an exclusively locked record only with the read-regardless option (see Section 7.2.3.3).

Most application programs use exclusive locking because it requires minimal programming and provides maximum protection when modifying and reading records. Note, however, that contention is apt to be greatest when a record stream uses the exclusive-locking option.

See Section 7.2.1 for an example of how RMS uses exclusive locking for an application program that is modifying a record.

7.2.2.2 Write Locking

The write-locking option allows the record stream that locks a record to modify the record. This option prohibits other record streams from having write-lock access or exclusive lock access, both of which imply an intent to modify the record. The write-locking option also denies read-lock access to other record streams because a read-lock access is incompatible with a record stream that is modifying the record.

Contending record streams can read the record using the no-locking option, or the read-regardless option (see Section 7.2.3.3). When a contending record stream reads a write-locked record using the no-locking option, the accessing service returns a success status.

Typically, an application program uses the write-locking option when it wants the record to remain in a consistent state while the application program is modifying the record.

7.2.2.3 Read Locking

The read-locking option permits other record streams to access the record for reading but denies access to any record stream that attempts to access the record for making modifications.

No record stream is allowed to access a read-locked record for making modifications to the record until all record streams that have a read lock release the record. Any record stream that attempts to access a read-locked record using either the exclusive-locking option or the write-locking option are denied access. The requesting service returns a completion status record to the application program indicating that the record was locked (RMS$_RLK) and the requesting record stream was denied access.

Contending record streams can read the record using the read-locking option, the no-locking option or the read-regardless option (see Section 7.2.3.3). When a contending record stream accesses a read-locked record using the read-locking option or the no-locking option, the accessing service returns a success status.

Typically, an application program uses the read-locking option when it wants the record to remain in a consistent state while reading the record but does not intend to modify the record.

7.2.2.4 No Locking (Query Locking)

The no-locking option specifies that the requesting record stream does not want to lock the record. This locking option permits the requesting record stream to have access to all locked records except for records that are locked for exclusive access. It also permits other record streams to apply any type of lock to the record. Using this option minimizes contention, but unlike the no query record locking option does not avoid a call to the lock manager .

By implication, a record stream that uses the no-locking option can only access the record for reading. When a record stream uses the no-locking option to access a record, the invoked service returns with the record unlocked.

Note that when a record stream selects the no-locking option, RMS momentarily locks the record to query whether or not the record is already locked by another record stream. This is required in order to determine if access is allowed. If the record is not locked, the requesting service returns a completion status indicating a successful access. If the record has an exclusive lock, the access is denied and the requesting service returns a completion status indicating the record is locked (RMS$_RLK). If the record has a write lock, the requesting service reads the record and returns a completion status indicating that the record was locked but a read was permitted (RMS$_OK_RLK).

If you specify the no-locking option together with the manual-unlocking option, the no-locking option takes precedence. That is, if you specify both options to the service that accesses the record, the service returns control to the application program with the record unlocked. See Section 7.2.4.1 for a description of the manual-unlocking option.

7.2.2.5 No Query Record Locking Option (Alpha Only)

The OpenVMS operating system provides functionality that can minimize record locking for read accesses to shared files, thereby avoiding the processing associated with record locking calls to the lock manager.

In previous releases to OpenVMS Version 7.2--1H1, if a file is opened allowing write sharing, an exclusive record lock is taken out for all record operations (both read and write). Applications may obtain record locking modes other than the exclusive lock (default) by specifying certain options to the RAB$L_ROP field. However, all the options involve some level of record locking. That is, the options require $ENQ or $DEQ system service calls to the lock manager.

The user record locking options include the RAB$V_NLK (no lock) query locking option, which requests that RMS take out a lock to probe for status and not hold the lock for synchronization. If the lock is not granted (exclusive lock held) and the read-regardless (RAB$V_RRL) option is not set, the record access fails with an RMS$_RLK status. Otherwise, the record is returned with one of the following statuses:

• RMS$_SUC --- No other writers
• RMS$_OK_RLK --- Record can be read but not written
• RMS$_OK_RRL --- Exclusive lock is held (lock request denied) but the read-regardless (RAB$V_RRL) option is set

When only the RAB$V_NLK option is specified, record access can be denied. When both the RAB$V_NLK and RAB$V_RRL options are specified, an application can guarantee the return of any record with a success or alternate success status.

The OpenVMS Version 7.2--1H1 introduces the no query record locking option, which allows applications to read records (using $GET or $FIND services) without any consideration of record locking. This option:

• Does not make a call to the lock manager
• Is equivalent to both RAB$V_NLK and RAB$V_RRL being set except that the RMS$_OK_RLK or RMS$_OK_RRL status will not be returned

This functionality applies to all three file organizations (sequential, relative, and indexed).

Three alternate methods for specifying the no query record locking option are outlined in Table 7-5.

Note the following:

• The first method allows the option to be enabled externally, potentially without any application change.
• You should use any of the methods only as appropriate for the application. In particular, you should check for any dependency in an existing application on the alternate success status RMS$_OK_RLK or RMS$_OK_RRL.

Table 7-5 Methods Available for Specifying No Query Record Locking

To...	Use This Method...
Disable query record locking at the process or system level.	Enter the following DCL command to request the RMS use no query record locking for any read operation with both RAB$V_NLK and RAB$V_RRL options set in the RAB$L_ROP field: $ SET RMS_DEFAULT/QUERY_LOCKING=DISABLE[/SYSTEM] Keys on RAB$V_NLK and RAB$V_RRL options in existing applications.
Enable no query record locking on a per-record read operation.	Set the RAB$V_NQL option in the RAB$W_ROP_2 field. The RAB$V_NQL option takes precedence over all other record locking options. Use only if the current read ($GET or $FIND) operation is not followed by an $UPDATE or $DELETE call.
Enable no query record locking at the file level.	Set the FAB$V_NQL option in the FAB$B_SHR field to request that RMS use no query locking for the entire period the file is open for any read record operation with both RAB$V_NLK and RAB$V_RRL options set in the RAB$L_ROP field. This option can be used with any combination of the other available FAB$B_SHR sharing options. Keys on RAB$V_NLK and RAB$V_RRL options in applications.

RMS precedence for the no query record locking option is as follows:

• The RAB$V_NQL option set in the RAB$W_ROP_2 field
• At file open (and applied, if RAB$V_NLK and RAB$V_RRL are set for the read operation):
  • The FAB$V_NQL option set in the FAB$B_SHR field
  • The SET RMS_DEFAULT/QUERY_LOCKING=DISABLE setting at the process level
  • The SET RMS_DEFAULT/QUERY_LOCKING=DISABLE setting at the system level. If the process /QUERY_LOCKING setting equals SYSTEM_DEFAULT (the default when the process is created), RMS uses the system specified value.

Because the Put service adds a new record, the application program does not have to access an existing record. However, because adding a record is a multistep process, the record that is being added must be locked until the entire process is finished.

The scenario for adding a record to a file begins with the application program moving a record into its buffer. Next, the application program calls the Put service, which locks the record while it moves it from the application program buffer to the file. When the record is in the file, the Put service unlocks the record, making it available to other record streams. The locking process is transparent at the program level unless the application program selects the manual-unlocking option.

If a record stream tries to add a record using the no-locking option, the Put service ignores the option and adds the record.

7.2.2.7 Summary

This section provides two tables to summarize the information described in Sections 7.2.2.1 through 7.2.2.6.

The record-locking options that control record access exhibit varying degrees of compatibility. Table 7-6 summarizes access control locking compatibility by comparing the type of access being requested by a record stream with the current lock held by another record stream. The table does not take into account miscellaneous record-locking options, notably the read-regardless option.

Table 7-6 Compatibility of Record-Locking Options

	Current Lock Held by Another Record Stream
Requested Access	EXCLUSIVE	WRITE	READ	None
EXCLUSIVE	NO	NO	NO	YES
WRITE	NO	NO	NO	YES
READ	NO	NO	YES	YES
NO LOCK	NO	YES 1	YES 1	YES

The next table lists record-locking options that control record access and how you select each option through the FDL and RMS interfaces.

Option	Interface	How to Select
Exclusive locking	FDL: RMS:	This is the default when you do not select write locking, read locking, or no locking.
Write locking	FDL: RMS:	CONNECT LOCK_ON_WRITE RAB$L_ROP RAB$V_RLK
Read locking	FDL: RMS:	CONNECT LOCK_ON_READ RAB$L_ROP RAB$V_REA
No locking	FDL: RMS:	CONNECT NOLOCK RAB$L_ROP RAB$V_NLK

7.2.3 Handling Record-Locking Conflicts

Application programs that use shared files must handle record locking conflicts that may occur when two or more record streams try to access the same record.

RMS provides three options for handling record locking conflicts:

• You can have the application program handle the record-locked error status (RMS$_RLK) returned by RMS when a record stream is denied access to a record.
• You can have the requesting service wait for access (wait-if-locked option).
• You can have the requesting service ignore the lock (read-regardless option).

The following table lists the options for having RMS handle record locking conflicts and how you select each option through the FDL and RMS interfaces.

Option	Interface	How to Select
Wait if locked	FDL: RMS:	CONNECT WAIT_FOR_RECORD RAB$L_ROP RAB$V_WAT
Wait timeout period	FDL: RMS:	CONNECT TIMEOUT_ENABLE and CONNECT TIMEOUT_PERIOD RAB$L_ROP RAB$V_TMO and RAB$B_TMO
Read regardless	FDL: RMS:	CONNECT READ_REGARDLESS RAB$L_ROP RAB$V_RRL

The following sections describe each of these options.

7.2.3.1 Handling the Record-Locked Error

When a service is denied record access because of a record conflict, it returns a record-locked error status (RMS$_RLK) that indicates the access attempt failed because the record was locked. One option is to have the application program pause briefly, and then try again to access the record.

Example 7-1 contains a program fragment written in VAX MACRO that demonstrates one method of implementing a short pause between attempts to access a locked record.

Example 7-1 Designing a Pause Between Attempts to Access a Record

. . . 10$: $GET RAB=INRAB ; Get the record BLBS R0,GOT_RECORD ; Branch on success CMPL R0,#RMS$_RLK ; Record-locked error? BNEQ ERROR ; Quit on other errors PUSHAL ONE_SECOND ; Pause for CALLS #1, G^LIB$WAIT ; One second BLBC R0,ERROR ; Quit on error BRB 10$ ; Try again for record . . .

For more information about process control techniques, see the OpenVMS System Services Reference Manual.

7.2.3.2 Waiting for Locked Records

Another option for handling record-locking conflicts is to use the wait-if-locked option to wait for the locked record to be released. When you take this option, the accessing service does not return until the record is released or until a specified wait period expires.

The optional wait period is established using the wait-timeout-period option in conjunction with the wait-if-locked option. If the specified wait period expires before the requesting service obtains access to the locked record, the requesting service discards the request. The requesting service returns a completion status indicating that it waited for the locked record but was not granted access within the specified time period (RMS$_TMO).

If you select the wait-if-locked option and the requesting service must wait to access the record, it returns an alternate success status that indicates that it had to wait (RMS$_OK_WAT).

7.2.3.3 Reading Regardless of Lock

The third choice available to you for handling record-locking conflicts involves using the read-regardless (of lock) option. This option allows the accessing service to ignore a lock that prohibits read access. If a lock is granted under the specified record-locking option, access is granted and the service returns with the specified lock. If the lock is denied, the read-regardless option allows the accessing service, Get or Find, to read the record, regardless of the lock. The service returns without a lock for all three file organizations, but the returned status depends on the file organization:

• For sequential files, the service returns RMS$_SUC.
• For relative and indexed files, the service returns alternate success status, RMS$_OK_RRL.

An application program might use the read-regardless option to avoid record locking conflicts when a coordinated view of a record is not necessary. This option can also be used to continue sequential reads through a locked record.

Note that when you use the read-regardless option with the wait-if-locked option and a wait timeout period, RMS acts on the read-regardless option only after the wait timeout expires.

7.2.4 Miscellaneous Record-Locking Options

This section describes two miscellaneous record-locking options---the manual-unlocking option and the lock-nonexistent-record option in a relative file.

7.2.4.1 Manual-Unlocking Option

The manual-unlocking option gives the application program explicit control over releasing a record lock established by the Get service, the Find service, or the Put service as described in Section 7.2.1.

Even if you select the manual-unlocking option, RMS unlocks affected records when a record stream is disconnected (Disconnect service), or when a file is closed (Close service). Other record operations, including operations that result in errors, do not unlock the record.

To manually release record locks, the application program can invoke the Free service to unlock all record locks held by a record stream, or it can invoke the Release service to selectively release record locks, using the record's RFA.

Manual unlocking is useful when you have to modify multiple records as part of a single transaction. For example, assume the application program must modify two related but separate records. Assume, too, that the modified first record must not be accessed by another record stream until modifications to the second record are completed.

While the program modifies the first record, it uses the manual-unlocking option to hold the lock on the modified first record. It then proceeds to modify the second record while still maintaining a lock on the first record. By using manual unlocking, the application program can restore the original contents of the first record if the update to the second record fails, thereby maintaining data integrity.

7.2.4.2 Lock-Nonexistent-Record Option

The lock-nonexistent-record option applies only to random accessing of relative files. Relative files have a static physical structure made up of record cells in contrast to sequential files and indexed files, which have a dynamic structure. The record cells may or may not contain records. A record may have been deleted from a cell, or the cell may be empty (that is, it never contained a record). In either case, the record cells are accessible to the application program.

Typically, if a record stream tries to access and lock an empty cell in a relative file using random access, the accessing service returns a record-not-found error status (RMS$_RNF). However, if the lock-nonexistent-record option is selected, the accessing service returns an alternative success status (RMS$_OK_RNF) indicating that the record stream accessed a cell that never contained a record. If the cell contains a deleted record, RMS returns the deleted record with an alternate success status (RMS$_OK_DEL) to indicate that a deleted record was accessed.

The lock-nonexistent-record option prevents other record streams from putting a record into an empty cell until the locking record stream puts a record in it or releases the record lock. Any other record stream that tries to access the cell to put data into it receives a record-locked status (RMS$_RLK). If the record stream that has the lock puts a record into the cell, RMS returns an alternate success status (RMS$_OK_ALK) indicating that the cell was already locked. In general, the RMS$_OK_ALK status is returned when a service tries to lock a record that the current record stream has already locked. This also applies to the Put service, which locks and unlocks the record in one record operation.

The next table lists miscellaneous record-locking options and how you select each option through the FDL and RMS interfaces:

Option	Interface	How to Select
Manual unlocking	FDL: RMS:	CONNECT MANUAL_UNLOCKING RAB$L_ROP RAB$V_ULK
Lock nonexistent record	FDL: RMS:	CONNECT NONEXISTENT_RECORD RAB$L_ROP RAB$V_NXR

	privacy and legal statement
4506PRO_021.HTML