FairCom — Cache and Memory

*_FLUSH_SEC background flush rate reduces contention

In FairCom DB V11.0 and later, the following background flush thread configuration options remove the dirty cache page flushing overhead from the checkpoint logic, and place this important requirement on these new dedicated background threads:

NONTRAN_DATA_FLUSH_SEC
NONTRAN_INDEX_FLUSH_SEC
TRAN_DATA_FLUSH_SEC
TRAN_INDEX_FLUSH_SEC

This change reduces the time that other threads are blocked waiting to acquire the update list mutex and has smoothed out performance curves for high-speed systems. If you would like a more thorough refresher on this change, please review this topic in the V11.0 Update Guide: Controls for Performance AND Safety of Non-Transaction Updates.

Configuring background flush at a given rate

Starting with FairCom DB V11.5, it’s now possible to configure a fixed rate of background flushing of updated data cache pages and index buffers, which provides the ability to further smooth out performance curves, reducing periodic drops in performance. The two parameters that can be specified for the background flushing are:

msec - The time in milliseconds to defer after flushing, and
nfls - The number of flushes after which the defer occurs.

With this new change, the keywords now support specifying these new parameters using the syntax rate=<msec>/<nfls>.

For example, to defer for 1 millisecond after every two flushes of updated TRNLOG data cache pages, use this option:

TRAN_DATA_FLUSH_SEC rate=1/2

The rate value sets a maximum speed at which the background flush threads will write updated buffers to disk. The goal is to flush updated pages quickly enough that the total number of updated buffers does not become extremely large (which could cause the number of transaction logs to increase and could cause checkpoints to take more time to build the list of updated pages and their corresponding transaction numbers and write them to disk), without flushing at too fast a rate, which would impact performance. The msec and nfls values can be used to set the maximum rate of flushing. FairCom suggests starting with rate=1/1, which means delay for one millisecond after every buffer flush. In our testing, we have found 1/1, or 1/2 to be the optimal settings.

BUFBLK_RATIO

BUFBLK_RATIO <ratio of index cache pages to block list mutexes>

The default ratio is 64. This means a block list mutex for every 64 index cache pages. The BUFBLK_RATIO keyword can override the default. A ratio of one (1) means a mutex for every cache page. A configuration entry of zero is ignored (and the compile-time default is used). The advantage of the ratio specification is that the BUFBLK configuration entry does not have to be changed when the IDX_MEMORY entry is changed.

Note Contact FairCom for details on this extremely advanced configuration option as this can severely impact online performance.

BUFFER_RUNLENGTH

BUFFER_RUNLENGTH <number of write operations>

This setting should be changed only at the request of your application developer. BUFFER_RUNLENGTH specifies the number of consecutive write operations performed while walking a list of buffer/cache pages before allowing other threads to acquire control of the list. A negative value is ignored.

Default: 10

BUFR_MEMORY

BUFR_MEMORY <bytes>

Specifies the size of memory blocks the FairCom Server uses in conjunction with data and index cache buffers. To minimize interaction with the underlying system memory manager, the FairCom Server manages its own blocks of memory out of which the buffer pages are allocated. The FairCom Server acquires one large block of memory and allocates smaller pieces as needed. If you are attempting to limit memory use by reducing IDX_MEMORY and/or DAT_MEMORY, set BUFR_MEMORY to about one eighth of the smaller of IDX_MEMORY and DAT_MEMORY.

Default: 64000

See Also

DAT_MEMORY
IDX_MEMORY
TOT_MEMORY (deprecated - not recommended)
USR_MEMORY

CACHE_STAT_ARRAY_SIZE

CACHE_STAT_ARRAY_SIZE <number>

By default, cache hit counters are allocated for each CPU available to the server. In v11.0 and later, you can override the number of cache hit counters by specifying a lower number with this keyword. For example, adding CACHE_STAT_ARRAY_SIZE 1 would limit the server to a single cache hit counter.

COMPATIBILITY LARGE_CACHE

COMPATIBILITY LARGE_CACHE

