[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP COBOL
User Manual

Previous Contents Index

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, I64) or HP 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 and I64, it is invalid to specify both X/Open and HP 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 an HP 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.

Previous Next Contents Index