HP 3000 Manuals HP 3000 Manuals
Multi-user Facilities
There are different syntax and programming considerations depending on
the organization of the files to be shared. The following sections
describe how to program for shared record sequential, line sequential,
relative or indexed files.
The LOCK MODE phrases used in the following sections are part of the
SELECT statement. See your Language Reference for details.
Types of Locking
There are three types of locking:
* Automatic
* Manual
* Exclusive
Automatic Locking.
Automatic locking is used to lock a single record or multiple records.
Automatic single record locks mean that when the program reads a record
from a file opened I-O, that record is automatically locked until the
program next accesses that file. For files that have been opened for
INPUT, records are never locked. Files opened for OUTPUT cannot support
automatic locking, and always hold an exclusive lock on the whole file.
Your program cannot access a file in automatic (sharable) mode if another
user has already opened the file in exclusive mode.
Automatic multiple record locks mean that you can lock records up to the
limit for your implementation. These records are locked automatically as
they are read, and are not released until a CLOSE
, COMMIT
, ROLLBACK
or UNLOCK
statement is executed. Note that the lock is released when a record is
deleted.
When a WRITELOCK
or FILESHARE
Compiler directive is specified, WRITE and REWRITE statements also
acquire a record lock when you are locking multiple records.
Manual Locking.
Manual locking is used to lock a single record or multiple records. It
is similar to automatic, except that to lock a record you must explicitly
lock it when it is read. That is, you must specify READ WITH LOCK
(single records) or READ WITH KEPT LOCK (multiple records) to acquire a
lock. As with automatic locking, only files opened I-O can acquire
record locks.
With multiple records WRITE and REWRITE statements also acquire a lock if
you have specified the WRITELOCK or FILESHARE Compiler directive.
Exclusive Locking.
Exclusive locking means that the whole of the file is locked as soon as
the user executes an OPEN statement on the file. Your program cannot
open a file in exclusive mode if another user is already accessing the
file. With exclusive locking, the file remains locked until it is
closed. If your program opens a file for OUTPUT or a relative or indexed
file for EXTEND, this implies an exclusive lock on the file.
To obtain an exclusive lock on a file, you must have read and write
permission for that file.
Locking Rules for Each File Organization
The following sections define the rules that apply to locking for each of
the file organizations.
Record Sequential, Relative and Indexed Files.
With record sequential, relative and indexed files you can lock whole
files, individual records or groups of records up to the maximum allowed
by your implementation.
You can lock several records simultaneously with the WITH LOCK ON
MULTIPLE RECORDS clause. Once you have locked the maximum number of
records allowed by your implementation, a status of 9/123, "Too many
locks", is returned if you try to lock any more records. When this
happens you must close the file, or execute a COMMIT
, ROLLBACK
or UNLOCK
statement to release these record locks.
You can lock single or multiple records in either MANUAL or AUTOMATIC
locking mode.
Each time your program accesses a file with an OPEN, READ or READ WITH
LOCK statement, the locking you have specified in the SELECT statement is
taken into account (see the Language Reference for details of these
statements). The following then apply:
* When you specify LOCK MODE IS EXCLUSIVE, the whole file is locked
from when your program opens the file until it closes it.
* When you specify LOCK MODE IS AUTOMATIC, a single record is locked
as the program reads it and unlocked when the file is next
accessed.
* When you specify LOCK MODE IS AUTOMATIC WITH LOCK ON MULTIPLE
RECORDS, multiple records are locked as the user executes READ
statements. Records remain locked until the file is closed, or a
COMMIT, ROLLBACK or UNLOCK statement is executed.
* When you specify LOCK MODE IS MANUAL, single records are locked as
the user executes a READ WITH LOCK statement on the record.
* When you specify LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE
RECORDS, multiple records are locked as the user executes READ
WITH KEPT LOCK statements. Records remain locked until the file
is closed, or a COMMIT
,
ROLLBACK or UNLOCK
statement is executed.
* When you do not specify a LOCK MODE IS clause, the default locking
is used. Files opened for INPUT are sharable. Files opened for
OUTPUT, I-O or EXTEND are exclusive.
* Unless you explicitly include WITH LOCK ON MULTIPLE RECORDS,
single record locks are assumed when the lock is automatic or
manual.
Note that you can open an indexed file only if you have WRITE permission
to the index portion of the file.
Line Sequential Files.
With line sequential files, you can lock only
files; record locking is not allowed. See your Language Reference for
the format of the SELECT statement for a line sequential file.
Each time your program accesses a file with an OPEN, READ or READ WITH
LOCK statement, the locking you have specified is taken into account (see
the Language Reference for details of these statements). This means
that:
* When you specify LOCK MODE IS EXCLUSIVE, the whole file is locked
from the time your program opens the file until it closes it.
* When you specify LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL,
the file is sharable but no locks can be obtained on records in
the file.
* When you do not specify a LOCK MODE IS clause, the default locking
is used. Files opened for INPUT are sharable. Files opened for
OUTPUT, I-O or EXTEND are exclusive.
All File Types.
UNIX On UNIX, multiple OPEN requests within the same run
unit can have conditions applied to determine
whether or not a given file has been previously
opened and whether any such open was exclusive.
This functionality is available when file opens are
issued from separate source programs. Any attempt
to open a file multiple times in the same source
program results in a "File already open - cannot be
opened" error.
This feature is enabled by setting the value of the
same_proc_excl_detection cobconfig run-time
configurable to TRUE. See your COBOL System
Reference (for UNIX) for an explanation of run-time
configurables, and further information about this
run-time configurable.
The Procedure Division
In most instances, COBOL programs designed to be run in a multi-user
environment do not require any extra considerations in the Procedure
Division. The exception to this is checking the file status for a lock
condition (see the section File Status later in this chapter). There
are, however, some instances when you need to use different syntax in the
Procedure Division. That syntax is described below.
* The COMMIT statement
This statement releases record locks on all records in all the files the
user has opened. This includes SEQUENTIAL, RELATIVE and INDEXED files,
with automatic or manual locking on single and multiple records. The
COMMIT statement has no effect on exclusive files.
* The ROLLBACK statement
This statement releases record locks on all records in all the files the
user has opened. This includes SEQUENTIAL, RELATIVE and INDEXED files,
with automatic or manual locking on single and multiple records. The
ROLLBACK statement has no effect on exclusive files.
* The UNLOCK statement
The statement
UNLOCK file-name
releases all record locks the user has acquired on the specified file.
You can use this statement only for files that are sharable.
* The READ statement
With sharable files opened for I-O whose LOCK MODE is MANUAL, you must
include the WITH LOCK phrase (for single record locks) or WITH KEPT LOCK
phrase (for multiple record locks).
With sharable files with multiple record locking the REWRITE and WRITE
statements can also lock the record that is accessed. To do this a
WRITELOCK
or FILESHARE
directive should be specified when compiling your program.
See your Language Reference for details of the syntax mentioned here.
File Status
In a multi-user environment the file status item set up with the clause:
FILE STATUS IS data-name
in the SELECT statement is used to check the status of an attempted
access to a file. This section explains how to interpret the status
codes returned in this data item.
The data-name you specify must refer to a two-byte alphanumeric data
item. The first byte of the data-name is called status key 1, and
reports generally on the success or failure of an input-output operation
on a file. The second byte of the data item is status key 2. If any
further information is available it is returned in status key 2.
When status key 1 contains the character "9", status key 2 contains a
binary error number rather than a character. You might want to redefine
status key 2 as a PIC X COMP-X item so that this data item can hold the
error numbers produced by the COBOL system.
The values that can be returned in these status keys and the errors they
refer to are documented in your Error Messages. Where status key 1
contains the value 9 (operating system error message), status key 2 can
contain any of the following binary values that are specific to a
multi-user environment:
Status Meaning
65 locked file - another program has already accessed
the file to the exclusion of other programs.
68 locked record - another program has already locked
the record.
213 too many locks - the application has already
acquired the maximum number of locks permitted by
the RTS or multi-user environment. You must now
execute a CLOSE, COMMIT, ROLLBACK or UNLOCK
statement to release record locks before
continuing.
It is your responsibility to make your program check for status codes,
and to decide what action you want your program to take on finding the
various status codes.
Handling a Record or File Lock.
If another program has already locked the record your program wants to
access, an attempted WRITE, REWRITE or DELETE operation fails.
If your program attempts to read a record already locked by another
program, a lock status (error 68) is returned in the file status data
item, if declared. However, valid data is also returned (unless the
operating system does not support this).
The system can be made to automatically reread a locked record until the
lock is released, by specifying the RETRYLOCK Compiler directive when
compiling your program.
You must be aware that this feature can lead to situations where two
applications cannot proceed because they are both trying to access
records locked by the other.
When a sequential read finds a record lock, the file position indicator
is not updated unless the run-time switch B has been turned on, and the
file is an indexed file. In this case, the file position indicator is
advanced to the next available record.
If you want to receive a "00" file status when reading a locked record
for which you do not want to acquire a lock, specify the NODETECTLOCK
Compiler directive when you compile your program.
The START...KEY IS GREATER THAN statement can be used to skip over locked
records in relative or indexed files.
If your program finds a lock on a record that you are attempting to
START, the COBOL system ignores the record lock and updates the file
position indicator.
Whenever your program tries to access a file that has been exclusively
opened by another program, you must wait until the other program has
closed the file before you can access the data in the file.
When your program finds a record locked, you must wait until that record
has been released before your program can access it successfully. In the
case of a program that has locked multiple records, you must wait until
the program closes the file or executes a COMMIT, ROLLBACK or UNLOCK
statement.
NOTE When reading a record, the contents of the record are returned even
when the record is locked. A status is returned indicating that
the record is locked, and the file position indicator is not
advanced unless the +B switch is used.
Refer to your COBOL System Reference for details of run-time switches and
Compiler directives.