To configure large data and index cache sizes, add COMPATIBILITY LARGE_CACHE to the FairCom Server configuration file. This keyword permits the DAT_MEMORY and IDX_MEMORY values to be reinterpreted as megabytes instead of bytes.

If the byte value in the configuration file is less than or equal to 64000, then the value is reinterpreted as megabytes. This permits up to 64GB of index or data cache to be requested. If the value is greater than 64000, it is interpreted as bytes (just as without the LARGE_CACHE option). If the LARGE_CACHE option is not used, the values for DAT_MEMORY and IDX_MEMORY are interpreted as bytes, regardless of their values.

Example

COMPATIBILITY  LARGE_CACHE
IDX_MEMORY     100000000
DAT_MEMORY     4096

Requests 100 million bytes of index cache, and 4 GB of data cache.

Limitations

The FairCom Server does not check that the specified amount of memory actually exists as available physical memory on the system. To avoid FairCom Server startup errors or performance degradation due to memory swapping, ensure that enough physical memory is available to accommodate the specified data and index cache sizes.
The FairCom Server does not support this option on systems that do not support LARGE_CACHE. These systems are identified as 32-bit systems that do not have SYS_LONG8 defined in their ctcmpl.h include file.

COMPATIBILITY MINIMUM_INDEX_BUFFERS

COMPATIBILITY MINIMUM_INDEX_BUFFERS

In V11.1 and later, the FairCom Server will prevent the index cache memory from going higher than the value specified by the IDX_MEMORY keyword by limiting the number of threads that can concurrently work on index updating, if necessary.

Add COMPATIBILITY MINIMUM_INDEX_BUFFERS to the ctsrvr.cfg file to restore the previous behavior where the index cache memory was expanded past the specified limit to allow more concurrent index threads.

DAT_MEMORY

DAT_MEMORY <bytes>

The memory allocated to the data cache, specified in bytes. Within the memory constraints of the hardware, there is no effective limit.

Default: 100 MB

Note Prior to V11, the default value for both the standard FairCom DB Server and the FairCom DB SQL Server was 600 * PAGE_SIZE. Assuming a default page size of 8192, the default DAT_MEMORY would be 4915200.

See Also

BUFR_MEMORY
IDX_MEMORY
TOT_MEMORY (deprecated - do not use)
USR_MEMORY

DATA_LRU_LISTS

DATA_LRU_LISTS <number of lists>

Note The LRU algorithm is no longer used for the data cache.

To reduce mutex contention, the cache control model permits the configuration keywords DATA_LRU_LISTS and INDEX_LRU_LISTS to specify how many LRU lists are maintained for data cache pages and index cache pages, respectively.

On Windows, Solaris, and AIX, the default is based on the number of available CPUs on the system and the CPU limit specified in the license file. Otherwise, DATA_LRU_LISTS defaults to 4.

See Also

INDEX_LRU_LISTS

GUEST_MEMORY

GUEST_MEMORY <bytes>

If greater than zero, this is the memory usage limit in bytes for a user without a User ID (i.e., a GUEST user).

Default: 0

IDX_MEMORY

IDX_MEMORY <bytes>

The memory allocated to the index cache, specified in bytes. Within the memory constraints of the hardware, there is no effective limit. High-speed buffer search routines ensure quick access to the entire cache.

Default: 100 MB

Note Prior to V11, the default value for both the standard FairCom DB Server and the FairCom DB SQL Server was 600 * PAGE_SIZE. Assuming a default page size of 8192, the default DAT_MEMORY would be 4915200.

See Also

BUFR_MEMORY
DAT_MEMORY
TOT_MEMORY (deprecated - not recommended)
USR_MEMORY

INDEX_LRU_LISTS

INDEX_LRU_LISTS <number of lists>

To reduce mutex contention, the new cache control model permits the configuration keywords DATA_LRU_LISTS and INDEX_LRU_LISTS to specify how many LRU lists are maintained for data cache pages and index cache pages, respectively.

On Windows, Solaris, and AIX, the default is based on the number of available CPUs on the system and the CPU limit specified in the license file. Otherwise, INDEX_LRU_LISTS defaults to 4.

