swirl
Guide to OmniMark 8   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesLegacy LibrariesErrors
 
  Related Syntax     Other Library Functions  
function  

vfs.lock

 
 

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 Syntax
   vfs.unlock
 
  Other Library Functions
   vfs.change-directory
   vfs.change-owner
   vfs.change-permissions
   vfs.close
   vfs.connect
   vfs.connect-directory
   vfs.copy
   vfs.cursor-position
   vfs.default-certificates-file
   vfs.delete-directory
   vfs.delete-file
   vfs.describe
   vfs.describe-file
   vfs.directory
   vfs.directory-name
   vfs.disconnect
   vfs.file
   vfs.file-directory
   vfs.file-name
   vfs.link
   vfs.list
   vfs.lock
   vfs.make-directory
   vfs.move
   vfs.move-cursor
   vfs.omvfs-version
   vfs.open
   vfs.open-file-system
   vfs.open-ftp
   vfs.open-http
   vfs.open-https
   vfs.reader
   vfs.set-default-certificates-file
   vfs.truncate
   vfs.unlock
   vfs.writer
 
 

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

OmniMark 8.2.0 Documentation Generated: March 13, 2008 at 3:27:39 pm
If you have any comments about this section of the documentation, please use this form.

Copyright © Stilo International plc, 1988-2008.