Related Topics
Other Library Functions

vfs.lock

function

Library: File system utilities (OMVFS)
Import : omvfs.xmd

Declaration 
export external function lock
                value file file-ref
        from    value integer start optional
        to      value integer end optional
        timeout value integer timeout optional
        id      modifiable integer lock-id optional

Argument definitions

file
The vfs.file object associated with the file you want to place a lock on.
start
An integer value of 0 or greater that indicates the first position of the locked area
end
An integer value of 1 or greater that indicates the last position of the locked area
timeout
An integer value of 0 or greater that indicates the number of milliseconds to wait for a lock
lock-id
An integer variable that will be set to a number that uniquely identifies the lock.


Purpose

Use vfs.lock to lock an entire file or a specific area of it.

This program locks the region from byte 200 up to and including byte 400. It will wait 2 seconds for the lock to be completed. It will obtain an identifier for the lock. It tests to see if the lock was obtained. Note how the do ... done block is used to scope the catch #external-exception that handles the case in which the lock is not available. 

  import "omvfs.xmd" prefixed by vfs.
  
  process
     local vfs.file exclusive-file
     local integer lock-id
     set exclusive-file
      to vfs.open "test.doc"
     do
        vfs.lock exclusive-file
          from 200 to 400
          timeout 2000
          id lock-id
        log-message "File locked with ID: %d(lock-id)%n"
        catch #external-exception identity error-code
           do when error-code = "VFS217"
              log-message "Could not lock file%n"
           else
              rethrow
           done
     done

The type of lock generated by this function depends on how the file was opened. If it was opened with write access, an exclusive lock is generated. No one can read from or write to the locked portion. If it was opened with read access, a shared lock is generated. No one can write to the locked portion.

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 you are putting more than one lock on a single file, you should obtain an identifier for each lock so that you can identify which lock you want to release when calling vfs.unlock.

Exceptions

The following exceptions may occur:

Related Topics
Other Library Functions