Compaq COBOL
User Manual

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

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.