See Also

DATA_LRU_LISTS

LIST_MEMORY

LIST_MEMORY <bytes>

Indicates the size of the memory blocks that are allocated by FairCom Server for internal in-memory data structures. It does not represent the actual memory size of a specific table and/or structure.

To conserve memory, this keyword can be set to a low value, such as 4096.

In situations with large amounts of available memory, the value can be increased beyond the default up to the maximum limit. This can improve performance at the expense of increased memory usage.

The vast majority of our customers never set this value to more than 1MB, which is a good compromise between memory usage and performance gains.

Maximum: 10MB

Default: 16384

LMT_MEMORY

LMT_MEMORY <limit>

Sets the maximum size for a single allocation using the FairCom DB memory suballocator. If this limit is exceeded a message is output to CTSTATUS.FCS and a NULL memory pointer is returned.

Default: 2GB

Note A terr(7491) occurs and an informative message is sent to CTSTATUS.FCS.

In FairCom DB V11 and later:

Prior to this modification, FairCom Server's LMT_MEMORY configuration option defaulted to 128MB, meaning that a single memory allocation could not exceed 128MB. However, this limit restricted the size of variable-length records from FairCom Server and limited the amount of memory that could be allocated with the RECOVER_MEMLOG recovery option.

This limit has been disabled by default. If LMT_MEMORY is not specified, FairCom Server does not place a limit on the size of a single memory allocation. If desired, LMT_MEMORY can be specified in ctsrvr.cfg setting a desired maximum allocation size.

Note This modification results in a behavior change.

This change also applies to standalone mode: #define ctMEMLMT is set to zero by default, meaning no memory allocation size limit. If desired, FairCom DB can be compiled with ctMEMLMT defined to a non-zero value.

MEMORY_HASH

The FairCom DB internal memory suballocator utilizes 11 lists, each dedicated to a particular range of allocation size and each controlled by a single mutex. An expanded model improves scalability, especially when a large number of memory allocation or free operations take place at once.

The server configuration keyword MEMORY_HASH <N> causes 11N lists to be created, with N dedicated to a particular range of allocation size. On Windows, Solaris, and AIX, the default is based on the number of available CPUs on the system and the CPU limit specified in the license file. Otherwise, MEMORY_HASH defaults to 4.

The MEMORY_HASH configuration requires aligned memory boundaries. If a particular server build is compiled without the proper alignment property, a messages is logged to CTSTATUS.FCS indicating this when this keyword is active:

- User# 00001 Configuration error: ctsrvr.cfg, line 3: This c-tree Server does not meet the compile-time requirements to support the MEMORY_HASH keyword.

MPAGE_CACHE

MPAGE_CACHE <bytes>

The FairCom DB data cache uses the following approach to cache data record images:

If the data record fits entirely within one or two cache pages (PAGE_SIZE bytes per cache page), then the entire record is stored in the cache.
If the data record image covers more than two cache pages, then the first and last segments of the record are store in the cache, but the middle portion is read from or written to the disk. These direct I/O’s are efficient operations since they are aligned and are for a multiple of the cache page size.

The nature of this approach can be modified. Set MPAGE_CACHE to a value greater than zero, N, to store records falling within N+2 cache pages entirely within the cache. The default value is zero, behaves as described above.

Note Setting MPAGE_CACHE greater than zero does NOT ensure faster system operation. It is more likely to be slower than faster. It does cause more of a record to be in cache, but there is increased overhead managing each individual cache page. The cache pages for consecutive segments of a record (where a segment fills a cache page) are completely independent of each other. They are not stored in consecutive memory and I/O is performed separately for each cache page. This configuration option should only be used for special circumstances with careful, realistic testing.

Even a record smaller than a single cache page may require two cache pages because the record position is generally not aligned on a cache page boundary.

Default: 0

NO_CACHE

NO_CACHE   <data file name>

