NAME

lock - lock/unlock file access

SYNOPSIS

lock [#]FileNum [, read] [, wait] [, [RecNum] [to LastRec]]
unlock [#]FileNum [, [RecNum] [to LastRec]]

DESCRIPTION

These statements provide for restricted access to the given file by other programs.  FileNum is an integer value which is the file number.  The use of the keyword "read" indicates that other programs are permitted read-only access despite the lock.  The keyword "wait" indicates that the user’s program should wait for access.  RecNum and LastRec are double-precision values which indicate the records to lock. 

If either RecNum or LastRec is specified, a range of records in the file is locked and the file given by FileNum must have been opened for random I/O.  Otherwise, the entire file is locked.  If RecNum is specified but LastRec is not, only a single record is locked.  If LastRec is specified but RecNum is not, the range of the lock begins at the beginning of the file.  If LastRec specifies a record beyond the actual end of the file, the lock extends to any records added beyond the actual end of the file. 

For random files, multiple locks on overlapping or contiguous records are regarded as a single lock on the combined range and the "read" state of the most recent lock is used as the "read" state of the new lock.  Similarly, it is permissible to unlock only a portion of a previous lock: the other records remain locked.  When the program terminates any remaining locks are unlocked. 

There is a limit on the number of locks that may exist on the system at any point in time but this limit is large.  If the limit is exceeded, an error will occur.  It is possible to exceed this limit while unlocking.  If a middle portion of a previous lock is unlocked, the lock is split in two requiring an additional lock. 

EXAMPLE

While these statements allow considerable flexibility, in practice they are used in a very disciplined fashion.  In a multi-user environment where a common database is used these functions provide for control over the shared data.  Any number of users may read the data without difficulty but if the database is to be updated while “on-line” (that is, while potentially being read by other users) then the opportunity for conflict exists.  A database (or a record of a database) may not be read while it is being updated (written).  If the record is being read, no writer may be permitted.  If the record is being written, no access (by a reader or another writer) may be permitted. 

Thus a record which is accessed with intent to read only must be locked to prevent write access by other users.  And a record which is accessed with intent to write must be locked to prevent any access by other users. 

The following program fragments illustrate this method.  The first fragment demonstrates access to the database by a reader.  Note that the word "read" is used in the lock statement indicating intent to read only.  Other readers will not be restricted by this lock. 

	    on error goto 100
	    open "database" as #1 len = 80
	    field #1, 80 as name$
	 10 lock #1, read, 1
	    get #filenum%, record%
	    unlock #1, 1
	    print name$
	 20 close #1
	    goto 999
	100 if err <> 5 or erl <> 10 then on error goto 0
	    print "Record is being updated, sorry"
	    resume 20
	999 end

This second fragment demonstrates access to the database by a writer.  Note that the word "read" is not used in the lock statement indicating intent to write.  This lock prevents access of any kind to this record. 

	    on error goto 100
	    input "What is the name"; n$
	    open "database" as #1 len = 80
	    field #1, 80 as name$
	    lset name$ = n$
	 10 lock #1, 1
	    put #filenum%, record%
	    unlock #1, 1
	 20 close #1
	    goto 999
	100 if err <> 5 or erl <> 10 then on error goto 0
	    print "Record is in use, sorry"
	    resume 20
	999 end

DIAGNOSTICS

If a lock is not permitted (because of a lock by another program), an error will occur or the program will wait.  If the word "wait" is used, the program will wait for access.  Otherwise the error "Illegal function call" will occur. 

USAGE NOTES

On some implementations of Basmark QuickBASIC the functionality of these statements is not available, on such implementations these statements will compile, but will generate the error "Illegal function call" when executed. 

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber