An applicable Declarative USE procedure executes whenever an I/O statement results in an exception condition (a file status value that does not begin with a zero (0)) and the I/O statement does not contain an AT END or INVALID KEY phrase. The AT END and INVALID KEY phrases take precedence over a Declarative USE procedure, but only for the I/O statement that includes the clause. For example, the AT END phrase takes effect only with File Status 10 and the INVALID KEY phrase takes effect only with File Status 23. Therefore, you can have specific I/O statement exception condition handling for a file and also include a Declarative USE procedure for general exception handling.

A Declarative USE procedure is a set of one or more special-purpose sections at the beginning of the Procedure Division. As shown in Example 7-6, the key word DECLARATIVES precedes the first of these sections, and the key words END DECLARATIVES follow the last.

Example 7-6 The Declaratives Skeleton

PROCEDURE DIVISION. DECLARATIVES. . . . END DECLARATIVES. MAIN-BODY SECTION. BEGIN. . . .

As shown in Example 7-7, a Declarative procedure consists of a section header, followed, in order, by a USE statement and one or more paragraphs.

Example 7-7 A Declarative USE Procedure Skeleton

. . . PROCEDURE DIVISION. DECLARATIVES. D0-00-FILE-A-PROBLEM SECTION. USE AFTER STANDARD ERROR PROCEDURE ON FILE-A. D0-01-FILE-A-PROBLEM. . . . D0-02-FILE-A-PROBLEM. . . . D0-03-FILE-A-PROBLEM. . . . END DECLARATIVES. MAIN-BODY SECTION. BEGIN. . . .

Declarative USE procedures can be either ordinary or global. Ordinary Declarative USE procedures have a limited scope; you can use them only in programs where they are originally introduced. Global Declarative USE procedures have a wider scope; you can use them in programs that introduce them as well as in programs that are contained within the introducing program.

In Compaq COBOL Declarative procedures, the conditions in the USE statements indicate when they execute. There are five conditions. One USE statement can have only one condition; therefore, if you need all five conditions in one program, you must use five separate USE procedures. These procedures and their corresponding conditions are as follows:

• File name---You can define a file name Declarative USE procedure for each file name. This procedure takes precedence over the next four procedures. It executes for any unsuccessful exception condition. (One USE statement can specify multiple file names.)
• INPUT---You can define only one INPUT Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for INPUT and (2) a file name Declarative USE procedure does not exist for that file.
• OUTPUT---You can define only one OUTPUT Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for OUTPUT and (2) a file name Declarative USE procedure does not exist for that file.
• INPUT-OUTPUT---You can define only one INPUT-OUTPUT Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for INPUT-OUTPUT (I-O) and (2) a file name Declarative USE procedure does not exist for that file.
• EXTEND---You can define only one EXTEND Declarative USE procedure for each program. This procedure executes for any unsuccessful exception condition if: (1) the file is open for EXTEND and (2) a file name Declarative USE procedure does not exist for that file.

Note that the USE statement itself does not execute; it defines the condition that causes the Declarative procedure to execute. Refer to the Compaq COBOL Reference Manual for more information about specifying Declarative procedures with the USE statement.

Example 7-8 shows you how to include a USE procedure for each of the conditions in your program. The example also contains explanatory comments for each.

Example 7-8 Five Types of Declarative USE Procedures

. . . PROCEDURE DIVISION. DECLARATIVES. ******************************************************** D1-00-FILE-A-PROBLEM SECTION. USE AFTER STANDARD ERROR PROCEDURE ON FILE-A. * * * If any file-access statement for FILE-A results in an * error, D1-00-FILE-A-PROBLEM executes. * * D1-01-FILE-A-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D2-00-FILE-INPUT-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON INPUT. * * * If an error occurs for any file open * in the INPUT mode except FILE-A, * D2-00-FILE-INPUT-PROBLEM executes. * * D2-01-FILE-INPUT-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D3-00-FILE-OUTPUT-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON OUTPUT. * * * If an error occurs for any file open * in the OUTPUT mode except FILE-A, * D3-00-FILE-OUTPUT-PROBLEM executes. * * D3-01-FILE-OUTPUT-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D4-00-FILE-I-O-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON I-O. * * * If an error occurs for any file open * in the INPUT-OUTPUT mode except FILE-A, * D4-00-FILE-I-O-PROBLEM executes. * * * D4-01-FILE-I-O-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . ******************************************************** D5-00-FILE-EXTEND-PROBLEM SECTION. USE AFTER STANDARD EXCEPTION PROCEDURE ON EXTEND. * * * If an error occurs for any file open * in the EXTEND mode except FILE-A, * D5-00-FILE-EXTEND-PROBLEM executes. * * D5-01-FILE-EXTEND-PROBLEM. PERFORM D9-00-REPORT-FILE-STATUS. . . . D9-00-REPORT-FILE-STATUS. . . . END DECLARATIVES. ******************************************************** A000-BEGIN SECTION. BEGIN. . . .

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 (Alpha) 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

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

• Compaq standard, which is compatible with the behavior of Compaq COBOL for OpenVMS VAX¹
• X/Open standard (Alpha), 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 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 (on Alpha only) 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 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 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 (Alpha)

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 (Alpha)

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