HP OpenVMS Systems Documentation

HP COBOL
User Manual

Note that User 2 could have employed AUTOMATIC record locking just as well. In this case, manual and automatic locking work similarly. <>

8.4.2 Hewlett-Packard Standard Record Locking

Automatic Record Locking (HP Standard)

You specify automatic record locking by using the ALLOWING phrase of the OPEN statement. The lock is applied when you access the record and released when you deaccess the record. In automatic record locking the access stream can have only one record locked at a time and can apply only one type of lock to the records of the file.

You deaccess a record by using the next READ operation, a REWRITE or a DELETE operation on the record, or by closing the file. In addition, you can release locks applied by automatic record locking by using the UNLOCK statement.

In automatic record-locking mode, you can release the current record lock by using an UNLOCK RECORD statement or an UNLOCK ALL RECORDS statement. (On Tru64 UNIX systems for indexed files only, there is no current record lock.) However, because in automatic record locking you can lock only one record at a time, the UNLOCK ALL RECORDS statement unnecessarily checks all records for additional locks.

The sample program in Example 8-5 uses automatic record locking. The program opens the file with I-O ALLOWING ALL. Another access stream in another program also opens the file with INPUT ALLOWING ALL.

Note that two parallel access streams use the program in Example 8-5.

If the first access stream is updating records in random order, a record lock can occur to the second stream from the READ until the REWRITE statement of the first stream. Record locks can also occur to the first stream when the second stream reads a record and the first stream tries to read the same record.

SELECT FILE-1
     ORGANIZATION IS RELATIVE
     ASSIGN TO "SHAREDAT.DAT"
     .
     .
     .
PROCEDURE DIVISION.
     OPEN I-O FILE-1 ALLOWING ALL.
     READ FILE-1  AT END DISPLAY "end".
          .
          .
          .
     REWRITE FILE-1-REC.
     CLOSE FILE-1.
     STOP RUN.

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.

Manual Record Locking (HP Standard)

You specify manual record locking by using the APPLY LOCK-HOLDING clause (in the I-O-CONTROL paragraph), the OPEN ALLOWING statement, and the ALLOWING clauses on the HP COBOL record operations (except DELETE). Manual record locking allows greater control of locking options by permitting users to lock multiple records in a file and by permitting different types of locking to apply to different records.

Manual record locking applies the specified lock when you access the record and releases the lock when you unlock the record.

When you specify manual record locking, you must use all of the following clauses:

• An APPLY LOCK-HOLDING clause in the I-O CONTROL paragraph
• An OPEN ALLOWING clause at file open time
• An ALLOWING clause on each record operation (except DELETE)²

The possible ALLOWING clauses for the record operations (that is, the READ, WRITE, REWRITE, and START statements) are as follows:

• ALLOWING NO OTHERS²---Locks records for exclusive access. Others cannot perform READ, WRITE, DELETE, or UPDATE statements. This clause constitutes a lock for write and does not allow readers.
• ALLOWING READERS---Locks records against WRITE, REWRITE, and DELETE access by all streams including the stream that issues the statement. Others can perform READ statements.
• ALLOWING UPDATERS²---Does not apply any locks to the records. Others can perform READ, REWRITE, and DELETE statements. This clause constitutes a no record lock condition. ²

However, if the file's OPEN mode is INPUT, using the ALLOWING clause on the record operation does not lock the record.

On Tru64 UNIX systems, for indexed files only, the WRITE, REWRITE, and START statements do not acquire a record lock.

On Tru64 UNIX systems for indexed files only, ALLOWING READERS is treated as ALLOWING NO OTHERS if the file is opened in I-O mode or as ALLOWING ALL if the file is opened in INPUT mode. <>

Table 8-5 shows the valid and invalid ALLOWING combinations for manual record locking. The columns represent the lock held, and the rows represent the lock requested.

Legend: Y = Subsequent stream executes successful I-O operation
        N = Subsequent stream I-O operation is unsuccessful (File Status 92)

Example 8-6 uses manual record locking. The file is opened with the ALLOWING ALL clause. The records are read but do not become available to other access streams because of the lock applied by the READ statement (READ...ALLOWING NO OTHERS). When the UNLOCK is executed, the records can be read by another access stream if that stream opens the file allowing writers.

FILE-CONTROL.
    SELECT FILE-1
         ORGANIZATION IS RELATIVE
         ASSIGN "SHAREDAT.DAT".
          .
          .
          .
    I-O-CONTROL.
         APPLY LOCK-HOLDING ON FILE-1.
          .
          .
          .
PROCEDURE DIVISION.
BEGIN.
     OPEN I-O FILE-1 ALLOWING ALL.
          .
          .
          .
     READ FILE-1 ALLOWING NO OTHERS AT END DISPLAY "end".
          .
          .
          .
     REWRITE FILE-1-REC ALLOWING NO OTHERS.
          .
          .
          .
     UNLOCK FILE-1 ALL RECORDS.
     CLOSE FILE-1.
     STOP RUN.

In manual record locking, you release record locks by the UNLOCK statement or when you close the file (either explicitly or implicitly; when you close a file, any existing record lock is released automatically). The UNLOCK statement provides for either releasing the lock on the current record (on OpenVMS systems with UNLOCK RECORD) or releasing all locks currently held by the access stream on the file (UNLOCK ALL RECORDS). (On Tru64 UNIX systems for indexed files only, there is no current record lock.)

When you access a shared file with ACCESS MODE IS SEQUENTIAL and use manual record locking, the UNLOCK statement can cause you to violate either of the following statements: (1) the REWRITE statement rule that states that the last input-output statement executed before the REWRITE must be a READ or START statement, or (2) the DELETE statement rule that states that the last input/output statement executed before the DELETE statement must be a READ. You must lock the record before it can be rewritten or deleted.

Releasing Locks on Deleted Records

In automatic record locking, the DELETE operation releases the lock on the record. In manual record-locking mode, you can delete a record using the DELETE statement but still retain a record lock. You must use the UNLOCK ALL RECORDS statement to release the lock on a deleted record.

If a second stream attempts to access a deleted record that retains a lock, the second stream will receive either a "record not found" exception or a hard lock condition. (See Section 8.4.3 for information on hard lock conditions.)