Transaction Processing

AUTO_CLNIDXX

AUTO_CLNIDXX YES

Optionally permits automatic CLNIDXX() during file open when a transaction high water mark, hghtrn, is found at file open to exceed the current transaction number.

The disadvantage of this approach is that it is necessary to traverse all the index leaf nodes, writing those to disk that have been cleaned. For a very large index, this could be time consuming. Only customers that have experienced problems with HTRN_ERR (520) are candidates to use this configuration option. Also, internal, administrative requests to open the file read only (say as part of a dynamic dump or ctFILBLK() processing) are denied if the file is in the middle of an on the fly CLNIDXX().

CTSTATUS.FCS receives messages concerning on the fly CLNIDXX(). Both success and failure are noted.

AUTO_PREIMG

AUTO_PREIMG <filespec>

Allows newly created non-transaction files to be created in PREIMG mode. These will automatically switch back to non-transaction when accessed by a non-transaction application. Files already created, but opened by a server with an applicable AUTO_PREIMG will be switched to PREIMG unless the file is an index without room for key level locks. Such a failed conversion at open is noted in CTSTATUS.FCS. filespec may contain wildcards.

Not only are files switched to PREIMG mode, but automatic ISAM PREIMG transactions will be launched. This permits an application to be run without any code change, and only a change to the configuration file if it is desired to use PREIMG files.

If a file is included in both AUTO_PREIMG and AUTO_TRNLOG, entries, then the AUTO_PREIMG entry will prevail.

Note Consistency between data files cannot be ensured unless explicit transactions that preserve atomicity of updates are implemented by the application.

This also supports automatic transactions for low level operations if and only if the file in question has been opened under transaction control because of AUTO_PREIMG or AUTO_TRNLOG, configuration entries. By low level operations we mean updates to a data or index file that result from non-ISAM level API calls such as WRTREC(), NEWVREC() or ADDKEY(). Even if the file is included in one of these configuration entries, automatic low level transactions will not occur if the file is opened with inherent transaction attributes.

The server configuration keyword PREIMAGE_DUMP causes PREIMG files included in a dynamic dump to be automatically changed to TRNLOG files during the dump. Therefore, files converted by AUTO_PREIMG can be included in a dynamic dump that invokes the PREIMAGE_DUMP option. Each data file and associated indexes will be restored to a consistent point.

Note AUTO_PREIMG accepts wildcard file specifications (see FairCom DB Standard Wildcards).

Files that already have transaction attributes are not affected by the configuration entries. An index file or c-tree Superfile host created without transaction support (and without these keywords) will not be able to be switched at open to transaction support. If such a file is included in the configuration lists for these key words, then the open will cause a CTSTATUS.FCS warning message with the name of the file.

See Also

AUTO_TRNLOG

AUTO_TRNLOG_LIGHT

DIAGNOSTICS AUTO_TRNLOG_CHECKLOCK

DIAGNOSTICS AUTO_PREIMG_CHECKLOCK

DIAGNOSTICS AUTO_TRNLOG_CHECKREAD

DIAGNOSTICS AUTO_PREIMG_CHECKREAD

PREIMAGE_DUMP

AUTO_RESTORE_POINT (SUBSYSTEM)

FairCom Server supports a configuration option to automatically perform restore points. This option can be set in the configuration file using the SUBSYSTEM TRNLOG AUTO_RESTORE_POINT block. The supported sub-options are:

• LOG_INTERVAL N, where is the number of logs between each automatic restore point. Specify 1 to write an automatic restore point to every log. Specify 0 to turn off automatic restore points. LOG_INTERVAL defaults to zero (no automatic restore points).
• TIMEOUT T, where T is a time in seconds that the automatic restore point waits for active to transactions to commit. TIMEOUT defaults to 2 seconds.
• FAIL_AFTER_TIMEOUT F, can be YES or NO: YES indicates that if transactions remain active after the restore point timeout period, the restore point call fails; NO indicates that if transactions remain active after the restore point period, those transactions are aborted and the restore point is logged. FAIL_AFTER_TIMEOUT defaults to NO.
• CHECKPOINT C, where C is YES or NO. YES indicates that a checkpoint is to be logged with the restore point; NO indicates that no checkpoint is to be logged with the restore point. CHECKPOINT defaults to NO.

Example:

SUBSYSTEM TRNLOG AUTO_RESTORE_POINT {
    ; write an automatic restore point every 2 logs
    LOG_INTERVAL        2

    ; wait for up to 3 seconds for transactions to finish
    TIMEOUT             3

    ; fail if transactions remain active after timeout
    FAIL_AFTER_TIMEOUT  YES

    ; write a checkpoint
    CHECKPOINT          YES
}

Changing automatic restore point settings at runtime

Automatic restore point settings can be changed at runtime by using the ctSETCFG() API function. For example:

rc = ctSETCFG(setcfgCONFIG_OPTION, "subsystem trnlog auto_restore_point {\n\
 log_interval 2\n\
 timeout 3\n\
 fail_after_checkpoint yes\n\
 checkpoint yes\n}");

ctadmn use of ctSETCFG()

The ctadmn utility's "Change the specified configuration option" option uses this function, and it now detects when a SUBSYSTEM configuration option is specified. In that situation, it prompts for the SUBSYSTEM sub-options. Here is an example demonstrating how to use ctadmn to turn off automatic restore points at runtime:

10. Change Server Settings
10. Change the specified configuration option
Enter the configuration option and its value >> subsystem trnlog auto_restore_point {
Enter the SUBSYSTEM options you wish to change, one per line.
Finish with a line containing only a closing curly brace: }
To cancel, enter a line containing only an asterisk: *
Enter next line >> log_interval 0
Enter next line >> }
Successfully changed the configuration option.

If an error occurs when changing a SUBSYSTEM option using the ctSETCFG() function, the function returns an error code and may log a descriptive error message to CTSTATUS.FCS. Here is an example, showing a typo in which log_interval0 is specified instead of log_interval 0:

Enter the configuration option and its value >> subsystem trnlog auto_restore_point {

Enter the SUBSYSTEM options you wish to change, one per line.
Finish with a line containing only a closing curly brace: }
To cancel, enter a line containing only an asterisk: *

Enter next line >> log_interval0

Enter next line >> }

Error: Failed to change the configuration option: 749

The following error message will be logged to CTSTATUS.FCS:

Wed Jan 18 14:42:53 2017
 - User# 00018  Configuration error: ctSETCFG(), line 2: The option LOG_INTERVAL0 is not supported in the TRNLOG AUTO_RESTORE_POINT subsystem block.

Monitoring automatic restore points

The system snapshot structure, ctGSMS, now includes fields for the automatic restore point settings. The system snapshot version has been updated from 19 to 20:

 LONG sarplogint; /* auto restore point log interval */
 LONG sarptimout; /* auto restore point tran timeout */
 LONG sarplogint; /* auto restore point log interval */
 LONG sarptimout; /* auto restore point tran timeout */

