This chapter includes the following information about sharing files and protecting records for sequential, relative, and indexed files:

• Controlling access to files and records ( Section 8.1)
• Choosing X/Open standard or Compaq standard file sharing and record locking ( Section 8.2)
• Ensuring successful file sharing ( Section 8.3)
• Using record locking to control access to records ( Section 8.4)

In a data manipulation environment where many users and programs access the same data, file control must be applied to protect files from nonprivileged users, to permit the desired degree of file sharing, and to preserve data integrity in the files. For example, in Figure 8-1 many users and programs want to access data found in FILE-A.

Figure 8-1 Multiple Access to a File

File sharing and record locking allow you to control file and record operations when more than one access stream (the series of file and record operations being performed by a single user, using a single file connector) is concurrently accessing a file, as in Figure 8-1.

A Compaq COBOL program, via the I/O system, can define one or more access streams. You create one access stream with each OPEN file-name statement. The access stream remains active until you terminate it with the CLOSE file-name statement or until your program terminates.

File sharing allows multiple users (or access streams) to access a single file concurrently. The protection level of the file, set by the file owner, determines which users can share a file.

Record locking controls simultaneous record operations in files that are accessed concurrently. Record locking ensures that when a program is writing, deleting, or rewriting a record in a given access stream, another access stream is allowed to access the same record in a specified manner.

Figure 8-2 illustrates the relationship of record locking to file sharing.

Figure 8-2 Relationship of Record Locking to File Sharing

File sharing is a function of the file system, while record locking is a function of the I/O system. The file system manages file placement and the file-sharing process, in which multiple access streams simultaneously access a file. The I/O system manages the record-sharing process and provides access methods to records within a file. This includes managing the record-locking process, in which multiple access streams simultaneously access a record.

You must have successful file sharing before you can consider record locking.

In Compaq COBOL, the file operations begin with an OPEN statement and end with a CLOSE statement. The OPEN statement initializes an access stream and specifies the mode. The CLOSE statement terminates an access stream and can be either explicit (stated in the program) or implicit (on program termination).

The record operations for Compaq COBOL that are associated with record locking are as follows:

READ
START
WRITE
REWRITE
DELETE
UNLOCK

Compaq COBOL offers two methods of controlling potential conflicts of multi-user file access between simultaneously running processes:

• Compaq standard, which is compatible with Compaq COBOL for OpenVMS VAX behavior¹
• X/Open standard, which conforms to the X/Open CAE Specification: COBOL Language and which offers X/Open portability

Both effectively control potential conflicts of file access between simultaneously running COBOL processes. Both offer locking for all file types: sequential, relative, and indexed.

The Compaq COBOL compiler determines whether to apply X/Open standard behavior or Compaq standard behavior for any file connector on the basis of the syntax used for that file connector. The following syntax identifies X/Open standard:

LOCK MODE (SELECT statement)
WITH LOCK (OPEN statement)
WITH [NO] LOCK (READ statement)
UNLOCK RECORDS

The following syntax identifies Compaq standard:

APPLY LOCK-HOLDING (Environment Division)
ALLOWING¹
REGARDLESS¹ (Procedure Division)
UNLOCK ALL

For any given file connector, any subsequent I-O locking syntax in your program must be consistent: X/Open standard and Compaq standard file sharing/record locking (implicit or explicit) cannot be mixed for the same file connector.

If a program includes any ambiguous semantics for I-O verbs (that is, no locking syntax for verbs for which the two standards provide different default behavior) and the previous code does not use Compaq or X/Open standard-specific syntax for that file connector, the compiler determines which standard to use by applying the specification (or default) from your compile command line, as follows:

• The -std [no]xopen flag on the cobol command for the Tru64 UNIX operating system
• The /STANDARD=[NO]XOPEN qualifier on the COBOL command for the OpenVMS Alpha operating system

If you do not specify the flag or qualifier, the default is noxopen (Compaq standard) file sharing and record locking.

If you want X/Open file sharing and record locking and have not used the LOCK MODE clause, therefore, you should specify /STANDARD=XOPEN or -std xopen to ensure X/Open standard behavior in instances of conflicting default semantics. Note, however, that the qualifier/flag comes into effect only when the explicit syntax has not determined the usage.

