LockText

The LockText method locks single byte text region in file and returns lock handle. File data within locked region can be accessed only by the calling thread.
C++
long LockText(
  long FilePosition,            // position of region in file
  long NumberOfCharacters,      // number of characters in region
  BOOL Multilock,               // multiple locking flag
  long Format = 0,              // text format
  long Timeout = 5              // operation timeout
);
BASIC
LockText(
  FilePosition As Long,         // position of region in file
  NumberOfCharacters As Long,   // number of characters in region
  Multilock As Boolean,         // multiple locking flag
  Format As TextFormat = 0,     // text format
  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.
NumberOfCharacters
Number of characters 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.
Format
Text formatting options, specified as a combination of the following values:
IXF_TEXT_NULLTERM text is NULL terminated,
IXF_TEXT_CRLFTERM text is CR/LF terminated,
IXF_TEXT_STRING text is a raw character sequence (see Remarks);
cannot be combined with other flags.
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 at least NumberOfCharacters bytes long depending on Format. 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.

IXFile represents text as length-prefixed by default. Actual text data in file is preceded with a long number specifying length of the text in characters. If text is formatted as length-prefixed additional 4 bytes are locked for its length prefix.

If text is formatted as NULL- or CR/LF-terminated, additional 1 byte (NULL) or 2 bytes (CR/LF) are locked for termination.

If Format has IXF_TEXT_STRING flag set, text is treated as a raw sequence of characters and length of locked region is exactly NumberOfCharacters bytes.

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.

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

See Also

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