/* Auto restore point options bits (ctGSMS sarpoptions field): */
#define ctARP_FAIL_AFTER_TIMEOUT 0x00000001 /* fail if trans active after timeout */
#define ctARP_WRITE_CHECKPOINT   0x00000002 /* write a checkpoint */

A text snapshot now also includes the automatic restore point settings:

        automatic restore point interval: 2
           active transaction time limit: 3
      fail if trans active after timeout: yes
                        write checkpoint: no
     log of last automatic restore point: 81

The ctsnpr utility (included in FairCom DB PRO packages in the source directory) has been updated to support the latest version of the text snapshot output format.

AUTO_TRNLOG

AUTO_TRNLOG <filespec>

Extends the automatic transaction support to include recoverable transactions without any application change. AUTO_TRNLOG, is intended to permit transaction support for applications that do not make transaction calls. See the entry on AUTO_PREIMG for more details.

If a file is included in both AUTO_PREIMG and AUTO_TRNLOG, entries, then the AUTO_PREIMG entry will prevail.

Note AUTO_TRNLOG accepts wildcard file specifications (see FairCom DB Standard Wildcards).

Files that already have transaction attributes are not affected by the configuration entries. An index file or c-tree Superfile host created without transaction support (and without these keywords) will not be able to be switched at open to transaction support. If such a file is included in the configuration lists for these key words, then the open will cause a CTSTATUS.FCS warning message with the name of the file.

See Also

AUTO_PREIMG

AUTO_TRNLOG_LIGHT

DIAGNOSTICS AUTO_TRNLOG_CHECKLOCK

DIAGNOSTICS AUTO_PREIMG_CHECKLOCK

DIAGNOSTICS AUTO_TRNLOG_CHECKREAD

DIAGNOSTICS AUTO_PREIMG_CHECKREAD

PREIMAGE_DUMP

AUTO_TRNLOG_LIGHT

AUTO_TRNLOG_LIGHT YES

AUTO_TRNLOG is intended to permit transaction support for applications that do not make transaction calls. In some instances, while the transaction support is desired, it may not be necessary to incur the full performance hit intrinsic with TRNLOG support. Adding AUTO_TRNLOG_LIGHT YES to a server configuration file means that the automatic transactions will be considered “light weight” which means that the transaction log entries are not required to be flushed to disk on an automatic commit. The default is NO: automatic transactions will invoke the strict transaction log management of regular transaction calls.

When AUTO_TRNLOG or AUTO_PREIMG are in effect, it may be desirable to know whether or not a legacy application is making “expected” lock calls

Default: NO

See Also

AUTO_PREIMG

AUTO_TRNLOG

DIAGNOSTICS AUTO_TRNLOG_CHECKLOCK

DIAGNOSTICS AUTO_PREIMG_CHECKLOCK

DIAGNOSTICS AUTO_TRNLOG_CHECKREAD

DIAGNOSTICS AUTO_PREIMG_CHECKREAD

PREIMAGE_DUMP

AUTOTRAN_ON_CREATE

AUTOTRAN_ON_CREATE

In v11.5 and later, when creating a transaction-controlled ISAM file, a transaction will automatically be started if one is not open to avoid a possible deadlock caused by starting the transaction in the middle of the file create.

Default: On

CHECKPOINT_FLUSH

CHECKPOINT_FLUSH <# of checkpoints>

This keyword sets the maximum number of checkpoints to be written before a buffer (data or index) holding an image for a transaction controlled file will be flushed. The default value is 2. A value of zero causes the buffer to be flushed at least by the occurrence of the first checkpoint written after the buffer update. Reducing the value of this system parameter reduces the amount of buffering, slowing system performance, but decreases the amount of work to be performed during recovery.

Note Enabling background transaction flush threads disables this checkpoint flush operation.

Default: 17

See Also

CHECKPOINT_INTERVAL

TRAN_DATA_FLUSH_SEC

TRAN_INDEX_FLUSH_SEC

CHECKPOINT_IDLE

CHECKPOINT_IDLE <# of seconds | -1>

Specifies the time in seconds between checkpoint checks. A checkpoint is an entry in the transaction log which lists open files, active transactions and transactions that are vulnerable due to pending buffer flushes. By default, every 300 seconds the FairCom Server checks if there has been any transaction activity, and if so, if there are any current active transactions. If there has been activity since the last checkpoint, but there is currently no active transaction, a checkpoint occurs. This strategy will not create extra checkpoints when the FairCom Server is idle, with respect to transactions, or when the FairCom Server is busy with transactions.

It is important to note that if an application routinely calls Begin() whether or not updates are imminent, this “idle” checkpoint will be inhibited because there appears to be an active transaction. The purpose of this feature is to increase the likelihood of a clean checkpoint occurring in the transaction log, thus speeding automatic recovery. Ordinarily, checkpoints occur at predetermined intervals in the transaction log. A value of negative one (-1) will disable the idle checkpoint feature.

Default: 300

CHECKPOINT_INTERVAL

CHECKPOINT_INTERVAL  <interval in bytes or MB>

This keyword can speed up recovery at the expense of performance during updates. The interval between checkpoints is measured in bytes of log entries. It is ordinarily about one-third (1/3) the size of one of the active log files (L000....FCS). Reducing the interval speeds automatic recovery at the expense of performance during updates. The entry is interpreted as bytes if greater than 100 or as megabytes if less than 100. For example, CHECKPOINT_INTERVAL 2 sets an approximate 2MB interval, while CHECKPOINT_INTERVAL 150000 causes checkpoints about every 150,000 bytes of log file.

Default: 10 MB

See Also

CHECKPOINT_FLUSH

CHECKPOINT_PREVIOUS

CHECKPOINT_PREVIOUS <YES | NO >

When automatic recovery begins, FairCom DB examines S0000000.FCS and S0000001.FCS to determine the location of the last checkpoint; which is the starting point for the automatic recovery. If the checkpoint does not appear to be valid (errors 64, RLEN_ERR and 66, RCHK_ERR), it is possible to have the server attempt to start the recovery at the location of the next to last checkpoint.

Default: NO

CHECK_SYSTEM_FILEID

CHECK_SYSTEM_FILEID <YES/NO>

CHECK_SYSTEM_FILEID YES is intended to distinguish different filesystem-level copies of files and prevent transaction recovery from applying corrections to an incorrect copy of a data or index file following a crash. Operation sequences are as follows:

1. update A.dat
2. close A.dat
3. Filesystem level copy A.dat to B.dat
4. update B.dat

These sequences are vulnerable to recovery errors if CHECK_SYSTEM_FILEID NO is disabled.
Some distributed file systems or containerized environments do not provide a stable device or inode id and will result in additional CTSTATUS.FCS messages like "reassigning file ID (sysid changed)..." when opening a file, even if the file has not been copied.

Default: Yes

CHKPDFC_LOG_LIMIT

CHKPDFC_LOG_LIMIT  <max logs w/o checkpoint>

