HP OpenVMS Systems Documentation

HP COBOL
User Manual

After you provide disk residency, specify permission, and determine the access mode to a file, you can specify the access allowed to other streams through file-sharing and record-locking techniques. The remainder of this chapter describes this access control.

8.3.4 Specifying File Access Using X/Open Standard File Sharing (Alpha, I64)

X/Open standard file sharing is summarized in this section and fully described in the HP COBOL Reference Manual (Environment Division and Procedure Division chapters) and the X/Open CAE Specification: COBOL Language.

If you want a file in your COBOL program to utilize X/Open standard file sharing (probably for purposes of portability), you should include X/Open-specific syntax for the file in the Environment Division. Use one of the following:

LOCK MODE IS AUTOMATIC
LOCK MODE IS MANUAL
LOCK MODE IS EXCLUSIVE

You can also select X/Open file sharing by just specifying WITH LOCK on the OPEN or READ statements. However, it is recommended that you use the LOCK MODE clause to avoid ambiguity and maintain readability. If this is not done and any I-O verbs rely on default behavior that might result in ambiguity, you should compile your program with the X/Open option added to the compile command line.

Opened files can be exclusive or shareable, as specified by the LOCK MODE option of the SELECT clause (in the FILE-CONTROL paragraph of the Environment Division) or the OPEN statement. However, files opened in OUTPUT mode cannot be shared. To make a file shareable, specify one of the following:

• LOCK MODE IS AUTOMATIC [WITH LOCK ON RECORD]
• LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS (allowed only for indexed or relative files)

These forms allow other access streams to open the file.

To make the file unavailable to other processes, specify one of the following:

• LOCK MODE IS EXCLUSIVE
• WITH LOCK on the OPEN statement

This locks the file. Attempts by other access streams to open the file cause a file lock condition.

If the LOCK MODE clause and WITH LOCK phrase are both omitted, the default file sharing is as follows:

• Opened in INPUT mode: shareable
• Opened in I-O, EXTEND, or OUTPUT mode: exclusive

The WITH LOCK phrase overrides any LOCK MODE clause. This is useful to create an exclusive access stream for a file declared as shareable.

You can protect a shareable file's data by using record-locking syntax (described in Section 8.4.1).

Example 8-1 shows the use of X/Open standard file-sharing code and the results when files are opened.

     FILE-CONTROL.
         SELECT employee-file ASSIGN TO "EMPFIL"
                LOCK MANUAL LOCK ON MULTIPLE RECORDS.

         SELECT master-file ASSIGN TO "MASTFIL"
                LOCK AUTOMATIC.

         SELECT tran-file ASSIGN TO "TRANFIL"
                LOCK MODE IS EXCLUSIVE.

         SELECT job-codes ASSIGN TO "JOBFIL".
                .
                .
                .
     PROCEDURE-DIVISION.
     BEGIN.
     * The file is shareable per LOCK MODE specification:

          OPEN I-O employee-file.

     * The file is exclusive during this access stream, overriding the
     * LOCK MODE specification:

          OPEN I-O master-file WITH LOCK.

     * The file is exclusive per LOCK MODE; others cannot access it:

          OPEN INPUT tran-file.

     * The file defaults to exclusive; others cannot access it:

          OPEN EXTEND job-codes.   <>

Hewlett-Packard standard file sharing is summarized in this section and fully described in the HP 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.

HP 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.

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.