LockVariant

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

Parameters

VariantTemplate
Variant that defines data element to be locked.
Variant can be of any allowed type, it can be either single variable or one dimensional array.
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.
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 * sizeof(VariantTemplate) 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.

VariantTemplate variant can be of one of allowed types: Byte, Integer, Long, Single, Double, String, Boolean, Date, Currency, Decimal and Variant. The array of variants is especially interesting because it allows locking complex structured data with fields of various types. The only limitation is that all arrays must be one-dimensional. As mentioned above VariantTemplate can contain String data; it should be noted, however, that text in variant is always represented by IXFile as length-prefixed Unicode.

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 another application, thread or other IXFile object.

Method can be used for locking structured data with fields of various types. In such case size of VariantTemplate determines size of single element and NumberOfElements specifies how many such elements are locked in file.

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

See Also

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