Ordinarily, several checkpoints are expected within each FairCom Server transaction log file and the FairCom Server would terminate with error CHKP_ERR (529) when two consecutive log files without these checkpoints were encountered. The FairCom Server has been modified with respect to this absence of checkpoints. This keyword permits additional log files to be written without checkpoints. A short wait is introduced for each non-checkpoint log write, allowing a checkpoint to occur and resolving any possible race conditions.

CHKPDFC_LOG_LIMIT specifies how many consecutive logs may be processed without a checkpoint until the FairCom Server terminates. The default number of transaction logs is five log files and this may be lowered to as few as four log files or raised to any reasonable limit.

Once the checkpoint deficiency reaches two logs, the first write of each transaction commit to the transaction logs is slightly deferred. This improves the chances that the FairCom Server checkpoint thread is allotted a slice of time. Once the checkpoint is eventually written, this write log defer is removed.

CLEANUP_ABLIST_ON_ABORT

CLEANUP_ABLIST_ON_ABORT <YES | NO>

When key mark cleanup optimizations are enabled (NXTMARKS, UPDMARKS) and if a great many aborted transactions, checkpoint size becomes large due to many abort node list entries. Possible symptoms could include:

• automatic recovery could fail with RCHK_ERR due to a checkpoint that exceeded 16 MB
• slow performance

When a transaction aborts, transaction marks are now automatically cleaned in updated nodes. This behavior is on by default (YES) and can be disabled for prior compatibility.

CLEANUP_ABLIST_ON_ABORT  NO

This option can be set in your server configuration file or dynamically modified at runtime.

COMMIT_DELAY

COMMIT_DELAY <milliseconds | -1>

Controls the length of time in milliseconds after a given transaction completes that the transaction manager waits before flushing the transaction to disk. By waiting, more than one transaction (that is, the first one and all others that complete before the delay period expires) may be committed at the same time reducing disk-access overhead. On average, the longer the delay, the larger the number of transactions committed.

Note Keep this delay in mind when setting a time limit for aborting transactions.

A value of "-1" disables this support.

Note The best practice is to consider the type of storage device your transaction logs are sitting on.

Disable this support when using Solid State Disks (SSDs).

SSD use: COMMIT_DELAY -1

Enable it If you are running on a rotating hard disk.

HDD use: COMMIT_DELAY 1

Default:

Windows 2 ms.

Unix/Linux - This value defaults to 1 ms for best performance.

See Also

• COMMIT_DELAY_BASE
• COMMIT_DELAY_SCALE
• COMMIT_DELAY_USEC
• DELAYED_DURABILITY

COMMIT_DELAY_BASE

COMMIT_DELAY_BASE   <cohort size measure>

For advanced control of the intricate commit delay timing statistics, additional controls are available for the commit delay time calculation.

The cohort size measure determines the rate at which the nominal commit delay time is adjusted as the number of cohorts increases or decreases. Increasing this value tends to reduce the amount of change in the blocking time as the number of cohorts changes.

It is recommended that these values be carefully profiled as they can impact performance in many unexpected ways.

Default: 50

See Also

COMMIT_DELAY

COMMIT_DELAY_SCALE

COMMIT_DELAY_USEC

COMMIT_DELAY_MINIMUM

COMMIT_DELAY_MINIMUM <time in microseconds>

Do not use this unless instructed to by FairCom.

In V11.0 and later, allows the minimum time allowable for commit delay to be overridden. Time specified is in microseconds. Example:

COMMIT_DELAY_MINIMUM 500

Default: 1000 microseconds or 0 depending on environment.

COMMIT_DELAY_SCALE

COMMIT_DELAY_SCALE  <ratio of block to clear time>

For advanced control of the intricate commit delay timing statistics, additional controls are available for the commit delay time calculation. The ratio of block to clear time cannot be smaller than 1. As this value increases, the amount of time waiting to permit commit delay cohorts to flow past their mutual block is decreased.

It is recommended that these values be carefully profiled as they can impact performance in many unexpected ways.

Default: 2

See Also

COMMIT_DELAY

COMMIT_DELAY_BASE

COMMIT_DELAY_USEC

COMMIT_DELAY_USEC

COMMIT_DELAY_USEC <microseconds> | -1>

Same as COMMIT_DELAY, but interpreted as microseconds. If both forms of this keyword are specified, then the last entry in the configuration file prevails.

Note Not all systems support arbitrarily short sleep times. FairCom has found, for example on the Solaris operating system, unless using real-time capabilities of the operating system, the minimum achievable sleep time is 10 milliseconds, even if a short sleep time is requested.

See Also

COMMIT_DELAY

COMMIT_DELAY_BASE

COMMIT_DELAY_SCALE

COMMIT_LOCK_DEFER_MS

COMMIT_LOCK_DEFER_MS   <defer time in milliseconds>

Provides an additional tuning mechanism for the COMMIT_READ_LOCK retry value.

The length of the defer value can be varied from zero to 100 milliseconds.

Internal tests demonstrated the effect of this change on CPU utilization was dramatic as a reader attempted to retry its read commit lock. Of course, actual performance increases will be variable, depending on any particular server environment. The trade-off with this method is introducing an unnecessary defer (i.e. if the next retry without a non-zero defer would have succeeded). In practice, this was not found to impede performance.

Commit write locks held by the transaction (i.e., locks that block read attempts during the actual commit process) are held during the entire commit. This has no direct impact upon the transaction commit, however, can cause longer delays for a read attempt when the transaction itself is comprised of a large number of write operations (e.g., committing thousands of ADDREC()s)

Default: 10

See Also

COMPATIBILITY NO_COMMIT_READ_LOCK

COMPATIBILITY LOG_WRITETHRU

COMPATIBILITY LOG_WRITETHRU

Instructs the FairCom Server to open its transaction logs in synchronous write mode. In this mode, writes to the transaction logs go directly to disk (or disk cache), avoiding the file system cache, so the server is able to avoid the overhead of first writing to the file system cache and then flushing the file system. As of FairCom DB Version 9, this is applicable to both Windows and Unix Systems.

Note On the Solaris operating systems, COMPATIBILITY LOG_WRITETHRU uses the O_DSYNC mode to implement synchronous log writes when available. (Direct I/O with O_SYNC is still used on those systems not supporting O_DSYNC.)

Default: OFF

See also

• COMPATIBILITY DIRECT_IO
• DELAYED_DURABILITY

COMPATIBILITY TDATA_WRITETHRU

Similar to the strategy used in transaction log flushing, the FairCom Server can avoid excessive flushing of data and index files under transaction control. Two additional keywords affect this behavior:

COMPATIBILITY TDATA_WRITETHRU and COMPATIBILITY TINDEX_WRITETHRU force transaction controlled data files and index files, respectively, to be written directly to disk (whenever c-tree determines that they must be flushed from the c-tree buffers), and the calls to flush their OS buffers are skipped. These keywords cause transaction controlled files to be written through the OS file system cache, rather than written into the file system cache and later explicitly flushed at a database checkpoint. This behavior allows I/O costs to be evenly amortized, reducing the amount of I/O that must be done at a database checkpoint. This results in a smaller variance in transaction times, and potentially greater total transaction throughput. For scenarios without heavy and continuous write activity, this alternate behavior frequently results in reduced throughput.

