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.
| 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 |
1Corresponds to File Status Value of 91
2Corresponds to File Status Value of 30
3Corresponds to File Status Value of 00
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.
8.4 Ensuring Successful Record Locking
Once you meet all of the file-sharing criteria and you access a file, you can consider two record-locking modes that control access to records in a file:
- Automatic record locking---The system automatically releases an existing record lock whenever a new record is accessed and acquires a record lock whenever it reads a record in the file.
- Manual record locking---A file connector can hold a number of record locks simultaneously. Manual record locking is available only for relative or indexed files.
You must use the same method for record locking as for file sharing. For any single file connector, you cannot mix the X/Open standard and the Compaq standard methods. |
8.4.1 X/Open Standard Record Locking
This section describes the X/Open standard method of specifying automatic or manual record locking.
Specifying Automatic Record Locking (X/Open Standard)
You specify X/Open standard automatic record locking in the Environment Division by using LOCK MODE IS AUTOMATIC [WITH LOCK ON RECORD] on the SELECT statement. (The optional WITH LOCK ON RECORD clause has no effect and is for documentation only.) Subsequently, a record lock is acquired by the successful execution of a READ statement. (The WITH LOCK clause is not necessary on the READ; it is implied.)
A record lock is released by one of the following events:
- The successful execution of a subsequent I-O statement
- Using the UNLOCK statement
- Closing the file, implicitly or explicitly
In X/Open standard record locking, only the READ statement can acquire a lock. You can use the WITH NO LOCK phrase of the READ statement to prevent the acquiring of an automatic record lock.
For files opened in INPUT mode, READ and READ WITH LOCK statements do not acquire a record lock.
Specifying Manual Record Locking (X/Open Standard)
You specify X/Open standard manual record locking in the Environment Division by using LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS on the SELECT statement. Manual record locking is available only for relative and indexed files.
For manual record locking, a record lock is acquired by specifying the WITH LOCK phrase on the READ statement. READ is the only operation that can acquire a lock. The record lock is released by one of the following events:
- Using the UNLOCK statement (any form of the UNLOCK statement unlocks all record locks held by the current access stream; there is no singular option)
- Closing the file, implicitly or explicitly
The WITH LOCK clause is ignored for files opened in INPUT mode. Locks are detected but not acquired.
Example 8-4 is a partial example of using both methods of X/Open standard record locking.
| Example 8-4 X/Open Standard Record Locking | ||||
|---|---|---|---|---|
User 1 (Automatic Record Locking): ---------------------------------
FILE-CONTROL.
SELECT FILE-1
ORGANIZATION IS RELATIVE
ASSIGN TO "SHAREDAT.DAT"
LOCK MODE AUTOMATIC.
.
.
.
PROCEDURE DIVISION.
BEGIN.
OPEN I-O FILE-1.
READ FILE-1.
.
.
.
REWRITE FILE-1-REC.
CLOSE FILE-1.
STOP RUN.
User 2 (Manual Record Locking): ------------------------------
FILE-CONTROL
SELECT FILE-1
ORGANIZATION IS RELATIVE
ASSIGN "SHAREDAT.DAT"
LOCK MODE MANUAL LOCK ON MULTIPLE RECORDS.
.
.
.
PROCEDURE DIVISION.
BEGIN.
OPEN I-O FILE-1.
.
.
.
READ FILE-1 WITH LOCK.
REWRITE FILE-1-REC.
UNLOCK FILE-1.
CLOSE FILE-1.
STOP RUN.
|
Note that User 2 could have employed AUTOMATIC record locking just as
well. In this case, manual and automatic locking work similarly.
8.4.2 Compaq Standard Record Locking
Automatic Record Locking (Compaq Standard)
You specify automatic record locking by using the ALLOWING phrase of the OPEN statement. The lock is applied when you access the record and released when you deaccess the record. In automatic record locking the access stream can have only one record locked at a time and can apply only one type of lock to the records of the file.
You deaccess a record by using the next READ operation, a REWRITE or a DELETE operation on the record, or by closing the file. In addition, you can release locks applied by automatic record locking by using the UNLOCK statement.
In automatic record-locking mode, you can release the current record lock by using an UNLOCK RECORD statement or an UNLOCK ALL RECORDS statement. (On Tru64 UNIX systems for indexed files only, there is no current record lock.) However, because in automatic record locking you can lock only one record at a time, the UNLOCK ALL RECORDS statement unnecessarily checks all records for additional locks.
The sample program in Example 8-5 uses automatic record locking. The program opens the file with I-O ALLOWING ALL. Another access stream in another program also opens the file with INPUT ALLOWING ALL.
Note that two parallel access streams use the program in Example 8-5.
If the first access stream is updating records in random order, a record lock can occur to the second stream from the READ until the REWRITE statement of the first stream. Record locks can also occur to the first stream when the second stream reads a record and the first stream tries to read the same record.
| Example 8-5 Automatic Record Locking (Compaq Standard) | ||||
|---|---|---|---|---|
SELECT FILE-1
ORGANIZATION IS RELATIVE
ASSIGN TO "SHAREDAT.DAT"
.
.
.
PROCEDURE DIVISION.
OPEN I-O FILE-1 ALLOWING ALL.
READ FILE-1 AT END DISPLAY "end".
.
.
.
REWRITE FILE-1-REC.
CLOSE FILE-1.
STOP RUN.
|
When you close a file, any existing record lock is released automatically. The UNLOCK RECORD statement releases the lock only on the current record on OpenVMS Alpha systems, which is the last record you successfully accessed. On Windows NT and Tru64 UNIX systems for indexed files only, there is no current record lock.
Manual Record Locking (Compaq Standard)
You specify manual record locking by using the APPLY LOCK-HOLDING clause (in the I-O-CONTROL paragraph), the OPEN ALLOWING statement, and the ALLOWING clauses on the Compaq COBOL record operations (except DELETE). Manual record locking allows greater control of locking options by permitting users to lock multiple records in a file and by permitting different types of locking to apply to different records.
Manual record locking applies the specified lock when you access the record and releases the lock when you unlock the record.
When you specify manual record locking you must use all of the following clauses:
- An APPLY LOCK-HOLDING clause in the I-O CONTROL paragraph
- An OPEN ALLOWING clause at file open time
- An ALLOWING clause on each record operation (except DELETE)2
The possible ALLOWING clauses for the record operations (that is, the READ, WRITE, REWRITE, and START statements) are as follows:
- ALLOWING NO OTHERS2---Locks records for exclusive access. Others cannot perform READ, WRITE, DELETE, or UPDATE statements. This clause constitutes a lock for write and does not allow readers.
- ALLOWING READERS---Locks records against WRITE, REWRITE, and DELETE access by all streams including the stream that issues the statement. Others can perform READ statements.
- ALLOWING UPDATERS2---Does not apply any locks to the records. Others can perform READ, REWRITE, and DELETE statements. This clause constitutes a no record lock condition. 2
However, if the file's OPEN mode is INPUT, using the ALLOWING clause on the record operation does not lock the record.
On Tru64 UNIX and Windows NT systems, for indexed files only, the WRITE, REWRITE, and START statements do not acquire a record lock.
On Tru64 UNIX and Windows NT systems for indexed files only, ALLOWING READERS is treated as ALLOWING NO OTHERS if the file is opened in I-O mode or as ALLOWING ALL if the file is opened in INPUT mode. <>
Table 8-5 shows the valid and invalid ALLOWING combinations for manual record locking. The columns represent the lock held, and the rows represent the lock requested.
| Lock Held (for first stream) | ||||
|---|---|---|---|---|
| I-O Attempt (for subsequent stream) | Updaters | Readers | No Others | |
| READ | Allowing Updaters | Y | Y | N |
| Allowing Readers | Y | Y | N | |
| Allowing no others | Y | N | N | |
| REWRITE | Allowing no others | Y | N | N |
| DELETE | Y | N | N | |
| START | Allowing Updaters | Y | Y | N |
| Allowing Readers | Y | Y | N | |
| Allowing no others | Y | Y | N | |
| WRITE | Allowing no others | N/A | N/A | N/A |
2 Some exceptions exist on Windows NT and Tru64 UNIX. See Compaq COBOL Reference Manual for details. |
| Previous | Next | Contents | Index |