# Compaq COBOL
User Manual

Previous | Contents | Index

## 8.3.5 Specifying File Access Using Compaq Standard File Sharing

Compaq standard file sharing is summarized in this section and fully described in the Compaq COBOL Reference Manual (Environment Division and Procedure Division chapters).

You use the ALLOWING clause of the OPEN statement to specify what other access streams are allowed to access that file. The forms of OPEN ALLOWING are as follows:

- OPEN ALLOWING NO OTHERS---Locks the file for exclusive access. Attempts by other access streams to access the file cause a file lock condition.
- OPEN ALLOWING READERS---Locks the file against operations that indicate intended write access (OPEN I-O and OPEN EXTEND). Other streams can use the OPEN INPUT statement to view the file. No updaters are permitted.
  On Tru64 UNIX, this lock is limited for INDEXED files, as follows:
  - Any stream

    > If automatic record locking was requested, the file has now been opened with manual record locking in an attempt to process READERS.

  - First stream

    > If the open mode was INPUT (reader), subsequent non-exclusive updaters will get access to the file at OPEN time, but they will not be able to update the file at the record level.
    > If the mode is EXTEND, I-O, or OUTPUT (updater), the file lock acquired will not exclude other updaters that have specified full sharing of the file (with ALLOWING {ALL,UPDATERS,WRITERS}).

  - Subsequent stream

    > If the mode is EXTEND or OUTPUT (updater), access to the file is granted instead of denied when a previous updater stream has specified full sharing of the file (with ALLOWING {ALL,UPDATERS,WRITERS}).
    > If the mode is INPUT (reader), access to the file is granted instead of denied when a previous updater stream has specified full (ALL/UPDATERS/WRITERS) or partial (READERS) sharing of the file.
    > If the mode is I-O, access is denied as expected.

  <>
- OPEN ALLOWING WRITERS or UPDATERS or ALL---Allows access by other streams. Other access streams can open the file in INPUT, EXTEND, and I-O modes.

Compaq COBOL also permits a list of OPEN ALLOWING options, separated by commas. The list results in the following equivalent ALLOWING specifications:

- ALLOWING WRITERS, UPDATERS becomes ALLOWING ALL
- ALLOWING READERS, UPDATERS becomes ALLOWING UPDATERS

The first access stream uses the ALLOWING clause to specify what other access streams can do. When the second and subsequent access streams attempt to open the file, the following checks occur:

1. The allowed options of this access stream are checked against the intended access of the previous streams.
2. The intended access of this access stream is checked against the allowed access of the previous streams.

For example, if the first access stream specifies the ALLOWING READERS clause, then a subsequent access stream that opens the file ALLOWING NO OTHERS would fail. Also, if the first access stream opens the file ALLOWING READERS, the following access stream that opens the file ALLOWING ALL and WITH I-O mode would fail, because the clause option and the I-O mode declare write intent to the file.

If you do not specify an ALLOWING clause on the OPEN statement, the default for files opened for INPUT is ALLOWING READERS, and the default for files opened for I-O, OUTPUT, or EXTEND mode is ALLOWING NO OTHERS.

Describing Types of Access Streams

You can establish several types of access streams. For example, two programs opening the same file represent two access streams to that file. Both programs begin with the file open, perform record operations, and then close the file.

Combining Related File-Sharing Criteria

This section summarizes the relationships among three of the file-sharing criteria (the first file-sharing requirement, disk residency, is not included).

The following chart shows the file protection and open mode requirements. For example, the file protection privilege READ (R) permits OPEN INPUT.

File Protection | Open Mode
--- | ---
R | INPUT
W | OUTPUT, EXTEND
RW | I-O, INPUT, OUTPUT, EXTEND

Remember that you specify intended operations through the first access stream. For the second and subsequent shared access to a file, you use the access intentions (open modes) and the ALLOWING clause to determine if and how a file is shared. Note that some streams can be locked out if their intentions are not compatible with those of the streams that have already been allowed entry to the file.

On OpenVMS, Table 8-1 shows the valid and invalid OPEN ALLOWING combinations between first and subsequent access streams. (The subsequent table is the equivalent for Tru64 UNIX systems.) The table assumes no file protection violations on the first stream.