TDATA_WRITETHRU uses the file system cache. The file is placed into a mode that causes the write to go to file system cache and then to disk before returning; the data still resides in file system cache. Compare to UNBUFFERED_IO, which completely avoids the file system cache.

See Also

COMPATIBILITY TINDEX_WRITETHRU

COMPATIBILITY TINDEX_WRITETHRU

Similar to the strategy used in transaction log flushing, the FairCom Server can avoid excessive flushing of data and index files under transaction control. Two additional keywords affect this behavior:

COMPATIBILITY TDATA_WRITETHRU and COMPATIBILITY TINDEX_WRITETHRU force transaction controlled data files and index files, respectively, to be written directly to disk (whenever c-tree determines that they must be flushed from the c-tree buffers), and the calls to flush their OS buffers are skipped. These keywords cause transaction controlled files to be written through the OS file system cache, rather than written into the file system cache and later explicitly flushed at a database checkpoint. This behavior allows I/O costs to be evenly amortized, reducing the amount of I/O that must be done at a database checkpoint. This results in a smaller variance in transaction times, and potentially greater total transaction throughput. For scenarios without heavy and continuous write activity, this alternate behavior frequently results in reduced throughput.

See Also

COMPATIBILITY TDATA_WRITETHRU

COMPATIBILITY LOCK_EXCL_TRAN

Skipping locks on exclusively opened TRNLOG files is enabled by default. It can be disabled by specifying the option COMPATIBILITY LOCK_EXCL_TRAN in ctsrvr.cfg.

DELAYED_DURABILITY

DELAYED_DURABILITY <N>

DELAYED_DURABILITY <N> (default 0) controls whether or not to use a modified log syncing strategy.

With delayed durability enabled transaction logs are no longer sync'd to persisted storage on each commit (or other internal log buffer flush events) and instead, transaction log data is allowed to be written to the filesystem cache, and a background thread then periodically and consistently syncs transaction log contents to disk.

By allowing committed transaction entries to be written to filesystem cache and deferring the file flush can result in a very large performance gain in many cases. However, there is a trade off as a window of potential data loss vulnerability is then introduced. The period of time that transaction log contents are present in volatile filesystem cache before the flush could mean transactions already reported to the application as committed, in rare cases, might not make it to persisted storage.

With many modern storage devices there is a limited presumption that available capacitance on the system and storage device hardware that data is usually persisted even in a power outage situation, though this is not guaranteed. Thus alternate recovery strategies should be considered.

One strategy to coordinate the known state of committed database transactions with a known application state can be achieved with restore points. Restore points can be triggered by an application to create a known point in time where the application and the database are in sync. A restore point creates a special database transaction log checkpoint that can be later referenced by the application as a known good start point.

With delayed durability enabled, it is recommended to consider the use of restore points for a robust recoverable solution.

• When DELAYED_DURABILITY set to 0 disables delayed durability/
• When DELAYED_DURABILITY is set to a positive value, <N>, the new strategy is in use and the log sync is guaranteed to occur within <N> seconds. A setting of 1 second is recommended because it results in a good performance gain (higher values offer very little additional benefit). The following configuration options are set as shown below:
   

Note If the configuration file has one or more of these configuration entries set inconsistently after the DELAYED_DURABILITY entry, the server logs a message to CTSTATUS.FCS and continues to start, disabling any incompatible options after processing the configuration file.

Warning

When DELAYED_DURABILITY is enabled, recently committed transactions could be lost if FairCom Server terminates abnormally. For automatic recovery to succeed after FairCom Server terminates abnormally, either of the following should be considered.

1. The application must write a restore point to the log (using the ctflush utility or calling ctQUIET() with mode of ctQTlog_restorepoint) such that a restore point exists prior to the time the server terminated abnormally. In this case, automatic recovery recovers to that restore point.
   or
2. ctsrvr.cfg must contain the option RECOVER_TO_RESTORE_POINT NO, indicating that no restore point is needed. In this case, automatic recovery recovers to the last data that was written to the log on disk. This is the default configuration.

DELSTK_COMMIT_SEC

DELSTK_COMMIT_SEC

The DELSTK_COMMIT_SEC server configuration can be used to improve performance of committing record deletes in a fixed-length data file that uses the TDATA_WRITETHRU option. To use this option, specify the following in ctsrvr.cfg:

DELSTK_COMMIT_SEC nsec

When nsec is greater than zero, this option causes commits of fixed-length record deletes in files that use the TDATA_WRITETHRU option to write the delete stack value to the file's header at most every nsec seconds. This means that, in the event of a server crash, the delete stack value in the header can be out-of-date, not accounting for the last nsec seconds of deleted records. The only impact is that some space in the file will not be available for reuse after automatic recovery.

Default: 0 (disabled)

The maximum value that can be specified is 30.

Changing at Runtime

This option can be changed at runtime using either of these approaches:

Using the ctadmn utility:

Select menu option 10. Change Server Settings, then select 10. Change the specified configuration option, and then enter the configuration option and its value:

delstk_commit_sec 1

FIXED_LOG_SIZE

FIXED_LOG_SIZE

*** THIS KEYWORD IS NO LONGER SUPPORTED ***

FORCE_LOGIDX

FORCE_LOGIDX <ON | OFF | NO>

FORCE_LOGIDX allows LOGIDX support to be forced on, off, or disabled:

• ON forces all indexes to use LOGIDX entries.
• OFF forces all indexes not to use LOGIDX entries.
• NO uses existing file modes to control LOGIDX entries.

The LOGIDX file mode is an index file mode permitting faster index automatic recovery during FairCom Server startup. Transaction controlled indexes with this file mode are recovered more quickly than with the standard transaction processing file mode TRNLOG. This feature can significantly reduce recovery times for large indexes and has not noticeably degraded the speed of index operations. LOGIDX is only applicable if the file mode also includes TRNLOG.

Note The LOGIDX file mode is intended for index files only, and is ignored in data files. When adding the LOGIDX file mode to an existing index that is not under transaction control, be sure to rebuild the index to enable transaction control.

Default: ON

See Also

• DELAYED_DURABILITY

KEEP_LOGS

KEEP_LOGS <number of inactive logs>

If greater than zero, KEEP_LOGS specifies the number of non-active transaction log files kept on disk in addition to the active log files. When a greater-than-zero KEEP_LOGS value is exceeded, the FairCom Server automatically deletes the oldest inactive log file as new log files are needed. If KEEP_LOGS is zero, inactive log files are immediately deleted by the FairCom Server. If KEEP_LOGS is -1, no inactive log files are deleted by the FairCom Server.

KEEP_LOGS permits the archiving of transaction logs. Inactive log files may be safely moved, deleted, copied or renamed. An inactive log file which is not immediately deleted by the FairCom Server is renamed from the form L*.FCS to the form L*.FCA. The last character in the extension is changed from ‘S’ to ‘A’, with the rest staying the same.

