Q(uick)BASIC Statement: LOCK...UNLOCK

Quick View

LOCK...UNLOCK

File I/O statements that control access by other processes to all or part of an opened file

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

LOCK [#]filenumber% [,{record& | [start&] TO end&}]
UNLOCK [#]filenumber% [,{record& | [start&] TO end&}]

Description/Parameter(s)

filenumber%	The number of an open file.
record&	For random-access files, the number of a record to lock, relative to the first record in the file. For binary files, the number of a byte to lock, relative to the first byte in the file.
start& and end&	The numbers of the first and last records or bytes in a range of records or bytes to lock or unlock.
For sequential files, LOCK and UNLOCK affect the entire file.

Example

This example runs only in a network environment.

OPEN "TEST.DAT" FOR RANDOM AS #1
FOR i% = 1 TO 10
    PUT #1, , i%
NEXT i%
LOCK #1, 2         'Lock record 2.
GET #1, 2, i%
UNLOCK #1, 2       'Unlock record 2.

Syntax

LOCK [#]filenumber [,{record |[start] TO end}][statements]UNLOCK [#]filenumber [,{record | [start] TO end}]

Description/Parameter(s)

These statements are used in networked environments where several processes might need access to the same file.

class="bold text-end"	Description
filenumber	The number with which the file was opened.
record	The number of the record or byte to be locked; record can be any number from 1 to 2,147,483,647 (equivalent to 2^31 -1). A record may be up to 32,767 bytes in length.
start	The number of the first record or byte to be locked.
end	The number of the last record or byte to be locked.

For binary-mode files, the arguments record, start, and end represent the number of a byte relative to the beginning of the file. The first byte in a file is byte 1.

For random-access files, the arguments record, start, and end are the number of a record relative to the beginning of the file. The first record is record 1.

The LOCK and UNLOCK statements are always used in pairs. The arguments to LOCK and UNLOCK must match exactly when you use them. See the second example below.

If you specify just one record, then only that record is locked or unlocked. If you specify a range of records and omit a starting record (start), then all records from the first record to the end of the range (end) are locked or unlocked. LOCK with no record arguments locks the entire file, while UNLOCK with no record arguments unlocks the entire file.

If the file has been opened for sequential input or output, LOCK and UNLOCK affect the entire file, regardless of the range specified by start and end. LOCK and UNLOCK only function at run time if you are using versions of DOS that support networking (version 3.1 or later). In addition, each terminal (or the network setup programs) must run the DOS SHARE.EXE program to enable locking operations. Earlier versions of DOS return an error message that reads "Advanced feature unavailable if LOCK and UNLOCK are executed."

Note:	Be sure to remove all locks with an UNLOCK statement before closing a file or terminating your program. Failing to remove locks produces unpredictable results. The arguments to LOCK and UNLOCK must match exactly.
	If you attempt to access a file that is locked, the following error messages may appear:
	"Bad record number" "Permission denied"

Examples

These example statements show how LOCK and UNLOCK are used in networked environments, where several processes might need access to the same file. These examples assume a random-access file.
Note: These examples are incomplete. Do not run them in their current form.

The following statement locks the entire file opened as number 2:

LOCK #2

The following statement locks only record 32 in file number 2:

LOCK #2, 32

The following statement locks records 1-32 in file number 2:

LOCK #2, TO 32

The two UNLOCK statements below unlock the records locked by the preceding LOCK statements:

LOCK #1, 1 TO 4
LOCK #1, 5 TO 8
UNLOCK #1, 1 TO 4
UNLOCK #1, 5 TO 8

The following UNLOCK statement is illegal because the range in an UNLOCK statement must exactly match the range in the corresponding LOCK statements (no error is reported, but the statements produce unpredictable results):

LOCK #1, 1 TO 4
LOCK #1, 5 TO 8
UNLOCK #1, 1 TO 8

The following program fragment opens a file and allows a user to lock an individual record before updating the information in that record. When the user is done, the program unlocks the locked record. (Unlocking the locked records allows other processes to use the data in the file.)

TYPE AccountRec
   Payer AS STRING * 15
   Address AS STRING * 20
   Place AS STRING * 20
   Owe AS SINGLE
END TYPE
DIM CustRec AS AccountRec

OPEN "MONITOR" SHARED AS #1 LEN = LEN(CustRec)

DO
   CLS: LOCATE 10,10
   INPUT "Customer Number?   #"; Number%
   ' Lock the current record so another process
   ' doesn't change it while you're using it.
   LOCK #1, Number%
      GET #1, Number%
      LOCATE 11,10: PRINT "Customer: ";CustRec.Payer
      LOCATE 12,10: PRINT "Address:  ";CustRec.Address
      LOCATE 13,10: PRINT "Currently owes: $";CustRec.Owe
      LOCATE 15,10: INPUT "Change (+ or -)", Change!
      CustRec.Owe = CustRec.Owe + Change!
      PUT #1, Number%
   ' Unlock the record.
   UNLOCK #1, Number%
   LOCATE 17,10: INPUT "Update another? ", Continue$
   Update$ = UCASE$(LEFT$(Continue$,1))
LOOP WHILE Update$ = "Y"

Syntax

LOCK [#]filenumber% [,{record& |[start&] TO end&}]⋮UNLOCK [#]filenumber% [,{record& | [start&] TO end&}]

Description/Parameter(s)

filenumber%	The number with which the file was opened.
record&	The number of the record or byte to be locked.
start&	The number of the first record or byte to be locked.
end&	The number of the last record or byte to be locked.

The argument record& can be any number from 1 to 2,147,483,647 (equivalent to 2^31 - 1). A record can be up to 32,767 bytes long.
For binary-mode files, the arguments record&, start&, and end& represent the number of a byte relative to the beginning of the file. The first byte in a file is byte 1.
For random-access files, record&, start&, and end& are the number of a record relative to the beginning of the file. The first record is record 1!
If the file has been opened for sequential input or output, LOCK and UNLOCK affect the entire file, regardless of the range specified by start& and end&.

Important

Be sure to remove all locks with an UNLOCK statement before closing a file or terminating your program. Failing to remove locks produces unpredictable results.
The arguments to LOCK and UNLOCK must match exactly.
Do not use LOCK and UNLOCK on devices or ISAM tables.
If you attempt to access a file that is locked, BASIC may generate the following error messages:
- "Bad record number"
- "Permission denied"

Usage Notes

LOCK and UNLOCK statements are used in networked environments where several processes might need access to the same file.
LOCK and UNLOCK statements are always used in pairs. The arguments to LOCK and UNLOCK must match exactly.
If you specify just one record, then only that record is locked or unlocked. If you specify a range of records and omit a starting record (start&), then all records from the first record to the end of the range (end&) are locked or unlocked. LOCK with no record arguments locks the entire file, while UNLOCK with no record arguments unlocks the entire file.
LOCK and UNLOCK execute only at run time if you are using OS/2 or versions of DOS that support networking (version 3.1 or later). In DOS, you must run the SHARE.EXE program to enable locking operations. Earlier versions of DOS return an error message that reads, "Advanced feature unavailable," if LOCK and UNLOCK are executed.

Example

This example illustrates the use of the LOCK and UNLOCK statements. A sample data record is created in a random-access file containing a customer record. The program allows you to update the file, locking the file while you use it to prevent access from another terminal.
Note: In order to use this program, you must have DOS version 3.1 or later, and you must run the DOS SHARE.EXE to enable locking operations before entering the BASIC programming environment.

'Define the record.
TYPE AccountRec
   Payer AS STRING * 20
   Address AS STRING * 20
   Place AS STRING * 20
   Owe AS SINGLE
END TYPE
 
DIM CustRec AS AccountRec
 
'This section creates a sample record to use.
ON ERROR GOTO ErrHandler
 
OPEN "MONITOR" FOR RANDOM SHARED AS #1 LEN = LEN(CustRec)
 
CustRec.Payer = "George Washington"
CustRec.Address = "1 Cherry Tree Lane"
CustRec.Place = "Mt. Vernon, VA"
CustRec.Owe = 12!
PUT #1, 1, CustRec          'Put one record in the file.
CLOSE #1
 
'This sections opens the sample record for updating.
OPEN "MONITOR" FOR RANDOM SHARED AS #1 LEN = LEN(CustRec)
DO
    Number% = 0             'Reset to zero.
    DO UNTIL Number% = 1    'Force user to input 1.
  CLS : LOCATE 10, 10
  INPUT "Customer Number?   #"; Number%
    LOOP
    'Lock the current record so another process
    'doesn't change it while you're using it.
    LOCK #1, Number%
    GET #1, Number%, CustRec
    LOCATE 11, 10: PRINT "Customer: "; CustRec.Payer
    LOCATE 12, 10: PRINT "Address:  "; CustRec.Address
    LOCATE 13, 10: PRINT "Currently owes: $"; CustRec.Owe
    LOCATE 15, 10: INPUT "Change (+ or -)", Change!
    CustRec.Owe = CustRec.Owe + Change!
    PUT #1, Number%, CustRec
    'Unlock the record so others can use it.
    UNLOCK #1, Number%
    LOCATE 17, 10: INPUT "Update another? ", Continue$
    Update$ = UCASE$(LEFT$(Continue$, 1))
LOOP WHILE Update$ = "Y"
CLOSE #1
 
'Remove file from disk.
KILL "MONITOR"
END
 
ErrHandler:
IF ERR = 70 THEN        'Permission denied error.
    CLS
    PRINT "You must run SHARE.EXE before running this example."
    PRINT "Exit the programming environment, run SHARE.EXE, and"
    PRINT "reenter the programming environment to run this"
    PRINT "example. Do not shell to DOS to run SHARE.EXE or you"
    PRINT "may not be able to run other programs until you reboot."
END IF
END