Function 5Ch Lock/Unlock File

mov bx, Handle ;handle of file to lock or unlock

mov cx, hiOffset ;high 16 bits of 32-bit offset

mov dx, loOffset ;low 16 bits of 32-bit offset

mov si, hiLength ;high 16 bits of 32-bit region length

mov di, loLength ;low 16 bits of 32-bit region length

mov al, LockFlag ;00h = lock, 01h = unlock

mov ah, 5Ch ;Lock/Unlock File

int 21h

jc error_handler ;carry set means error

Lock/Unlock File (Function 5Ch) denies or allows access to the specified region in a file.

Parameters

Handle

Identifies the file to lock or unlock.

hiOffset:loOffset

Specifies the 32-bit offset (in bytes) from the start of the file to the beginning of the region to lock or unlock.

hiLength:loLength

Specifies the 32-bit length (in bytes) of the region to lock or unlock.

LockFlag

Specifies whether to lock or unlock the specified file region (00h to lock the region, 01h to unlock the region).

Return Value

If the function is successful, the carry flag is clear. Otherwise, the carry flag is set, and the AX register contains an error value, which may be one of the following:

Value

Name

0001h	ERROR_INVALID_FUNCTION
0006h	ERROR_INVALID_HANDLE
0021h	ERROR_LOCK_VIOLATION
0024h	ERROR_SHARING_BUFFER_EXCEEDED

Comments

File sharing must be loaded (by running the Share program) before this function can be used.

This function returns 0021h (ERROR_LOCK_VIOLATION) if all or part of the specified region is already locked or if the specified region is not identical to a region previously locked by the same procedure.

If another program attempts to write to or read from a locked region, MS-DOS retries three times; if the retries fail, MS-DOS issues Critical-Error Handler (Interrupt 24h) for the requesting program. A program can change the number of retries by using Set Sharing Retry Count (Function 440Bh).

The locked region can be anywhere in the file. For example, locking beyond the end of the file is not an error. Duplicate File Handle (Function 45h) and Force Duplicate File Handle (Function 46h) duplicate access to any locked regions. Passing an open file to a child program by using Load and Execute Program (Function 4B00h) does not duplicate access to locked regions.

Programs should not depend on being denied access to a locked region. To determine the status of a region (locked or unlocked), a program can attempt to lock the region and then examine the error value.