Default: 0

KEEP_RESTORE_POINTS

KEEP_RESTORE_POINTS <N>

KEEP_RESTORE_POINTS <N> allows the server to maintain information about the last N Restore Points. This is somewhat like the KEEP_LOGS keyword. The last N Restore Points are referred to as the "Active Restore Points." It is possible to set N to zero which means there will be no Active Restore Points. If there are no Active Restore Points, then automatic recovery cannot rollback to a quiet transaction state. The list of Active Restore Points is stored in each checkpoint. In the case of a Checkpoint Restore Point, the checkpoint includes itself as the last Active Restore Point.

Note When N is greater than zero, the server automatically maintains the transactions logs necessary to ensure that a rollback to any of the Active Restore Points is possible. However, KEEP_RESTORE_POINTS does not affect the existence of the Restore Point files. These files are quite small (128 bytes), and are not deleted by the server.

See Also

• RECOVER_TO_RESTORE_POINT

LEAF_NODE_READ_LOCK

LEAF_NODE_READ_LOCK  YES | NO

Default: YES

When enabled, FairCom Server acquires a read lock on a leaf node if the index does not use key compression. If it finds that the node contains transaction marks, it releases the read lock and acquires a write lock on the node. This greatly improves scalability of leaf nodes reads.

This option is dynamically configurable at runtime using the ctadmn utility's option (menu option 10, and then menu option 10, Change the specified configuration option, again) to change a server configuration option value.

LOG_COMPRESSION_FACTOR

LOG_COMPRESSION_FACTOR  <percent>

Default: 80

See Also

• LOG_COMPRESSION_THRESHOLD

Note Log compression is not currently supported.

LOG_COMPRESSION_THRESHOLD

LOG_COMPRESSION_THRESHOLD  <bytes>

There are two parameters that control the manner in which the compression is applied to log entries.

• The first is a size threshold:
  If the variable region is less than this threshold, no compression is attempted.
• The second is a compression factor expressed as a percent:
  If the compression does not fit in a buffer of size (<factor> * input_size / 100), then no compression takes place.

Snapshot statistics include compression results.

Default: 100

See Also

• LOG_COMPRESSION_FACTOR

Note Log compression is not currently supported.

LOG_EVEN

LOG_EVEN <full_path>L

The alternative name for even numbered transaction log files. This name must be in the form of an optional directory path and the single character ‘L’ (e.g., D:\LOG0\L). The FairCom Server appends a seven-digit even number and the extension .FCS to the name given here.

If a relative path is specified for START_EVEN / START_ODD or LOG_EVEN / LOG_ODD, it is relative to the defined LOCAL_DIRECTORY path, not the startup directory of the server.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Note The ability to give separate device and directory names for odd and even log files allows them to be directed to different physical storage devices.

Default: L

See Also

LOG_ODD

LOG_ODD

LOG_ODD <full_path>L

The alternative name for odd numbered transaction log files. This name must be in the form of an optional directory path and the single character ‘L’ (e.g., D:\LOG1\L). The FairCom Server appends a seven-digit odd number and the extension .FCS to the name provided.

If a relative path is specified for START_EVEN / START_ODD or LOG_EVEN / LOG_ODD, it is relative to the defined LOCAL_DIRECTORY path, not the startup directory of the server.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Default: L

See Also

LOG_EVEN

LOG_PAGE_SIZE

LOG_PAGE_SIZE <bytes>

The FairCom Server uses a transaction log buffer to manage log write requests and this is comprised of a number of page size blocks. The LOG_PAGE_SIZE configuration key word is used to change the page size, and ideally, the log page size should match the optimal size for the disk I/O subsystem. The maximum setting is 32K.

Default

The default is 8K.

See Also

• PAGE_SIZE

LOG_SPACE

LOG_SPACE <Megabytes>

This is the number of megabytes of disk space allocated to storing active transaction logs, starting with a minimum of 2. The FairCom Server maintains up to 4 active log files, which consume, in the aggregate, up to LOG_SPACE megabytes of disk space. Log files are numbered consecutively starting with 1. The log file names are in the form L0000001.FCS.

For a server with existing transaction logs, If LOG_SPACE is changed and LOG_TEMPLATE is non-zero, the existing log templates will be the wrong size and should be removed. The log template (L0000000.FCT) is only created when the Log # 1 is created, so the transaction log reset procedure should be followed.

V12 Notes

The maximum allowed value for the LOG_SPACE keyword has been increased from 1GB to 4GB-1. This controls the initial size of transaction logs (of 4 logs specifically), so each log can now grow to just under 1GB. Each individual log can now grow up to 4GB if needed, although 3GB is expected to be the largest size, which will be a 1GB normal log size, plus a potential 2GB variable-length record in a transaction. Reducing the number of logs results in less log file churning with high velocity applications leading to faster consistent transaction throughput.

A change in logic allows us to avoid performing a long series of synchronous writes to the transaction log when we start the server in an empty transaction log directory.

This change significantly speeds up server startup on Linux when the file system has write barriers enabled.

Note When write barriers are disabled on Linux, synchronous writes are much faster than with write barriers enabled, so FairCom highly recommends running with write barriers off and a battery backed power supply on the machine in production systems for best performance.

With this performance improvement, we have been able to increase LOG_SPACE to 1 GB and we have COMPATIBILITY LOG_WRITETHRU on by default.

The defaults in the Server Configuration File (ctsrvr.cfg) have been modified to optimize performance on modern systems.

• LOG_SPACE has been increased from 120 MB to 1 GB

LOG_SPACE 1 GB

• PAGE_SIZE has been increase from 8192 to 32768

PAGE_SIZE 32768 

Warning Changing the PAGE_SIZE is a maintenance task that should be done carefully and with a full reliable backup. Practice on a copy of your data and server folder until you are confident with the results. For procedures, see Adjusting PAGE_SIZE in the FairCom Installation Guide.

Note A file created with a larger PAGE_SIZE cannot be opened by a server with a smaller PAGE_SIZE.

Default: 1 GB (prior to V12: 120 MB)

LOG_TEMPLATE

LOG_TEMPLATE <n>

Enables transaction log templates. <n> is the number of log templates for the server to maintain. A value of 0 means no use of log templates. A value of two (2) means that two blank logs (L0000002.FCT and L0000003.FCT) would be created at first server startup in addition to the template (L0000000.FCT). Log templates have been on by default since V9.

Before enabling log templates on a system that did not have them turned on, any existing transaction logs must be deleted so the server can create the log templates. To do this, shut down the server cleanly and delete Lnnnnnnn.FCS, S0000000.FCS, and S0000001.FCS. When the server is restarted after adding this keyword, initial startup may take longer due to creation of template log files (*.FCT), however, using the templates will result in better performance in high transaction volume environments.

Default: 2

See Also

• LOG_TEMPLATE_COPY_SLEEP_TIME
• LOG_TEMPLATE_COPY_SLEEP_PCT