In some cases, it might be beneficial to define that a certain file NOT be cached. For example, if a file contains very large variable length records (BLOBS), it might be more efficient to bypass the cache and rely solely on the operating systems cache support. The FairCom Server does not store the full variable length record in cache, but retains the first and last page of the variable length record. This prevents large blocks of data from consuming the cache and also alleviates the management of a large number of cache pages for any one particular record. NO_CACHE disables cache for a given file.

Note <data file name> may include a wildcard pattern using ‘?’ for a single character and ‘*’ for zero or more characters. See FairCom DB Standard Wildcards. The Server Administrator can specify multiple NO_CACHE configuration entries.

Caching can only be turned off for entire superfiles (i.e., the superfile host), not for individual superfile members. Index files require the use of index cache pages and must be cached.

Default: Cache files

NONTRAN_FILESYS_FLUSH_OFF

NONTRAN_FILESYS_FLUSH_OFF  <YES | NO>

FairCom DB suppresses calls to flush updated file system cache pages to disk for all non-TRNLOG data and index files, except during a call to CTFLUSH(). This is a performance enhancement for non-transaction and PREIMG files.

Note that this default behavior may introduce a vulnerability to possible data loss in the event of a system crash if updates to a FairCom DB data or index file have been written to the file system cache but not yet written to disk. This can be mitigated by installing a battery backup (UPS) on the system so the file-system cache can still be flushed in case of a power failure. Note that this does not introduce any vulnerability involving abnormal termination of the FairCom DB Server process, as it only affects file system caching, not c-tree caching behavior.

YES suppresses the flush calls, and NO enables the flush calls. This option can also be changed at runtime.

PRIME_CACHE

The FairCom Server optionally maintains a list of data files and the number of bytes of data cache to be primed at file open. When priming cache, the server reads the specified number of bytes for the given data file into data cache when physically opening the data file.

Data files are added to the priming list with configuration entries of the form:

PRIME_CACHE   <data file name>#<bytes primed>

For example, the following keyword instructs the server to read the first 100,000 bytes of data records from customer.dat into the data cache at file open:

PRIME_CACHE   customer.dat#100000

A dedicated thread performs cache priming, permitting the file open call to return without waiting for the priming to be accomplished.

Use PRIME_CACHE with the SPECIAL_CACHE_FILE keyword to load dedicated cache pages at file open.

A <data file name> or <index file name> can be a wildcard specification using a ‘?’ for a single character and a ‘*’ for zero or more characters. See FairCom DB Standard Wildcards.

Default: No priming

See Also

PRIME_CACHE_AT_STARTUP

PRIME_INDEX (PRIME_INDEX, Prime Index)

PRIME_CACHE_BY_KEY

PRIME_CACHE_AT_STARTUP

These features are available beginning with V13.

FairCom Server technology supports configuration options that are used to prime the server's data and index caches when the server starts up. The functionality is similar to cache priming configuration options PRIME_CACHE, PRIME_CACHE_BY_KEY, and PRIME_INDEX, except that those options take effect only when an application opens the files.

This feature relies on atomic operations. If atomic operation support is off at compile time, the feature will be disabled.

The new configuration options are specified in JSON format, such as in the following example:

subsystem cache prime_cache_at_startup {
    "allow_connections": true,
    "thread_count": 8,
    "prime_cache": [
        {"file": "filename1.dat", "size": "1 gb"},
        {"file": "filename2.dat"}
    ],
    "prime_cache_by_key": [
        {"file": "filename1.dat", "size" : "1 gb", "index": 1, "reverse": false},
        {"file": "filename2.dat", "size" : "1 gb", "index": 1}
    ],
    "prime_index": [
        {"file": "filename1.dat", "size": "1 gb", "index": 1},
        {"file": "filename2.dat", "size": "1 gb", "index": 1}
    ]
}

Supported attributes:

