FairCom ISAM for C

Dummy Lock File

The Standalone Multi-user mode of FairCom DB requires a dummy lock file or use of the Extended Lock Strategy, discussed above, when using environments not supporting robust write locks. For example, platforms only supporting exclusive record locks. No other process can read or write an exclusively locked record. FairCom DB does not require such strong locks. A write lock allows other processes to read the locked record, but not write it. To simulate write locks, FairCom DB secures true exclusive record locks on phantom regions of the dummy file. The dummy file is a separate FairCom DB data file used to help control record locking. Since the lock is held in a separate file, the virtual file logic does not affect locks held on the dummy lock file.

If two applications share one or more files in a multi-user FairCom DB environment using a dummy file, the following conditions must be met:

• They must use the same dummy lock file which must be numbered zero in the ISAM parameter file, or use the same IFIL structures with dfilno set to zero, or be assigned file number 0 if using low level functions.
• The dummy lock file should be opened before any other ctree files.
• Files shared between the applications must be assigned the same FairCom DB file numbers.
• Files not in common must not be assigned the same file numbers.
• There are artificial limitations on the quantity of concurrently open files and the maximum size of these files. In the “dummy lock file” approach, each region of data or index file is mapped to a unique byte of a single file on which the locks are actually requested. For example, an index node would be mapped to a byte in the dummy lock file based on the following equation:

node |= ((ULONG8) knum->filnum << LEFT_SHIFT);

Based on a 64 bit locking domain, the LEFT_SHIFT values yield the following constraints on quantity of concurrently opened files and the maximum file size:

LEFT_SHIFT	files	max size of fixed records	max size of variable-length file
48	65534	256 TB records	2560 TB file
49	32766	512 TB records	5120 TB file

In the above table, “256 TB records” means that a fixed-length data file can contain up to 256 * 1024 * 1024 * 1024 * 1024 records regardless of the record length. By comparison, the variable-length file limit is on the actual file size. The default LEFT_SHIFT setting is set as follows:

#define LEFT_SHIFT 49 /* Controls dummy lock capacity */

The file number dependency is because the file number is used in conjunction with the record offset to obtain a unique byte in the dummy file to lock. If the same file is opened with a different file number, the same offset would not be locked, preventing the logic from working. Additionally, all applications sharing a dummy lock file must use the same LEFT_SHIFT or the behavior is undefined.

To make it easier to assign file numbers consistent with the above three points, remember that you can inflate the fils parameter in InitISAM() or the idxs parameter of the parameter file to ensure sufficient flexibility in numbering the files. For example, if you call InitISAM() with fils set to ten (10), but you are only using two files, they can be assigned any file numbers between zero (0) and nine (9).

The dummy lock file must be assigned file number 0. This file is an optional file to enable write locks on Standalone Multi-user systems that only support exclusive locks.

NOTE: When used, a dummy lock file must always be opened as a permanent file, NOT a virtual file. Therefore, use a file mode of 3.

CAUTION: Windows OS file shares (NFS) rely on filesystem locks to maintain filesystem cache coherency. The use of a Dummy Lock File bypasses this mechanism. Updates to a shared file on NFS cannot be done safely using a Dummy Lock File. A different locking model is required to handle this safely.