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:

The LOCK MODE IS MANUAL clause in the SELECT statement for the file
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:

If you do not use the WITH LOCK ON MULTIPLE RECORDS clause, single record locking takes effect
If you specify multiple record locking for a file and you use the WRITELOCK compiler directive when you compile your program, the program also acquires a record lock whenever it accesses the file with a WRITE or REWRITE statement

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:

Closes the file
Executes a COMMIT statement
Executes a ROLLBACK statement
Executes an UNLOCK statement on the file
Deletes the locked record

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.

File Status

File Handler Configuration