V_LOCK_METHOD

This variable selects which locking method Vision will use to control simultaneous access to indexed files. It affects only the Vision file system, and only files directly accessed by the runtime (it does not apply to files accessed via AcuServer).

The default setting of 0 (zero) causes Vision to lock the first byte of the file for every access to the file (both reads and updates). This ensures that the process is not interfered with by another process.

Setting this variable to 1 causes Vision to lock the first byte of the file for all operations except random READs or READ NEXTs. These two operations proceed without the lock. Instead they perform some additional reads of the file, to ensure that they get consistent results. If they get inconsistent results, they are retried, this time locking the first byte as other operations do. This locking method is available for Vision Versions 3 and later.

Note: This variable must have the same setting for all the runtimes accessing a file, whether they are reading or writing to it. For example, if a runtime set with V_LOCK_METHOD=1 is reading from a file, any runtimes that are writing to that same file must also have V_LOCK_METHOD set to 1.

Lock method 1 can produce better performance on some machines. These machines fall into two categories:

Setting V_LOCK_METHOD to 1 might help improve performance with files of Vision Version 3 or later. For example, setting V_LOCK_METHOD to 1 can be helpful on some Windows networks. A peer-to-peer network of Windows 98 machines can exhibit problems reading Vision files when a process performs a tight read loop. The problem usually surfaces as either an error 30,33 or an unexpected error 99. This occurs because the runtime is unable to place a lock on the header of the file after 400 attempts over a 20-second period. For other networks, setting V_LOCK_METHOD to 1 can substantially reduce the number of lock requests made by the runtime and can often resolve these problems.

To get statistics about header locks, select Trace Files level "3" in the debugger (for example, TF 3). These statistics print on the runtime's error output each time a Vision file is closed. They cover the operations in that file since it was last opened. You can also view these statistics (without the full trace) by adding "256" to the lock method chosen (for example, setting V_LOCK_METHOD to "257" selects method "1" and prints statistics).

Setting the V_LOCK_METHOD variable to 2 enables "asynchronous reads" of Vision files. This option is intended to further reduce the number of file locks required to perform random READs and READ NEXTs.

The advantage of the "2" setting is that it is less likely to require retrying a READ with a lock when a file is undergoing heavy modification. With V_LOCK_METHOD 1, the READ is retried with a lock whenever it detects that the file has been updated in any way; with V_LOCK_METHOD 2, the READ is retried only when Vision encounters inconsistent data while traversing the index tree or reading the record data. This leads to less locks and therefore greater performance for machines with slow locking functions.

V_LOCK_METHOD 2 works only for files of Vision Version 4 and later. A fundamental requirement for the V_LOCK_METHOD 2 feature to work properly is that the operating system must provide atomic write operations. That is, if one process is writing to a file, another process will always see the contents of the file as it exists either before or after the write operation, never the intermediate contents as the write operation runs.

Some file systems do not provide atomic file operations, and for those environments, V_LOCK_METHOD 2 is not recommended. Use the vutil -wtest option to check the compatibility of the file system housing the Vision files that you will access using the V_LOCK_METHOD 2 configuration; see Testing for Vision File Locking Compatibility for more information.

CAUTION:
Using V_LOCK_METHOD 2 on a file system that does not provide atomic file operations will likely cause spurious file errors or file corruption.

If any process reading a particular file is using V_LOCK_METHOD 2, all other processes (runtimes) updating that file must be ACUCOBOL Version 5.0.0 or greater. This is because Version 5.0.0 contains changes that affect the way Vision updates the tree structure of its files. These changes allow for greater consistency of the tree from the viewpoint of an asynchronous reader. This requirement is not enforced by Vision, however, so it is important for the users to pay careful attention to the versions of programs accessing their files to avoid receiving erroneous data. Therefore, before enabling this option, make sure that all runtimes updating files on which asynchronous reads are to be performed (V_LOCK_METHOD 2) are Version 5.0.0 or later.

As with V_LOCK_METHOD 1, adding 256 to the value of the V_LOCK_METHOD setting causes statistics about header locks to be printed to the runtime's error output each time a Vision file is closed. So, setting V_LOCK_METHOD 258 selects method 2 and turns on the header lock statistics.