8.3 Ensuring Successful File Sharing

Successful file sharing requires that you:

• Provide disk residency for the file.
• Use the operating system file protection facility, namely the contents of /etc/groups (on Tru64 UNIX systems) or the UIC (on OpenVMS Alpha systems).
• Determine the intended access mode to the file (Compaq COBOL open modes).
• Indicate the file access allowed by other streams, using X/Open standard or Compaq standard syntax to specify file sharing.

The remainder of this section describes these requirements in more detail.

8.3.1 Providing Disk Residency

Only files that reside on a disk can be shared. In Compaq COBOL you can share sequential, relative, and indexed files.

8.3.2 Using File Protection

By applying the appropriate file permissions at the operating system level, the owner of a file determines how other users can access the file. An owner can permit different types of file access for different users or groups.

The four types of file access are as follows:

• READ---Permits the reading of the records in the file.
• WRITE---Permits updating or extending the records in the file.
• EXECUTE---Applies to on-disk volume protection and image execution and is therefore not applicable to a Compaq COBOL program except through system service routines.
• DELETE---Permits deletion of the file and is therefore not applicable to a Compaq COBOL program (since Compaq COBOL has no delete file facility) except through system service routines.

In the OpenVMS Alpha file protection facility, four different categories of users exist with respect to data structures and devices. A file owner determines which of the following user categories can share the file:

• SYSTEM---Users of the system whose group numbers are in the range 0 to the value of the MAXSYSGROUP parameter or who have certain I/O-related privileges
• OWNER---Users of the system whose UIC group and member numbers are identical to the UIC of the file owner
• GROUP---Users of the system whose group number is identical to the group number of the file owner
• WORLD---All other users of the system who are not included in the previous categories

The OpenVMS Alpha operating system applies a default protection to each newly created file unless the owner specifically requests modified protection.

For more information on file protection, refer to the OpenVMS User's Manual. <>

On Tru64 UNIX systems, the three types of file access are as follows:

• Read---Permits the reading of the records in the file.
• Write---Permits updating or extending the records in the file.
• Execute---Applies to image execution and is therefore not applicable to a Compaq COBOL program.

There are three categories of users:

• User---Owner of the file
• Group---Users in the same group as the owner
• Others---All other users

Compaq COBOL determines the access permission for newly created files in the following manner:

1. The default access permissions are granted:
   • User and Group are granted read and write access.
   • Others are granted read access.
2. Then the file mode creation mask of the process creating the file is taken into account.

Additional information on file permission can be found in the Tru64 UNIX man pages for chmod, ls, open, and umask . <>

8.3.3 Determining the Intended Access Mode to a File

Once you establish disk residency and permission for a file, you can consider how the stream intends to access the file. You specify this intention by using the Compaq COBOL open and access modes.

The Compaq COBOL open modes are INPUT, OUTPUT, EXTEND, and I-O. The Compaq COBOL access modes are SEQUENTIAL, RANDOM, and DYNAMIC. The combination of open and access modes determines the operations intended on the file.

You must validate your Compaq COBOL intention against the file protection assigned by the file owner. For example, to use an OPEN INPUT clause requires that the file owner has granted read access privileges to the file. To use an OPEN OUTPUT or EXTEND clause requires write access privileges to the file. To use an OPEN I-O clause requires both read and write access privileges.

The following chart shows the relationship between open and access modes and intended Compaq COBOL operations. The word ANY indicates that all three access methods result in the same intentions.

Open Mode	Access Mode	Intended COBOL Operations
INPUT	ANY	READ, START
OUTPUT	ANY	WRITE
I-O	SEQUENTIAL	READ, START, REWRITE, DELETE
	RANDOM/DYNAMIC	READ, START, REWRITE, DELETE, WRITE
EXTEND	SEQUENTIAL	WRITE

File protection and open mode access apply to both the unshared and shared (multiple access stream) file environments. A file protection and intent check is made when the first access stream opens a file (in the unshared file environment), and again when the second and subsequent access streams open the file (in the shared file environment).

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

X/Open standard file sharing is summarized in this section and fully described in the Compaq 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.

Example 8-1 X/Open Standard Lock Modes and Opening Files

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.

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.