DosFileLocks

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

Syntax
DosFileLocks (FileHandle, UnLockRange, LockRange)

Parameters

 * 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.

Return Code

 * 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 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:
 * If Block = 1 is specified, an "invalid range lock list" or "invalid unlock list" error is returned.
 * NewLockIDList is not supported.

C

 * 1) define INCL_DOSFILEMGR

USHORT rc = DosFileLocks(FileHandle, UnLockRange, LockRange);

HFILE  FileHandle;    /* File handle */ PLONG  UnLockRange;   /* UnLock range */ PLONG  LockRange;     /* Lock range */

USHORT rc;            /* return code */ 

MASM
 EXTRN DosFileLocks:FAR INCL_DOSFILEMGR    EQU 1

PUSH  WORD    FileHandle    ;File handle PUSH@ OTHER   UnLockRange   ;UnLock range PUSH@ OTHER   LockRange     ;Lock range CALL  DosFileLocks

Returns WORD 

Example
This example opens a file, writes some data to it, locks a block of the data, and then unlocks it. 
 * 1) define INCL_DOSFILEMGR


 * 1) define OPEN_FILE 0x01
 * 2) define CREATE_FILE 0x10
 * 3) define FILE_ARCHIVE 0x20
 * 4) define FILE_EXISTS OPEN_FILE
 * 5) define FILE_NOEXISTS CREATE_FILE
 * 6) define DASD_FLAG 0
 * 7) define INHERIT 0x80
 * 8) define WRITE_THRU 0
 * 9) define FAIL_FLAG 0
 * 10) define SHARE_FLAG 0x10
 * 11) define ACCESS_FLAG 0x02


 * 1) define FILE_NAME "test.dat"
 * 2) define FILE_SIZE 800L
 * 3) define FILE_ATTRIBUTE FILE_ARCHIVE
 * 4) define RESERVED 0L
 * 5) define NULL_RANGE 0L

HFILE  FileHandle; USHORT Wrote; USHORT Action; PSZ    FileData[100]; USHORT rc;

struct LockStrc {  long Offset; long Range; } Area;

int i;

Action = 2; strcpy(FileData, "Data..."); Area.Offset = 4; Area.Range = 100;

if(!DosOpen(FILE_NAME,               /* File path name */ &FileHandle,            /* File handle */ &Action,                /* Action taken */ FILE_SIZE,              /* File primary allocation */ FILE_ATTRIBUTE,         /* File attribute */ FILE_EXISTS | FILE_NOEXISTS, /* Open function type */ DASD_FLAG | INHERIT |        /* Open mode of the file */ WRITE_THRU | FAIL_FLAG | SHARE_FLAG | ACCESS_FLAG, RESERVED))              /* Reserved (must be zero) */ {     for(i=0; i<200; ++i) DosWrite(FileHandle,           /* File handle */                  FileData,              /* User buffer */                  sizeof(FileData),      /* Buffer length */                  &Wrote);               /* Bytes written */ rc = DosFileLocks(FileHandle,     /* File handle */                        NULL_RANGE,      /* Unlock range */                        (PLONG) &Area);  /* Lock range */ rc = DosFileLocks(FileHandle,     /* File handle */                        (PLONG) &Area,   /* Unlock range */                        NULL_RANGE);     /* Lock range */ } 