allow_connections is a boolean value that indicates if connections to the server are allowed while the cache priming is performed at server startup. Defaults to false.
thread_count is an integer value that sets the number of threads to use to prime the cache. It defaults to 4. Maximum is 255.
prime_cache is an array of names of data files that are to be read into the cache in physical order, and an optional size indicating the maximum number of bytes to read into data cache for the file. The file name is a string. The file name can include wildcard characters (for example, *.dat). The wildcard characterdoes not recurse into subdirectories. The size can include a suffix, such as kb, mb, gb, tb (for example, "1 gb"). If size is not specified, the entire file is read into the data cache.
prime_cache_by_key is an array of names of data files that are to be read into the cache in the order of the specified index. The index number is a positive value, where 1 means the first index. If the index number is omitted, the first index is used. Size has the same definition as for prime_cache. Reverse is a boolean indicating whether the key traversal is in ascending or descending key order.
prime_index is an array of names of index files that are to be read into the index cache. Size and index have the same meaning as for prime_cache_by_key.

In addition to the specified size limits, the data and index cache sizes limit the cache priming as follows:

prime_cache and prime_cache_by_key stop if the data cache becomes full.

prime_index stops if the index cache becomes full.

The SUBSYSTEM CACHE PRIME_CACHE_AT_STARTUP configuration option can be specified in a server settings file. If it is used in a settings file, the option cannot also be used in the configuration file. In that case, the subsystem is considered blocked and the configuration file options are ignored. Likewise, if this subsystem is specified more than once in the configuration file, only the first occurrence of the subsystem block takes effect. The other occurrences are ignored.

The subsystem can be commented out by placing a semicolon at the start of the SUBSYSTEM line. However, individual lines within the subsystem block cannot be commented out. Attempting to do so will cause a syntax error.

By default, the server logs information about the files that it loads into cache to CTSTATUS.FCS. The configuration option CTSTATUS_MASK PRIME_CACHE_AT_STARTUP can be used to disable this logging.

See Also

PRIME_INDEX (PRIME_INDEX, Prime Index)

PRIME_CACHE

PRIME_CACHE_BY_KEY

PRIME_INDEX

The FairCom Server optionally maintains a list of data and index files and the number of bytes of data and/or index cache to be primed at file open. When priming cache, the server reads the specified number of bytes for the given data file into data cache when physically opening the data file.

To prime index files, use configuration entries of the form:

PRIME_INDEX  <idx file name>#<bytes primed>[#<member no>]

If the optional <member no> is omitted, all index members are primed. If an index member number is specified, only that member is primed. For example, the following keyword instructs the server to read the first 100,000 bytes of index nodes in customer.idx into the index buffer space at file open:

PRIME_INDEX   customer.idx#100000

The nodes are read first for the host index, and then for each member until the entire index is primed or the specified number of bytes has been primed.

The following example restricts the priming to the first member (the index after the host index):

PRIME_INDEX   customer.idx#100000#1

A <data file name> or <index file name> can be a wildcard specification using a ‘?’ for a single character and a ‘*’ for zero or more characters. See FairCom DB Standard Wildcards.

Default: No priming

See Also

PRIME_CACHE (PRIME_CACHE, Prime Cache)

PRIME_CACHE_BY_KEY

PRIME_CACHE_BY_KEY <data_file_name>#<data_record_bytes_to_prime>#<index_number>

The PRIME_CACHE configuration option supports priming the data cache with the specified number of bytes of data from the specified data file, in physical order from the start of the data file. PRIME_CACHE_BY_KEY supports priming the data cache in forward AND reverse order by index.

data_file_name specifies the name of the c-tree data file whose records are to be read into the FairCom Server’s cache. The file name may include wildcard characters (see FairCom DB Standard Wildcards).
data_record_bytes_to_prime specifies the maximum number of bytes of data records to read into the FairCom Server’s cache.
index_number specifies the relative key number of the index to use when reading the data records. Specify 1 to indicate the first index, 2 to indicate the second index, etc., based on the index definitions stored in the data file’s IFIL resource. Specify a negative value to indicate that records should be read in reverse key order by that index.

Example

PRIME_CACHE_BY_KEY mark.dat#100000000#-1

Primes up to 100,000,000 bytes from mark.dat reading by the first index in reverse key order.

See Also

PRIME_CACHE and PRIME_INDEX

SET_CACHE_OPTIONS

