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.
• 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 |= ((LONG) knum->filnum << LEFT_SHIFT);

Based on a 2GB 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 file
25	62	max 32 MB records	320 MB variable-length file
24	126	max 16 MB records	160 MB variable-length file
23	254	max 8 MB records	80 MB variable-length file
22	510	max 4 MB records	40 MB variable-length file

In the above table, “max 32 MB records” means that a fixed-length data file can contain up to 32 * 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 24 /* 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.

In order 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.