PreviousFile Status File Handler ConfigurationNext

Chapter 5: Sharing Files

When sharing data in a multi-user environment, you need to prevent more than one user from changing the same data at the same time. Locking files and records enables programs in a multi-user environment to share common files while maintaining data integrity.

5.1 Sharing mode

The sharing mode indicates whether a file is to participate in file sharing and record locking.

Three sharing modes are available:

Sharing Mode
Description
SHARING WITH NO OTHER Do not allow sharing with any other user of this file
SHARING WITH READ ONLY Allow sharing with other users who have the file opened for input
SHARING WITH ALL OTHER Allow sharing with all other users

For a full table showing the results when an OPEN is attempted in the various sharing modes, see the table Opening available shared files that are currently open by another file connector in the section The OPEN Statement in the chapter Procedure Division - MERGE - OPEN in your Language Reference.

To specify one of these sharing modes, use the SHARING phrase either on an OPEN statement or as part of the SELECT statement. The SHARING phrase in the OPEN statement overrides that in the SELECT statement.

If you do not include the SHARING phrase in either the SELECT or the OPEN statement, the sharing mode is determined when the first of the following conditions is satisfied:

Condition - If You Specify ...
Sharing Mode
The WITH LOCK phrase on the OPEN statement SHARING WITH NO OTHER
The LOCK MODE IS EXCLUSIVE phrase in the SELECT statement SHARING WITH NO OTHER
Either the LOCK MODE IS MANUAL phrase or the LOCK MODE IS AUTOMATIC phrase in the SELECT statement SHARING WITH ALL OTHER
The open mode as OUTPUT, I-O or EXTEND SHARING WITH NO OTHER
The open mode as INPUT and the configuration option OPENINPUTSHARED set to ON SHARING WITH ALL OTHER
The open mode as INPUT SHARING WITH READ ONLY

5.2 Record Locking

If file sharing is in effect, you can set locks on individual records. In this way, you can prevent other users from accessing the locked records whilst enabling these users to access other unlocked records.


Note: You cannot lock records in either a line sequential file or a file that you have opened for input.


5.2.1 Manual and Automatic Record Locking

To lock a record, use either manual or automatic record locking.

5.2.1.1 Manual Record Locking

If you are using manual record locking, use the READ statement to acquire a record lock.

To specify manual locking, use:

  1. The LOCK MODE IS MANUAL clause in the SELECT statement for the file

  2. The WITH LOCK clause on the READ statement

For example:

select fd-name
   assign to "muser.dat"
   lock mode is manual
...
read fd-name with lock

5.2.1.2 Automatic Record Locking

If you are using automatic record locking, the READ statement acquires a record lock automatically. To avoid locking a record, use the WITH NO LOCK clause in the READ statement.

To specify automatic locking, use the LOCK MODE IS AUTOMATIC clause in the SELECT statement for the file:

select fd-name
   assign to "muser.dat"
   lock mode is automatic
...
read fd-name

5.2.2 Single and Multiple Record Locking

You can lock either a single record or multiple records.

5.2.2.1 Single Record Locking

If you are using single record locking, you can hold one record lock only at any one time. Each new i-o operation on the file releases any previous lock.

To specify single record locking, do not use the WITH LOCK ON MULTIPLE RECORDS clause after either the LOCK MODE IS MANUAL clause or the LOCK MODE IS AUTOMATIC clause.

5.2.2.2 Multiple Record Locking

Multiple record locking permits many record locks to be held at once.

To specify multiple record locking, follow either the LOCK MODE IS MANUAL clause or the LOCK MODE IS AUTOMATIC clause with the WITH LOCK ON MULTIPLE RECORDS clause. For example:

select fd-name
   assign to "muser.dat"
   lock mode is automatic with lock on multiple records
...

Notes:


5.2.3 Handling Record Locks

By default, when a read operation encounters a locked record, the operation returns a locked record status. However, the operation does update the record area to show the contents of the record. After this operation, the current record pointer remains associated with the locked record, so that a following READ NEXT operation continues to try and access the same record.

The following configuration options affect this behaviour:

Configuration Option
Description
IGNORELOCK When set to ON, specifies that record locks are to be ignored when reading files open for input
RETRYLOCK When set to ON, specifies that operations that try and access locked records should be retried until the operation is successful. Can also be set to an integer, which specifies the maximum number of retries before the operation is aborted.
LOCKTYPE When set to 1, record locks are placed on the record itself, which means that a read operation that meets a locked record cannot return the data record. In this case the contents of the record area following the read are undefined.
SKIPLOCK When set to ON specifies that, following a read encountering a locked record, a READ NEXT operation returns the following record


Note: To bypass the locked record, you can also use the START…KEY IS GREATER THAN.. statement.


5.2.4 Releasing Record Locks

When the program that acquired the lock does one of the following, the action releases all record locks:

Additionally, when the program that acquired the lock accesses any other record in the file with any file operation, except START, this action releases single record locks.

5.3 File Status Codes

If your program runs in a multi-user environment, you should always check for the following file status codes:

File Status Code
Description
9/065 This status code is returned by an OPEN statement and indicates that the file is locked.
9/068 This status code is returned by a READ, DELETE or REWRITE statement and indicates that the record is locked.
9/213 This status code indicates that the maximum number of permitted locks has been reached. The maximum number of permitted locks depends on your network and/or operating system.

5.4 An Example Locking Application

An example file and record locking application is provided in the directory locking which is located in the directory demo under the Net Express base installation directory.

This application consists of a main program LOCKING.CBL and other programs called by this main program.

When running this application, use option 4 initially to create a file. To view the affects of record locking, use options 2 and/or 3 in multiple sessions.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousFile Status File Handler ConfigurationNext