Memory caching of data is one of the most important subsystems of a database server, including FairCom DB. Caching allows the database process to optimally serve clients with data directly from memory when possible. Separate independent memory caches are used for data and indexes (buffers). Proper cache sizing is a critical performance tuning task of the database administrator. Too little memory, and the database engine becomes bottlenecked with persisted storage I/O. Too much, and not enough memory is made available to the operating system and other applications running on the host machine.

Cache resizing is a powerful feature for performance tuning with increasing database loads. Adding additional client connections, thus increasing user concurrency, frequently benefits from larger caches. Another situation is a very large ad-hoc database load or query where temporarily having a larger memory cache improves overall performance. Changing a cache size requires restarting the FairCom DB server process which is not an easy task in the 24/7 enterprise environment.

FairCom DB "hard" allocates memory for caches at server startup directly from the OS memory heap. Once allocated, the memory is permanently associated with the database for the life of the process. Allocated memory is chunked into page size blocks within the memory cache subsystem, historically making it difficult to resize as needed. An additional complication is how to handle existing data residing in cache. Losing that "hot" data will likely result in performance loss for connected applications until a runtime steady state is again achieved over time.

FairCom has had increasing requests for ability to change cache sizes at runtime and this release introduces dynamic cache resizing. Now, you can fine tune data and index caches as performance demands based on database connections and load avoiding costly database down time.

dynamic_cache_resize_flat_wide

How to Resize Your Current Cache

The server administrator utility, ctadmn, supports a new configuration option set_cache_options as a parameter. This is followed with a null-terminated JSON string with desired options. Supported cache options are as follows:

"timeout": <timeoutInSeconds> where <timeoutInSeconds> is the maximum number of seconds to wait for active transactions to complete when quiescing the server in order to change the cache sizes. The default timeout is 1 second.
"dat_memory": "<new_data_cache_size>" where <new_data_cache_size> is an integer cache size followed by optional suffix such as mb for megabytes or gb for gigabytes. For example, "dat_memory": "100 mb". If not specified, the data cache size is not changed.
"idx_memory": "<new_index_cache_size>" where <new_index_cache_size> is an integer cache size followed by optional suffix such as mb for megabytes or gb for gigabytes. For example, "idx_memory": "200 mb". If not specified, the index cache size is not changed.
"keep_cached_data": "<yes_or_no>" where <yes_or_no> is either yes, which means the currently-cached data is kept in the data cache, or no, which means the currently-cached data is removed from the data cache. The default is yes.
"keep_cached_nodes": "<yes_or_no>" where <yes_or_no> is either yes, which means the currently-cached nodes are kept in the index cache, or no, which means the currently-cached nodes are removed from the index cache. The default is yes.

Administrator Utility Usage

From ctadmn, choose option 10 "Change the specified configuration option"


                Change Server Settings:

                         1. Configure function monitor
                         2. Configure checkpoint monitor
                         3. Configure memory monitor
                         4. Configure request time monitor
                         5. Change dynamic dump sleep time
                         6. Change dynamic dump sleep interval
                         7. Enable or disable a status log mask option
                         8. Change advanced encryption master password
                         9. Change a DIAGNOSTICS option
                        10. Change the specified configuration option
                        11. Change Logon Block Settings

        Enter your choice (1-11), or 'q' to return to previous menu>> 10

Enter the configuration option and its value >> set_cache_options {"dat_memory": "200 mb"}

Successfully changed the configuration option.


Press RETURN to continue...

Expected Status Log Messages

The resize request triggers an internally generated server quiesce state with the following common messages.


Mon Jun 13 13:47:51 2022 - User# 00030 ctQUIET: attempt quiet transaction state with action: 1100a0x  timeout: 1 sec
Mon Jun 13 13:47:51 2022 - User# 00030 ctQUIET: blocking call with action: 641a2x
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 33: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 40: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 47: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 52: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 58: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 65: 817
Mon Jun 13 13:47:54 2022 - User# 00030 ctQUIET: end of blocking call
Mon Jun 13 13:47:54 2022 - User# 00030 Using 3 index node LRU lists with 3962 buffers per list
Mon Jun 13 13:47:54 2022 - User# 00030 ctQUIET: unblocking call with action: 809e00x
Mon Jun 13 13:47:55 2022 - User# 00030 ctQUIET: end of unblocking call

