LockBinary

The LockBinary method locks binary data region in file and returns lock handle. File data within locked region can be accessed only by the calling thread.
C++
long LockBinary(
  long FilePosition,            // position of region in file
  long NumberOfElements,        // number of elements in region
  long SizeOfElement,           // size of each element
  BOOL Multilock,               // multiple locking flag
  long Timeout = 5              // operation timeout
);
BASIC
LockBinary(
  FilePosition As Long,         // position of region in file
  NumberOfElements As Long,     // number of elements in region
  SizeOfElement As Long,        // size of each element
  Multilock As Boolean,         // multiple locking flag
  Timeout As Long = 5           // operation timeout
) As Long

Parameters

FilePosition
Starting position of region in file to be locked.
If this parameter is -1 lock begins at current file position.
NumberOfElements
Number of elements in region to be locked.
If this parameter is -1 file is locked up to the end.
SizeOfElement
Size of each element in region, in bytes.
Multilock
If this parameter is TRUE multiple locking of overlapping regions is allowed for this object (see Remarks); otherwise regions can be locked only once and cannot overlap.
Timeout
Time to wait for lock if file region is locked by another application, in seconds.
If this parameter is 0 and locking is not possible method returns immediately with error.

Return Values

If the method succeeds, the return value is the handle of locked region in file.
If the method fails, the return value is failure code and error code is set. Call GetError to get error code.

Remarks

Method locks file region that begins at FilePosition and is NumberOfElements * SizeOfElement bytes long. If specified region is already locked by another application (thread) or overlaps another locked region, method waits up to Timeout seconds trying to lock specified region before returning error; if Timeout is 0, returns immediately.

Multiple locking allows locking the same region or its parts many times; with this option enabled object is allowed to lock as many overlapping file regions as needed without regard to their influence on each other. Map of the locks is maintained internally by the object to guarantee correct order of unlocking - file region is physically unlocked only when there are no dependent locks active. Therefore you must assume that after calling UnLock method file region can be still physically locked. Keep in mind that multiple locking is allowed only for the same IXFile object; you cannot lock region that overlaps another region locked by other application, thread or other IXFile object.

Method can be used for locking structured data with fields of various types. In such case entire structure should be treated as a sequence of bytes whose length is equal to total size of the structure specified in SizeOfElement; NumberOfElements specifies how many such structures are locked in file. Method can be also used for locking data of simple types that are not directly supported like Boolean, Date, Currency or Decimal; in such case size of elements must be specified to properly calculate length of region.

Locked region should be eventually unlocked with UnLock method, passing lock handle returned from this method as a parameter.

Visual Basic developers can preferably use LockVariant method for locking structured data.

See Also

LockByte, LockShort, LockLong, LockFloat, LockDouble, LockText, LockUnicodeText, LockVariant, UnLock, Locking File