Table 8-1 File-Sharing Options (OpenVMS)
FIRST STREAM | SUBSEQUENT STREAM
--- | ---
Open mode: Allowing: | UPDATE ALL | UPDATE READERS | UPDATE NONE | INPUT ALL | INPUT READERS | INPUT NONE | OUTPUT ALL READERS NONE
UPDATE ALL | G | 3 | 2 | G | 3 | 2 | 5
UPDATE READERS | 4 | 3,4 | 2 | G | 3 | 2 | 5
UPDATE NONE | 1 | 1,3 | 1,2 | 1 | 1,3 | 1,2 | 5
INPUT ALL | G | G | 2 | G | G | 2 | 5
INPUT READERS | 4 | 4 | 2 | G | G | 2 | 5
INPUT NONE | 1 | 1 | 1,2 | 1 | 1 | 1,2 | 5
OUTPUT ALL | G | 3 | 2 | G | 3 | 2 | 5
OUTPUT READERS | 4 | 3,4 | 2 | G | 3 | 2 | 5
OUTPUT NONE | 1 | 1,3 | 1,2 | 1 | 1,3 | 1,2 | 5

Legend
UPDATE | OPEN EXTEND or OPEN I-O
INPUT | OPEN INPUT
OUTPUT | OPEN OUTPUT
ALL | ALLOWING ALL or ALLOWING UPDATERS or ALLOWING WRITERS
READERS | ALLOWING READERS
NONE | ALLOWING NO OTHERS
G | Second stream successfully opens and file sharing is granted.
1 | Second stream is denied access to the file because the first stream requires exclusive access (the first stream specified NO OTHERS).
2 | Second stream is denied access to the file because the second stream requires exclusive access (the second stream specified NO OTHERS).
3 | Second stream is denied access to the file because the first stream intends to write, while the second stream specifies read-only sharing.
4 | Second stream is denied access to the file because the second stream intends to write, while the first stream specifies read-only sharing.
5 | No sharing; second will create new file version with OPEN OUTPUT.

<>

On Tru64 UNIX, Table 8-2 shows the valid and invalid OPEN ALLOWING combinations between first and subsequent access streams. The table assumes no file protection violations on the first stream.

Table 8-2 File-Sharing Options (Tru64 UNIX)
FIRST STREAM | SUBSEQUENT STREAM
--- | ---
Open mode: Allowing: | UPDATE ALL | UPDATE READERS | UPDATE NONE | INPUT ALL | INPUT READERS | INPUT NONE
UPDATE ALL | G | 5 | 2 | G | 5 | 2
UPDATE READERS | 6 | 3,4 | 2 | G | 5 | 2
UPDATE NONE | 1 | 1,3 | 1,2 | 1 | 1,3 | 1,2
INPUT ALL | G | G | 2 | G | G | 2
INPUT READERS | 7 | 7 | 2 | G | G | 2
INPUT NONE | 1 | 1 | 1,2 | 1 | 1 | 1,2

Legend
UPDATE | OPEN EXTEND or OPEN I-O
INPUT | OPEN INPUT
OUTPUT | OPEN OUTPUT
ALL | ALLOWING ALL or ALLOWING UPDATERS or ALLOWING WRITERS
READERS | ALLOWING READERS
NONE | ALLOWING NO OTHERS
G | Second stream successfully opens and file sharing is granted.
1 | Second stream is denied access to the file because the first stream requires exclusive access (the first stream specified NO OTHERS).
2 | Second stream is denied access to the file because the second stream requires exclusive access (the second stream specified NO OTHERS).
3 | Second stream is denied access to the file because the first stream intends to write, while the second stream specifies read-only sharing.
4 | Second stream is denied access to the file because the second stream intends to write, while the first stream specifies read-only sharing.
5 | No sharing; second will create new file version with OPEN OUTPUT.
6 | For indexed files, when the first stream allows READERS, file lock does not exclude updaters allowing sharing. For files other than indexed, 4 applies.
7 | For indexed files, the second stream is granted access but cannot update the file. For files other than indexed, 4 applies.

<>

In the following example, three streams illustrate some of the file-sharing rules:

    STREAM 1           OPEN INPUT ALLOWING ALL
    STREAM 2           OPEN INPUT ALLOWING READERS
    STREAM 3           OPEN I-O ALLOWING UPDATERS

Stream 1 permits ALLOWING ALL; thus stream 2 can read the file. However, the third stream violates the intent of the second stream, because OPEN I-O implies a write intention that stream 2 disallows. Consequently, the third access stream receives a file locked error.

## 8.3.6 Error Handling for File Sharing