LOG_TEMPLATE_COPY_SLEEP_PCT

LOG_TEMPLATE_COPY_SLEEP_PCT <percent>

When working with large log templates on high volume systems, the log template copy operation can consume excessive I/O time impacting performance. By periodically deferring the copy operation, this can smooth out I/O spikes. This option, when used with the LOG_TEMPLATE_COPY_SLEEP_TIME option specifies the percentage of data that is written to the target transaction log file after which the copy operation sleeps for the number of milliseconds specified for the LOG_TEMPLATE_COPY_SLEEP_TIME option.

Default: 15
Minimum value: 1
Maximum value: 99

See Also

• LOG_TEMPLATE
• LOG_TEMPLATE_COPY_SLEEP_TIME

LOG_TEMPLATE_COPY_SLEEP_TIME

LOG_TEMPLATE_COPY_SLEEP_TIME <milliseconds>

When working with large log templates on high volume systems, the log template copy operation can consume excessive I/O time impacting performance. By periodically deferring the copy operation, this can smooth out I/O spikes. This option causes the copying of the log template to pause for the specified number of milliseconds each time it has written the percentage of data specified by the LOG_TEMPLATE_COPY_SLEEP_PCT option to the target transaction log file.

If an error occurs using this method to copy the log template, the code logs an error message to CTSTATUS.FCS (look for "LOG_TEMPLATE_COPY: ...") and attempts to use the original log template copy method.

A suggested time is 5 ms to start with.

Default: 0 (disabled)
Minimum value: 0
Maximum value: 1000 (1 second sleep)

See Also

• LOG_TEMPLATE
• LOG_TEMPLATE_COPY_SLEEP_PCT

LONG_TRANSACTION_MS

LONG_TRANSACTION_MS  <milliseconds>

A long transaction is any transaction that exceeds the elapsed transaction time specified. This will cause a message to be written to the SYSMON queue if the PERF_MONITOR configuration option is enabled.

See Also

• PERF_MONITOR

MAX_DFRIDX_LOGS

MAX_DFRIDX_LOGS <max_logs>

Changes the limit FairCom Server sets for the number of active transaction logs that are kept for deferred index and Replication Agent processing.

In V12 and later, the default is 100; prior to V12, the default was 50.

Specifying a value of zero for <max_logs> removes the limit.

Tip - If you find error 96 on startup due to logs not found, it is likely be due to MAX_DFRIDX_LOGS or MAX_REPL_LOGS settings removing logs after the max is reached. Be sure to review your operational environment for appropriate settings.

See also:

• MAX_REPL_LOGS
• Limit number of transactions logs kept for deferred index & Replication Agent

Transaction log limit for replication and deferred indexing

Note This is a Compatibility Change for FairCom DB V11.5 and later.

The Replication Agent and deferred index processing thread for TRNLOG files read transaction logs and inform the server of their minimum transaction log requirements respectively. In early V11 releases, FairCom DB retained all required logs indicated by these clients. In some cases, this resulted in the number of transaction logs to increase without limit, filling all drive space. A typical scenario is a Replication Agent taken offline without removing its minimum transaction log requirement from the server.

FairCom DB Server now limits by default the number of active transaction logs that are kept for Replication Agent and deferred index processing to 50. This default configuration is a deliberate trade off to avoid accumulating an unlimited number of active transaction logs and potentially running out of critical drive space.

The worst case scenario with this change is your Replication Agent or internal thread that is reading transaction logs can fail with error 96 when reconnecting and searching for a log that it expects present is no longer there. In this case, it will likely be necessary to resync your files through the Replication ReSync feature, a backup and restore, or manual file copy.

Two configuration options were introduced controlling these limits independently for these two features:

• MAX_REPL_LOGS <max_logs> - Sets the maximum number of logs to be held specifically for replication.
• MAX_DFRIDX_LOGS <max_logs> - Sets the maximum number of logs to be held specifically for the deferred indexing thread.

Use of either of these configuration settings does not impact your FairCom DB Servers’ ability to retain any necessary logs required for Automatic Recovery.

The more comprehensive KEEP_LOGS configuration keyword always overrides both MAX_DFRIDX_LOGS and MAX_REPL_LOGS configuration settings in either case.

When a new transaction log is created and one of these limits is in effect and the required number of logs exceeds the limit, FairCom DB logs one of the following messages to CTSTATUS.FCS and sets the minimum log requirement of the deferred index thread or Replication Agent to a larger value equal to the log limit:

- User# 00039 Deferred index log requirement (current=42, required=32) exceeds MAX_DFRIDX_LOGS limit. Setting lowlog to 33.

- User# 00038 Replication reader AGENT1 log requirement (current=43, required=32) exceeds MAX_REPL_LOGS limit. Setting lowlog to 33.

These keywords can be set at runtime by using the command-line tool ctadmn, option 10 (Change the specified configuration option) and setting the new value, like this:

10. Change the specified configuration option

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

Enter the configuration option and its value >> MAX_REPL_LOGS 75

Successfully changed the configuration option.

They can be set programmatically by calling the ctSETCFG() function. Examples:

/* Set maximum logs for deferred index thread to 100. */

ctSETCFG(setcfgCONFIG_OPTION, "MAX_DFRIDX_LOGS", "100");

/* Set maximum logs for replication agents to 0 (no limit). */

ctSETCFG(setcfgCONFIG_OPTION, "MAX_REPL_LOGS", "0");

MAX_PREIMAGE_DATA

MAX_PREIMAGE_DATA <limit> sets the maximum size of in‑memory data that is allocated by a transaction to <limit>. After that amount of data has been allocated, subsequent allocations are stored in a preimage swap file on disk. The default value is 1 GB.

See Also

MAX_PREIMAGE_SWAP

Millions of Records per Transaction

MAX_PREIMAGE_SWAP

MAX_PREIMAGE_SWAP <limit> sets the maximum size of the preimage swap file on disk. If the file reaches its maximum size and a transaction attempts to allocate more space in the file, the operation fails with error TSHD_ERR (72). The default value is zero (meaning no limit).

See Also

MAX_PREIMAGE_DATA

Millions of Records per Transaction

MAX_REPL_LOGS

MAX_REPL_LOGS <max_logs>

Changes the limit FairCom Server sets for the number of active transaction logs that are kept for deferred index and Replication Agent processing.

In V12 and later, the default is 100; prior to V12, the default was 50.

Specifying a value of zero for <max_logs> removes the limit.

Tip - If you find error 96 on startup due to logs not found, it is likely be due to MAX_DFRIDX_LOGS or MAX_REPL_LOGS settings removing logs after the max is reached. Be sure to review your operational environment for appropriate settings.

See also:

• MAX_DFRIDX_LOGS
• Limit number of transactions logs kept for deferred index & Replication Agent

MAX_TRANSACTION_JUMP

MAX_TRANSACTION_JUMP <maximum transaction increase value>