Examples

Set data cache size to 100 MB and keep existing data in cache (since "keep_cached_data" defaults to "yes"). No change to index cache. In this example, if data cache is already 100 MB, no action is taken:

set_cache_options {"dat_memory": "100 mb"}

Set data cache size to 100 MB and remove all data from data cache:

set_cache_options {"dat_memory": "100 mb", "keep_cached_data": "no"}

Keep current data cache size and remove all data from data cache:

set_cache_options {"keep_cached_data": "no"}

Set index cache size to 200 MB and keep existing nodes in cache:

set_cache_options {"idx_memory": "200 mb"}

Set index cache size to 200 MB and remove all nodes from index cache:

set_cache_options {"idx_memory": "200 mb", "keep_cached_nodes": "no"}

Keep current index cache size and remove all nodes from index cache:

set_cache_options {"keep_cached_nodes": "no"}

This example shows actions on both data and index cache:

set_cache_options {"dat_memory": "500 mb", "idx_memory": "400 mb", "keep_cached_nodes": "no", "timeout": 5}

Direct SDK API

An application that is logged in as the ADMIN user can change data and/or index caches by calling the ctSETCFG() API function with option of setcfgCONFIG_OPTION and value set to:

set_cache_options {<cache_options>}

where <cache_options> is the null-terminated string in JSON format.

This example showing how to change the cache sizes in C or C++ code by calling the ctSETCFG() API function:

NINT  rc;
rc = ctSETCFG(setcfgCONFIG_OPTION, "set_cache_options {\"dat_memory\": \"100 mb\"}");

Diagnostic Logs

The configuration option DIAGNOSTICS RESIZE_CACHE, which can be specified in ctsrvr.cfg and changed at runtime, causes cache resize diagnostic messages to be logged to CTSTATUS.FCS.

SORT_MEMORY

SORT_MEMORY <bytes>

Specifies the size of sort buffers used by the FairCom Server. To conserve memory, set this value to 8192 or 4096. If large amounts of memory are available, the value can be increased significantly beyond the default. This value must be less than the maximum segment size in segmented architectures.

The SORT_MEMORY keyword specifies the memory size in bytes and can use the MB and GB keywords (unlike MAX_K_TO_USE).

The maximum SORT_MEMORY value is:

4 TB - 1 for 64-bit FairCom DB
4 GB - 1 for 32-bit FairCom DB

As the SORT_MEMORY option is more intuitive, its use is recommended over MAX_K_TO_USE. (MAX_K_TO_USE remains available for backward compatibility). If both SORT_MEMORY and MAX_K_TO_USE are specified in ctsrvr.cfg, only the one that is specified last in the configuration file takes effect.

Default: 100 MB

See Also

SPECIAL_CACHE_FILE

SPECIAL_CACHE_FILE  <datafilename>#<bytes to cache>

Note This keyword was removed in V11 and later (notice this impacts FairCom RTG V2.0 and later). We are in the process of reintroducing this support into V12 (FairCom RTG V3.0). This keyword is still accepted by the parsing engine, and the Server engine will start, however the support is inactive so there are no benefits to adding this keyword at this time.

Dedicates a specified amount of cache memory to a particular Extended data file. This allows the Server Administrator to specify files that are critical to maintain in cache memory at the expense of the “least-recently-used” (LRU) approach, where a new cache page replaces the LRU existing page.

For example, the following keywords specify 100,000 bytes of dedicated cache for customer.dat and 400,000 bytes for data\inventory.dat:

SPECIAL_CACHE_FILE   customer.dat#100000
SPECIAL_CACHE_FILE   data\inventory.dat#400000

The <datafilename> can be a wildcard specification using a ‘?’ for a single character and a ‘*’ for zero or more characters. See FairCom DB Standard Wildcards.

Default: None

See Also

SPECIAL_CACHE_PERCENT

