en:docs:fapi:dosfilelocks
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


Next revision
—en:docs:fapi:dosfilelocks [2018/08/30 15:06] – created prokushev
Line 1: Line 1:
 +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.
 +
 +==Example Code==
 +===C Binding===
 +<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> 
 +
 +===MASM Binding===
 +<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>
 +
 +
 +====== Note ======
 +
 +Text based on [[http://www.edm2.com/index.php/DosFileLocks]]
 +
 +{{page>en:templates:fapi}}
 +