MAX_TRANSACTION_JUMP limits the maximum increase in the server's transaction number when opening a transaction-controlled file. This can prevent a shutdown due to transaction number overflow.

MAX_TRANSACTION_JUMP specifies a maximum transaction increase value. When opening a transaction-controlled file, if the file's transaction high water mark in the file header exceeds the server's current transaction number by more than the specified value, the server fails the file open with error 533 (MTRN_ERR). In this situation, use the ctclntrn utility to clean the transaction marks in the file, allowing the server to open it.

A value of 0 disables the setting.

If you don't know what to set it to, we recommend starting with a value of 1,000,000,000.

Default: 0 (disables the setting)

See also:

Transaction High-Water Marks

MAX_USER_LOG_ENTRY_BYTES

MAX_USER_LOGS   <# of logs>

An optional limit for how many active transaction logs a transaction spans before it is aborted or abandoned. The default, ZERO, disables the check for long transactions.

When specified, MAX_USER_LOGS takes as its argument the maximum number of logs a transaction may span. If a transaction exceeds the limit, an attempt is made to abort the transaction. If the transaction cannot be aborted (consider the case where an abort would cause the server to fail), the transaction is abandoned. This means the client thread will lose its connection to the server, and the application may receive errors ARQS_ERR (127) or ARSP_ERR (128). There is no guarantee that a transaction will not span more logs than the specified maximum, however, the transaction will end within a reasonable number of logs.

If the transaction is aborted, then the next call by the client will return error MLAB_ERR (821) to indicate the operation was not completed and the pending transaction has been aborted. (See the end note for a special case of this error condition.) A message of the following form will be made in CTSTATUS.FCS:

Sun Dec 03 08:53:21 2006
 - User# 00011  Transaction aborted at ct_mul_abandon1 for user# 9: 821

If the transaction is abandoned (that is, no explicit abort written in the log), then the client will be disconnected from the server. CTSTATUS.FCS entries such as the following reflect logs growing from a transaction that is pending, then the detection of the long transaction, then the eventual abandonment:

Sun Dec 03 09:53:42 2006
 - User# 00012  The number of active log files increased to: 5
Sun Dec 03 09:53:42 2006
 - User# 00012  Transaction (started in log 1) still pending.
                User# 11 |GUEST||
Sun Dec 03 09:53:55 2006
 - User# 00012  The number of active log files increased to: 6
Sun Dec 03 09:53:55 2006
 - User# 00012  Abandoned Transaction
Sun Dec 03 09:54:10 2006
 - User# 00012  The number of active log files increased to: 7
Sun Dec 03 09:54:10 2006
 - User# 00012  Abandoned Transaction2
Sun Dec 03 09:54:10 2006
 - User# 00012  Abandoned transaction kill request posted against user #11
        |GUEST||
Sun Dec 03 09:54:10 2006
 - User# 00011  ctntio: send error - O11 bytes=0 pErr=127
        |GUEST||: 168
Sun Dec 03 09:54:25 2006
 - User# 00012  The number of active log files decreased to: 4

The number of logs continued to grow, and then shrink, as reflected in the above excerpt because in addition to a transaction sleeping on a blocked lock, another unrelated application was continuing to add records to its files and corresponding entries in the transaction logs.

Note In some rare situations error TRAB_COD (-823) can be returned instead of MLAB_ERR. This indicates the requested operation was completed before the abort actually took place. Usually, this is the same condition as an MLAB_ERR, as the transaction is aborted. In practice, the TRAB_COD should be rare.

Default: 0

MAX_USER_LOGS

MAX_USER_LOGS <max number of logs>

MAX_USER_LOGS controls how many logs a transaction can span before attempts are made to abort or abandon the transaction. The default, ZERO, disables the check for long transactions.

If a transaction cannot be aborted (for example, a server fault would occur) the transaction is abandoned which means that the client thread loses its connection to the server. There is no guarantee that the transaction will not span more logs than the specified maximum, but the transaction will end within a reasonable number of logs.

If the transaction is aborted, then the next call by the client will return a MLAB_ERR (821) to indicate the operation was not completed and the pending transaction has been aborted. A message of the following form will be made in CTSTATUS.FCS:

Sun Dec 03 08:53:21 2006
- User# 00011  Transaction aborted at ct_mul_abandon1 for user# 9: 821

If the transaction is abandoned (which means no explicit abort written in the log), then the client will be disconnected from the server. CTSTATUS.FCS entries such as those shown below reflect logs growing from a transaction that is pending, then the detection of the long transaction, then the eventual abandonment:

Sun Dec 03 09:53:42 2006
- User# 00012  The number of active log files increased to: 5
Sun Dec 03 09:53:42 2006
- User# 00012  Transaction (started in log 1) still pending.
               User# 11 |GUEST||
Sun Dec 03 09:53:55 2006
- User# 00012  The number of active log files increased to: 6
Sun Dec 03 09:53:55 2006
- User# 00012  Abandoned Transaction
Sun Dec 03 09:54:10 2006
- User# 00012  The number of active log files increased to: 7
Sun Dec 03 09:54:10 2006
- User# 00012  Abandoned Transaction2
Sun Dec 03 09:54:10 2006
- User# 00012  Abandoned transaction kill request posted against user #11
       |GUEST||
Sun Dec 03 09:54:10 2006
- User# 00011  ctntio: send error - O11 bytes=0 pErr=127
       |GUEST||: 168
Sun Dec 03 09:54:25 2006
- User# 00012  The number of active log files decreased to: 4

The number of logs continued to grow, and then shrink, as reflected in the above excerpt because in addition to a transaction sleeping on a blocked lock, another unrelated application was continuing to add records to its files and corresponding entries in the transaction logs.

PREIMAGE_FILE

PREIMAGE_FILE <Full_path>D

The alternative name for the file containing preimages swapped to disk. The format for this name is an optional directory path, which may include a Drive ID, followed by the single character ‘D’ (e.g., E:\SWAP\D). The FairCom Server appends a seven-digit number and the extension .FCS to the name provided here.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Default: D

START_EVEN

START_EVEN <full_path>S

The alternative name for even numbered start file. The start file contains the location at which the automatic recovery routines begin to scan the transaction logs. There are two start files (numbered zero and one) to reduce the risk of losing the starting point for automatic recovery. This name must be in the form of a directory path and the single character ‘S’ (e.g., C:\START\S). The FairCom Server appends a seven-digit even number and the extension .FCS to the name provided.

If a relative path is specified for START_EVEN / START_ODD or LOG_EVEN / LOG_ODD, it is relative to the defined LOCAL_DIRECTORY path, not the startup directory of the server.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Default: S

See Also

START_EVEN_MIRROR

START_ODD

START_ODD_MIRROR

START_ODD

START_ODD <full_path>S

The alternative name for odd numbered start file. The start file contains the location at which the automatic recovery routines begin to scan the transaction logs. There are two start files (numbered zero and one) to reduce the risk of losing the starting point for automatic recovery. This name must be in the form of a directory path and the single character ‘S’ (e.g., C:\START\S). The FairCom Server appends a seven-digit odd number and the extension .FCS to the name provided.