This section describes error conditions, checking file operations for success or failure, some considerations when you specify the OPEN EXTEND statement, and related potential errors.

Error Conditions

Whether the syntax is X/Open standard (Alpha) or Compaq standard, any file contention error results in an unsuccessful statement for which a USE procedure will be invoked. A "file-locked" condition results in an I-O status code of 91.

On Alpha, it is invalid to specify both X/Open and Compaq standard file sharing for the same file connector. Any attempts are flagged by the compiler when they are detectable in a single compilation unit. Across compilation units, the run-time system detects and reports such violations. This restriction is true for explicit and implicit (default) usage. <>

Checking File Operations

You can check the success or failure of a file open operation by using the File Status value (or, on OpenVMS systems, the RMS-STS value in a Compaq COBOL special register called RMS-STS).

Table 8-3 illustrates the file status values you frequently use in a file-sharing environment.

Table 8-3 File Status Values Used in a File-Sharing Environment
File Status Value | Meaning
--- | ---
00 | Successful operation
30 | File protection violation
91 | File is locked

File Status 00 indicates the completion of a successful operation.

File Status 30 might result from a violation of the file protection codes described in Section 8.3.2. To correct this condition, the file owner must reset the protection on the file or the directory that contains the file.

File Status 91 indicates that a previous access stream has denied access to the file. That previous access stream opened the file with locking attributes that conflict with the OPEN statement of the subsequent stream.

You can obtain the values that apply to file-sharing exceptions (or to successful file-sharing operations), as shown in Example 8-2.

Example 8-2 Program Segment for File Status Values

    FILE-CONTROL.
        SELECT FILE-NAME ASSIGN TO "fshare.dat"
               FILE STATUS IS FILE-STAT.

    WORKING-STORAGE SECTION.
    01  FILE-STAT PIC XX.
        88 FILE-OPENED VALUES "00", "05", "07".
        88 FILE-LOCKED VALUE  "91".
    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
            IF FILE-LOCKED
               CONTINUE
            ELSE
            .
            .
            .
            END-IF.
    END DECLARATIVES.
        .
        .
        .
    OPEN-FILES.
          OPEN I-O FILE-NAME.
          IF NOT FILE-OPENED
             PERFORM CHECK-OPEN.
          .
          .
          .
    CHECK-OPEN.
          IF FILE-LOCKED
             MOVE 1 to RETRY-COUNT
             PERFORM RETRY-OPEN UNTIL FILE-OPENED OR
                                      RETRY-COUNT > MAX-RETRY
             IF FILE-LOCKED AND RETRY-COUNT > MAX-RETRY
                DISPLAY "File busy...please try again later"
                STOP RUN
             END-IF
          END-IF.

    * handle other possible errors here
          .
          .
          .
    RETRY-OPEN.
         OPEN I-O FILE-NAME.
         add 1 to RETRY-COUNT.

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

Table 8-4 RMS-STS Values Used in a File-Sharing Environment (OpenVMS)
RMS-STS Value | Meaning
--- | ---
RMS$_DIR | Error in directory name
RMS$_DNF | Directory not found
RMS$_DNR | Device not ready or not mounted
RMS$_DUP | Duplicate key detected (DUP not set)
RMS$_ENQ | System service request failed
RMS$_EOF | End of file detected
RMS$_FLK 1 | File is locked
RMS$_FNF | File not found
RMS$_FUL | Device full (insufficient space)
RMS$_KEY | Invalid record number key or key value
RMS$_KRF | Invalid key of reference for $GET/$FIND
RMS$_KSZ | Invalid key size for $GET/$FIND
RMS$_OK_RLK | Record locked but read anyway
RMS$_OK_RRL | Record locked against read but read anyway
RMS$_PRV 2 | File protection violation
RMS$_RAC | Invalid record access mode
RMS$_REX | Record already exists
RMS$_RLK | Record currently locked by another stream
RMS$_RNF | Record not found
RMS$_RNL | Record not locked
RMS$_RSZ | Invalid record size
RMS$_SNE | File sharing not enabled
RMS$_SPE | File$_sharing page count exceeded
RMS$_SUC 3 | Successful operation
RMS$_WLK | Device currently write locked

1Corresponds to File Status Value of 91
2Corresponds to File Status Value of 30
3Corresponds to File Status Value of 00

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:

Example 8-3 Program Segment for RMS-STS Values (OpenVMS)

    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.

Previous | Next | Contents | Index