vfsLock

function

Library: File system utilities (OMVFS legacy)
Include: omvfs.xin

Declaration

define external function vfsLock
 value vfsFile file
 from value integer start optional
 to value integer end optional
 timeout value integer timeout optional
 id modifiable integer lock-id optional

Argument definitions

file: is the vfsFile component associated with the file you want to place a lock on.

start: is the first position of the locked area

end: is the last position of the locked area

timeout: is the time allowed for the operation

lock-id: is the identifier of the lock

Purpose

Use vfsLock to lock an entire vfsFile object or a specific area of it.

Requirements

You must include the following line at the beginning of your OmniMark program:

 include "omvfs.xin"

The vfsFile object file must be open (else external exception VFS200). The type of lock generated by this function depends on how file was opened. If file was opened with

write access, an exclusive lock is generated. No one can read from or write to the locked portion.
with read access, a shared lock is generated. No one can write to the locked portion.

The lock region begins at the start of the file if start is not specified. If start is specified it must be one of the following:

zero (0) (lock region begins at the start of the file)
VFS-START (lock region begins at the start of the file)
a positive integer (lock region begins at the specified byte in the file)

Specifying any other value for start will cause an exception to be thrown (external exception VFS212).

The lock region terminates at the end of the file if end is not specified. If end is specified it must have a value of either

VFS-END (lock region terminates at the end of the file)
a positive integer (lock region terminates at the specified byte in the file)

Specifying any other value for end will cause an exception to be thrown (external exception VFS213). If end is specified as an integer, it must have a value at least one greater than the value specified for start (else external exception VFS215).

The defined range for the lock must be at least one character long (else external exception VFS215). The range defined by start and end must not overlap any existing locks on the file (else external exception VFS216).

The timeout parameter allows you to specify the amount of time the program will wait for the specified lock to be completed before throwing an exception (external exception VFS217). If timeout is not specified, the function will wait until the lock is completed. If timeout is specified it must have a value of either:

zero (0) (the function returns immediately if the lock cannot be completed), or
a positive integer "n" (the function has "n" milliseconds to complete the lock)

Specifying any other value for timeout will cause an exception to be thrown (external exception VFS214).

lock-id is a modifiable parameter. If it is specified, the function will set it to a unique integer that identifies the newly locked region.

Usage Notes

General OS operation failure exceptions will return external exception VFS300. The accompanying text will contain details on the reason for the exception.

Example

Lock the region from byte 200 up to and including byte 400. Wait 2 seconds for the lock to be completed. Obtain an identifier for the lock.

 include "omvfs.xin"
 
 process
 local vfsFile Frankfurt
 local integer Lock-ID
 	. . .
 set Frankfurt to vfsOpen "myfile.txt"
 	. . .
 vfsLock Frankfurt
 	from 200 to 400
 	timeout 2000
 	id Lock-ID

Other Library Functions