If a relative path is specified for START_EVEN / START_ODD or LOG_EVEN / LOG_ODD, it is relative to the defined LOCAL_DIRECTORY path, not the startup directory of the server.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Default: S

See Also

START_EVEN

START_EVEN_MIRROR

START_ODD_MIRROR

SUPPRESS_LOG_FLUSH

SUPPRESS_LOG_FLUSH <YES | NO>

Causes transaction begin and commit operations to skip the flushing of the log file when its argument is YES. The default is NO. Suppressing the log flush makes it impossible to perform a proper automatic recovery. However, a dynamic dump will capture the necessary log information to restore TRNLOG files to a clean, consistent state. Using this keyword without the PREIMAGE_DUMP keyword is not recommended

By turning on PREIMAGE_DUMP and using PREIMG files, your system can run much faster than with full transaction processing, and still perform on-line dynamic dumps which will permit restoring files to the time of the dump in a clean, consistent state. However, it will NOT be possible to roll forward from the restored files because transaction log entries are not maintained outside of the dump process. See also PREIMAGE_DUMP and Advanced - Faster Auto-Recovery.

Note We do not recommend disabling this keyword, as your data integrity will suffer. Be sure you understand what you are doing if you plan to change the default setting of this keyword.

Default: NO

See Also

• SUPPRESS_LOG_SYNC
• DELAYED_DURABILITY

SUPPRESS_LOG_SYNC

SUPPRESS_LOG_SYNC

Skips the sync'ing to disk from a log flush operation. This only applies to transaction begin/end operations. There are other system operations that cause log flushes, however, these are not affected. These other log flushes should also be relatively low in number.

Note We do not recommend disabling this keyword, as your data integrity will suffer. Be sure you understand what you are doing if you plan to change the default setting of this keyword.

See Also

• SUPPRESS_LOG_FLUSH
• DELAYED_DURABILITY

TRAN_HIGH_MARK

TRAN_HIGH_MARK <long integer>

Specifies a transaction number threshold value. If a file is opened with a high-water mark value greater than this threshold, a message is placed in CTSTATUS.FCS listing the file name.

For example, the following configuration entry would cause any file whose high-water mark exceeds one million to have its name listed in CTSTATUS.FCS.

TRAN_HIGH_MARK  1000000

TRAN_OVERFLOW_THRESHOLD

TRAN_OVERFLOW_THRESHOLD <transaction_number>

This keyword causes the c-tree Server to log the following warning message to CTSTATUS.FCS and to standard output (or the message monitor window on Windows systems) when the current transaction number exceeds the specified transaction number:

WARNING The current transaction number (####) exceeds the user-defined threshold.

The message is logged every 10000 transactions once this limit has been reached. The TRAN_OVERFLOW_THRESHOLD limit can be set to any value up to 0x3ffffffffffff, which is the highest 6‑byte transaction number that FairCom DB supports.

When FairCom DB supports 6‑byte transaction numbers it does not display transaction overflow warnings until the current transaction number approaches the 6‑byte transaction number limit. But if 4‑byte transaction number files are in use, a key insert or delete will fail if the current transaction number exceeds the 4‑byte transaction number limit (however, FairCom DB will continue operating). This keyword allows the server administrator to determine when the server will issue a warning that its transaction number is approaching the limit.

See Also

• Extended Transaction Number Support

TRAN_TIMEOUT

TRAN_TIMEOUT <interval>

There are occasions where it is valuable to limit the time that a FairCom Server transaction is allowed to span. Long held transactions can cause a number of application-related issues. For example, holding locks on a record, or preventing updates to be available to other users in a timely manner.

TRAN_TIMEOUT sets a time limit on a transaction: when a transaction is started, once the time period passes, if the transaction is still active it is aborted regardless of what the user is doing (the user could be idle for example).

• <interval> is specified in seconds.
• The minimum value for the timeout <interval> is 10 seconds. Any value between 1 and 10 is the same as 10.
• If the <interval> is set to 0 (or a negative number), this feature is turned off.

TRAN_TIMEOUT is also useful to avoid increases in the number of active transaction logs which can occur due to a user starting a transaction and then remaining idle without committing the transaction, while other transaction activity occurs. TRAN_TIMEOUT aborting the transaction releases locks acquired within the transaction.

Deferred Transaction Begins

A deferred begin transaction (a transaction started using ctDEFERBEG), only starts counting the transaction time when the transaction is converted to an actual transaction (typically on the first update made in that transaction). For example, if you start isql and do some SELECTS then look at the transaction time shown for the SQL connection by ctadmn, it will show '--' indicating the transaction is not yet an actual transaction (this is because SQL threads use ctDEFERBEG transactions). Once you perform an update, ctadmn will show the transaction time counting, and if TRAN_TIMEOUT is in effect, the transaction will be aborted if it does not commit before the TRAN_TIMEOUT limit.

Transaction Timeout Statistics

The USERINFO() function returns state information for a particular connection to the FairCom Server. Included in the state information is the elapsed transaction time for that connection. When a transaction is started with the ctDEFERBEG mode, the elapsed transaction time value returned by USERINFO() is based on the time at which the TRANBEG() call was made.

For a transaction whose begin has been deferred, USERINFO() returns an elapsed transaction time of zero until the transaction begin is converted to an actual transaction begin, at which point the elapsed transaction time is calculated from that time.

Default: No timeout

TRANSACTION_FLUSH

TRANSACTION_FLUSH <# of updates>

This keyword provides control for the maximum number of updates to a buffer (data or index) before it is flushed. The buffer may well be flushed prior to this number of updates because of the LRU (Least Recently Used) scheme (used for index caches but not data caches) or because of the checkpoint limit. This system parameter affects only buffers holding images for transaction controlled files. Reducing this value reduces the amount of buffering, slowing system performance; but decreases the amount of work to be performed during recovery. A value of zero causes the buffer to be flushed upon update.

Default: 500000

UNBUFFERED_LOG_IO

UNBUFFERED_LOG_IO <YES | NO>

Enable separate unbuffered I/O for transaction logs.

OS Support

This option is supported on the Windows operating system.

In V11 and later, support for direct I/O has been enabled on Linux systems. A value of 512-bytes is used for size and alignment for direct I/O.

This feature supports both c-tree data and index files, as well as transaction logs. Configuration options are provided for both.

• UNBUFFERED_IO filename (enables direct I/O for the specified file; the filename can include wildcards, such as *.dat)
• UNBUFFERED_LOG_IO YES (enables direct I/O for the transaction logs).

Note This feature requires Linux kernel version 2.6 or later, FairCom Server logs an error message to CTSTATUS.FCS if these options are used on pre-2.6 Linux kernel systems. The error messages are:

The UNBUFFERED_IO option requires Linux kernel version 2.6 or later

The UNBUFFERED_LOG_IO option requires Linux kernel version 2.6 or later 

See Also

• UNBUFFERED_IO