DosFileLocks

Bindings:  C, MASM 

This call locks and unlocks a range in an opened file. 

 DosFileLocks    (FileHandle, UnLockRange, LockRange) 
 

 FileHandle (HFILE) - input 
    File handle. 

 UnLockRange (PLONG) - input 
    Address of the structure containing the offset and length of a range 
    to be unlocked. A doubleword of zero indicates that unlocking is not 
    required. 

    FileOffset (ULONG) 
       The offset to the beginning of the range to be unlocked. 

    RangeLength (ULONG) 
       The length of the range to be unlocked. 

 LockRange (PLONG) - input 
    Address of the structure containing the offset and length of a range 
    to be locked. A doubleword of zero indicates that locking is not 
    required. 

    FileOffset (ULONG) 
       The offset to the beginning of the range to be locked. 

    RangeLength (ULONG) 
       The length of the range to be locked. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    6         ERROR_INVALID_HANDLE 
    33        ERROR_LOCK_VIOLATION 
    36        ERROR_SHARING_BUFFER_EXCEEDED 
 
 Remarks 

 DosFileLocks provides a mechanism that allows a process to lock a region 
 in a file for read/write access. The time a region is locked should be 
 short. 

 Instead of denying another process read/write access to the entire file 
 by means of access and sharing modes specified with DosOpen or DosOpen2 
 requests, a process attempts to lock only the the range needed for 
 read/write access and examines the error code returned. 

 A range to be locked must first be cleared of any locked subranges or 
 overlapping ranges. The locked region can be located anywhere in the 
 file, and locking beyond end-of-file is not considered an error. 

 Once a lock is successful, read/write access by another process to the 
 specified range is denied until the range is unlocked. If both unlocking 
 and locking are specified by a DosFileLocks request, the unlocking 
 operation is performed first. After unlocking is completed, locking is 
 done. 

 Duplicating the handle duplicates access to any locked regions; however, 
 access to locked regions is not duplicated across the DosExecPgm call. 

 If a file is closed (either by a DosClose request or by a process 
 terminating) and locks are still in effect, the locks are released in no 
 defined order. 

 
 Family API Considerations 

 Some options operate differently in the DOS mode than in OS/2 mode. 
  Therefore, the following restrictions apply to DosFileLocks when coding 
 for the DOS mode: 

 o If Block = 1 is specified, an "invalid range lock list" or "invalid 
   unlock list" error is returned. 
 o NewLockIDList is not supported.