HP OpenVMS Systems Documentation

HP COBOL
User Manual

On OpenVMS, Table 8-4 describes RMS-STS values used in a file-sharing environment.

You can obtain the values that apply to file-sharing exceptions (or to successful file-sharing operations) by using the VALUE IS EXTERNAL clause, as shown in Example 8-3:

WORKING-STORAGE SECTION.

01 RMS-SUC     PIC S9(9) COMP  VALUE IS EXTERNAL RMS$_SUC.
01 RMS-FLK     PIC S9(9) COMP  VALUE IS EXTERNAL RMS$_FLK.
   .
   .
   .
PROCEDURE DIVISION.
DECLARATIVES.
FILE-1-ERR SECTION.
    USE AFTER STANDARD EXCEPTION PROCEDURE ON FILE-1.
FILE-1-USE.
    EVALUATE RMS-STS OF FILE-1
      WHEN RMS-SUC      DISPLAY "successful operation"
      WHEN RMS-FLK      DISPLAY "file is locked - access denied".
   .
   .
   .<>

Specifying the OPEN EXTEND Statement in a File-Sharing Environment

If you specify an OPEN EXTEND in a file-sharing environment, be aware that the EXTEND results differ depending upon what file organization you use.

OPEN EXTEND with a Shared Sequential File

In a shared sequential file environment, when two concurrent access streams open the file in EXTEND mode, and both streams issue a write to the end of the file (EOF), the additional data will come from both streams, and the data will be inserted into the file in the order in which it was written to the file.

OPEN EXTEND with a Shared Relative File

You must use the sequential access mode when you open a relative file in extend mode. Sequential access mode for a relative file indicates that the record order is by ascending relative record number.

In sequential access mode for a relative file, the RELATIVE KEY clause of the WRITE statement is not used on record insertion; instead, the RELATIVE KEY clause acts as a receiving field. Consequently, after the completion of a write by the first access stream, the relative key field is set to the actual relative record number.

Figure 8-3 illustrates why this condition occurs.

Figure 8-3 Why a Record-Already-Exists Error Occurs

As the file operations begin, both access streams point to the end of file by setting record 4 as the highest relative record number in the file. When access stream 1 writes to the file, record 5 is created as the next ascending relative record number and 5 is returned as the RELATIVE KEY number.

When access stream 2 writes to the file, it also tries to write the fifth record. Record 5 already exists (inserted by the first stream), and the second access stream gets a record-exists error. Thus, in a file-sharing environment, the second access stream always receives a record-exists error. To gain access to the current highest relative record number, stream 2 must close the file and reopen it.

OPEN EXTEND with a Shared Indexed File

You must use the sequential file access mode when you open an indexed file in extend mode. Sequential access mode requires that the first additional record insertion have a prime record key whose value is greater than the highest prime record key value in the file.

In a file-sharing environment, you should be aware of and prepared for duplicate key errors (by using INVALID KEY and USE procedures), especially on the first write to the file by the second access stream.

Subsequent writes should also allow for duplicate key errors, although subsequent writes are not constrained to use keys whose values are greater than the highest key value that existed at file open time. If you avoid duplicate key errors, you will successfully insert all access stream records.

8.4 Ensuring Successful Record Locking

Once you meet all of the file-sharing criteria and you access a file, you can consider two record-locking modes that control access to records in a file:

• Automatic record locking---The system automatically releases an existing record lock whenever a new record is accessed and acquires a record lock whenever it reads a record in the file.
• Manual record locking---A file connector can hold a number of record locks simultaneously. Manual record locking is available only for relative or indexed files.

This section describes the X/Open standard method of specifying automatic or manual record locking.

Specifying Automatic Record Locking (X/Open Standard) (Alpha, I64)

You specify X/Open standard automatic record locking in the Environment Division by using LOCK MODE IS AUTOMATIC [WITH LOCK ON RECORD] on the SELECT statement. (The optional WITH LOCK ON RECORD clause has no effect and is for documentation only.) Subsequently, a record lock is acquired by the successful execution of a READ statement. (The WITH LOCK clause is not necessary on the READ; it is implied.)

A record lock is released by one of the following events:

• The successful execution of a subsequent I-O statement
• Using the UNLOCK statement
• Closing the file, implicitly or explicitly

In X/Open standard record locking, only the READ statement can acquire a lock. You can use the WITH NO LOCK phrase of the READ statement to prevent the acquiring of an automatic record lock.

For files opened in INPUT mode, READ and READ WITH LOCK statements do not acquire a record lock.

Specifying Manual Record Locking (X/Open Standard) (Alpha, I64)

You specify X/Open standard manual record locking in the Environment Division by using LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS on the SELECT statement. Manual record locking is available only for relative and indexed files.

For manual record locking, a record lock is acquired by specifying the WITH LOCK phrase on the READ statement. READ is the only operation that can acquire a lock. The record lock is released by one of the following events:

• Using the UNLOCK statement (any form of the UNLOCK statement unlocks all record locks held by the current access stream; there is no singular option)
• Closing the file, implicitly or explicitly

The WITH LOCK clause is ignored for files opened in INPUT mode. Locks are detected but not acquired.

Example 8-4 is a partial example of using both methods of X/Open standard record locking.

User 1 (Automatic Record Locking): ---------------------------------

FILE-CONTROL.
         SELECT FILE-1
              ORGANIZATION IS RELATIVE
              ASSIGN TO "SHAREDAT.DAT"
              LOCK MODE AUTOMATIC.
              .
              .
              .
PROCEDURE DIVISION.
BEGIN.
OPEN I-O FILE-1.
READ FILE-1.
              .
              .
              .
REWRITE FILE-1-REC.
CLOSE FILE-1.
STOP RUN.


User 2 (Manual Record Locking): ------------------------------

FILE-CONTROL
         SELECT FILE-1
              ORGANIZATION IS RELATIVE
              ASSIGN "SHAREDAT.DAT"
              LOCK MODE MANUAL LOCK ON MULTIPLE RECORDS.
              .
              .
              .

PROCEDURE DIVISION.
BEGIN.
OPEN I-O FILE-1.
              .
              .
              .
READ FILE-1 WITH LOCK.
REWRITE FILE-1-REC.
UNLOCK FILE-1.
CLOSE FILE-1.
STOP RUN.