HP OpenVMS Systems Documentation
On OpenVMS, Table 8-4 describes RMS-STS values used in a file-sharing environment.
|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". . . .<>
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.
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.
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
8.4 Ensuring Successful Record Locking
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 (Alpha, I64) and the HP standard methods.
This section describes the X/Open standard method of specifying automatic or manual record locking.
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:
For files opened in INPUT mode, READ and READ WITH LOCK statements do not acquire a record lock.
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:
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 (Alpha, I64)|
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.