SPECIAL_CACHE_PERCENT   <percentage>

Note This keyword was removed in V11 and later (notice this impacts FairCom RTG V2.0 and later). We are in the process of reintroducing this support into V12 (FairCom RTG V3.0). This keyword is still accepted by the parsing engine, and the Server engine will start, however the support is inactive so there are no benefits to adding this keyword at this time.

Specifies the percentage of the overall data cache space that may be dedicated to individual files. For example, the following keyword would permit up to 10% of the total data cache pages to be assigned to files on the special cache file list:

SPECIAL_CACHE_PERCENT    10

To disable any special cache, enter -1 for the percentage. The percentage defaults to 50% and the maximum amount that can be specified with the keyword is 90%.

Default: 50%

See Also

SPECIAL_CACHE_FILE

TOT_MEMORY

TOT_MEMORY <bytes>

This keyword has been Deprecated.

If greater than zero, the total number of bytes the system will attempt to allocate for all uses (including index and data caches specified by the IDX_MEMORY and DAT_MEMORY keywords). If the system usage exceeds this level, attempts will be made to reduce discretionary allocations. If zero, no memory limit is imposed.

The TOT_MEMORY option will cause an operation to fail with an insufficient memory error such as TSHD_ERR (72) or QMEM_ERR (92) when the memory limit is reached. If this limit is exceeded, it may cause a user to flush preimage memory, but it will cause a TSHD_ERR (72) if the system limit is exceeded during preimage operations.

Memory management attempts to permit the server to survive exceeding the optional TOT_MEMORY limit. Although every effort is made to avoid this situation, it is possible that using this option could cause FairCom Server to terminate if it needs memory in a critical situation and cannot get memory, even if memory is available on the system. For these reasons, the use of this option can be risky.

Default: 0

See Also

USR_MEM_RULE

USR_MEM_RULE <GUIDELINE | ABSOLUTE>

The system default rule for FairCom Server action when a user exceeds his/her memory limit. This rule is employed only if the System Administrator has not assigned a rule specifically to the user or the user’s primary group.

Valid values are:

ABSOLUTE - The memory limit set for a user is to be applied as given, so no additional memory beyond the established limits will be allocated if it is requested.
GUIDELINE - The memory limit set for a user guides memory allocation as follows: allow the user to have requested memory beyond the limit set, if it is available, and when another user needs that memory, then it reduces the amount of memory used back down toward the guideline as soon as possible (e.g., by moving memory resident information to disk).

Default: GUIDELINE

See Also

USR_MEMORY

USR_MEMORY

If greater than zero, this is the system default limit of memory (in bytes) available to each user. Zero means no user system default limit is imposed. The Administrator overrides this setting for a particular user by assigning a different value to the user or to the user’s primary Group.

Default: 0

See Also

BUFR_MEMORY
DAT_MEMORY
IDX_MEMORY
TOT_MEMORY (deprecated - not recommended)
USR_MEM_RULE

Cache and Memory

*_FLUSH_SEC background flush rate reduces contention

BUFBLK_RATIO

BUFFER_RUNLENGTH

BUFR_MEMORY

CACHE_STAT_ARRAY_SIZE

COMPATIBILITY LARGE_CACHE

COMPATIBILITY MINIMUM_INDEX_BUFFERS

DAT_MEMORY

DATA_LRU_LISTS

GUEST_MEMORY

IDX_MEMORY

INDEX_LRU_LISTS

LIST_MEMORY

LMT_MEMORY

MEMORY_HASH

MPAGE_CACHE

NO_CACHE

NONTRAN_FILESYS_FLUSH_OFF

PRIME_CACHE

PRIME_CACHE_AT_STARTUP

PRIME_INDEX

PRIME_CACHE_BY_KEY

SET_CACHE_OPTIONS

SORT_MEMORY

SPECIAL_CACHE_FILE

SPECIAL_CACHE_PERCENT

TOT_MEMORY

USR_MEM_RULE

USR_MEMORY

Was this article helpful?

Related Articles

Data Integrity

Working with Resources

DB SQL system catalog tables