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

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.

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.

<PRE> #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 */ </PRE> 'Example'

This example opens a file, writes some data to it, locks a block of the data, and then unlocks it. <PRE> #define INCL_DOSFILEMGR

#define OPEN_FILE 0x01 #define CREATE_FILE 0x10 #define FILE_ARCHIVE 0x20 #define FILE_EXISTS OPEN_FILE #define FILE_NOEXISTS CREATE_FILE #define DASD_FLAG 0 #define INHERIT 0x80 #define WRITE_THRU 0 #define FAIL_FLAG 0 #define SHARE_FLAG 0x10 #define ACCESS_FLAG 0x02

#define FILE_NAME “test.dat” #define FILE_SIZE 800L #define FILE_ATTRIBUTE FILE_ARCHIVE #define RESERVED 0L #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 */
    }

</PRE>

<PRE> 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 </PRE>

Text based on http://www.edm2.com/index.php/DosFileLocks