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

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)

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)

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)

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    vfsChangeDir    vfsChangeOwner    vfsChangePermissions    vfsClose    vfsConnect    vfsConnectDir    vfsCopy    vfsCursorPosition    vfsDeleteDir    vfsDeleteFile    vfsDescribe    vfsDescribeFile    vfsDir    vfsDirName    vfsDisconnect    vfsFile    vfsFileDir    vfsFileName    vfsIsVersionCompatible    vfsLibraryVersion    vfsLink    vfsList    vfsLock    vfsMakeDir    vfsMove    vfsMoveCursor    vfsOpen    vfsRead    vfsRename    vfsTruncate    vfsUnlock    vfsWrite

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]