HP OpenVMS Systems Documentation

HP COBOL
User Manual

On OpenVMS, if another stream attempts to REWRITE a deleted record for which there is a retained lock, the type of exception that access stream receives depends on its file organization. If the file organization is RELATIVE, the access stream receives the "record locked" status. If the file organization is INDEXED, the access stream succeeds (receives the success status).

In relative files, the lock is on the relative cell (record) and cannot be rewritten until the lock is released. On indexed files, the lock is on the record's file address (RFA) of the deleted record, so a new record (with a new RFA) can be written to the file. <>

Bypassing a Record Lock

When you use manual record locking, you can apply a READ REGARDLESS or START REGARDLESS statement to bypass any record lock that exists. READ REGARDLESS reads the record and applies no locks to the record. START REGARDLESS positions to the record and applies no locks to the record. If the record is currently locked by another access stream, a soft record lock condition can be detected by a USE procedure. (See Section 8.4.3 for information on soft record locks.)

You use READ REGARDLESS or START REGARDLESS when: (1) a record is locked against readers because the record is about to be written, but (2) your access program needs the existing record regardless of the possible change in its data.

When you close a file, any existing record lock is released automatically. The UNLOCK RECORD statement releases the lock only on the current record on OpenVMS systems, which is the last record you successfully accessed. On Tru64 UNIX systems for indexed files only, there is no current record lock.

8.4.3 Error Handling for Record Locking

This section describes the locking error conditions and the two kinds of locks: hard and soft.

Any record contention error results in an unsuccessful statement for which a USE procedure will be invoked. A "record-locked" condition results in an I-O status code of 92.

Interpreting Locking Error Conditions

Two record-locking conditions (hard and soft record lock) indicate whether a record was transferred to the record buffer. HP COBOL provides the success, failure, or informational status of an I/O operation in the file status variable.

Hard Record Locks

A hard record lock condition, which causes the file status variable to be set to 92, indicates that the record operation failed and the record was not transferred to the buffer. A hard record lock results from a scenario such as the one shown in the following steps, which uses HP standard manual record-locking mode:

1. Program A opens the file I-O ALLOWING ALL.
2. Program A reads a record ALLOWING NO OTHERS.
3. Program B opens the file I-O ALLOWING ALL.
4. Program B tries to access the same record as A.
5. Program B receives a hard record lock condition.
6. The record is not accessible to Program B.
7. Program B's File Status variable is set to 92.
8. Program B's USE procedure is invoked.
9. Program A continues.

The record was not available to Program B.

On Tru64 UNIX, for INDEXED files, READ with the ALLOWING UPDATERS clause as well as any START statement will not detect a locked record. Potential conflicts do not trigger a hard lock condition, only actual conflicts do. <>

Soft Record Locks

Soft record locks can occur only with HP standard record locking. A soft record lock condition, which causes the file status variable to be set to 90, indicates that the record operation was successful, the record was transferred to the buffer, and a prior access stream holds a lock on that record. A soft record lock can be detected by a USE procedure. This condition occurs in either of the following two situations:

• When a record is accessed in a file that has been opened in INPUT mode, a soft record lock condition may occur if the record has been locked by a prior stream. This depends on the type of lock held by the first stream and requested by the subsequent stream.
• In the second situation, a stream attempts to access a record that has been locked by another stream. The second stream employs a READ REGARDLESS or START REGARDLESS statement (see Bypassing a Record Lock), which overrides the hard record lock and allows access to the record. The second stream sucessfully reads the record and receives a soft record lock. (The second stream cannot update the record.)

For example, a soft record lock results from a situation such as the following, which uses automatic record-locking mode:

1. Program A opens the file I-O ALLOWING READERS.
2. Program A reads a record.
3. Program B opens the file INPUT ALLOWING ALL.
4. Program B reads the same record.
5. Program B receives a soft record lock condition. The record is accessible to Program B.
6. Program B's File Status variable is set to 90.
7. On OpenVMS, Program B's USE procedure (if any) is invoked. <>
8. Programs A and B continue.

The record was available to Program B.

A manual record-locking environment is required in order for the REGARDLESS and ALLOWING options to be used on a READ statement. The READ REGARDLESS and START REGARDLESS statements should be used only when the access program clearly needs the existing record regardless of the possible imminent change in its data. For a full description of the OPEN, READ, and START statements and their options, refer to the HP COBOL Reference Manual.

Soft Record Locks and Declarative USE Procedures

If a soft record lock occurs, the values of the following variables for the current file are undefined until the execution of any applicable Declarative USE procedure is complete:

• Record buffer
• RELATIVE KEY
• DEPENDING ON

These variables remain undefined if the Declarative USE procedure terminates with an EXIT PROGRAM statement.

Hard Record Locks and File Position During Sequential Access

If a hard record lock condition occurs for a sequential READ statement, the file position indicator is unaffected. If the application must continue reading records, the following actions may be taken:

• HP standard record locking
  START or READ REGARDLESS may be used to bypass a hard record lock (see Soft Record Locks).
• X/Open standard record locking
  For indexed and relative files, a START statement, with the appropriate KEY clause, may be used to skip the record that is locked. On Alpha and I64, because X/Open START statements do not detect or acquire a record lock, some file processing may still be possible. However, users must be aware that this is not typical sequential file processing, as not all records will be retrieved.

Error Handling Example

Example 8-7 is an example of processing locked record conditions.

FILE-CONTROL.
    SELECT file-name ASSIGN TO "fshare.dat"
           FILE STATUS IS file-stat.

WORKING-STORAGE SECTION.
01  file-stat PIC XX.
    88 record-ok     VALUES "00", "02", "04".
    88 record-locked VALUE  "92".
01  RETRY-COUNT  PIC 9(2).
01  MAX-RETRY    pic 9(2) VALUE 10.
    .
    .
    .
PROCEDURE DIVISION.
DECLARATIVES.
FILE-USE SECTION.  USE AFTER STANDARD EXCEPTION PROCEDURE ON file-name.
FILE-ERR.
* need declaratives to trap condition, but let main code process it.
* invalid key clause does not apply

        IF record-locked
           continue
        ELSE
           .
           .
           .
        END-IF.
END DECLARATIVES.
MAIN-BODY SECTION.
BEGIN.
    DISPLAY "From main-body".

    .
    .
    .
GET-RECORD.
      READ file-name.
      IF NOT record-ok
         PERFORM check-read.
      .
      .
      .
CHECK-READ.
      IF record-locked
         MOVE 1 to retry-count
         PERFORM retry-read UNTIL record-ok OR
                                  retry-count > max-retry
         IF record-locked AND retry-count > max-retry
            DISPLAY "Record is unavailable...enter new record to retrieve: "
                     WITH NO ADVANCING
            ACCEPT record-id
            GO TO get-record
         END-IF
      END-IF.

* handle other possible errors here

RETRY-READ.
     READ file-name.
     add 1 to retry-count.