Locking

AUTO_CHECKLOCK

CHECKLOCK_FILE <YES/NO>

Available in version 13.0.3 onwards:

If YES (default), ctCHECKLOCK is enabled on all files.

If NO, ctCHECKLOCK is not enabled (which is the behavior before 13.0.3).

You can enable or disable this feature for individual files using CHECKLOCK_FILE.

Breaking Change: As of version 13.0.3, the server prevents a record from being updated if it is not locked. This has always been the intended behavior, but previous versions did not enforce it. Use AUTO_CHECKLOCK NO to revert to the previous behavior.

AUTO_LOCK_RETRY

AUTO_LOCK_RETRY <retries>

Enables automatic retries of data record locks when a c-tree function call fails with a data record lock error DLOK_ERR.

Default: 0 (retries).

AUTO_LOCK_RETRY_SLEEP

AUTO_LOCK_RETRY_SLEEP <milliseconds>

Set the sleep time between retries.

Default: 100 ms

BLOCKING_LOCK_TIMEOUT_SEC

BLOCKING_LOCK_TIMEOUT_SEC <timeoutSEC>

BLOCKING_LOCK_TIMEOUT_SEC avoids excessively long blocking lock waits. When used, this feature returns error UTIM_OUT (827) to the caller of the lock request. The function ctLOKTIMOUT() is used to set, change and clear this timeout feature.

• timeoutSEC is specified in seconds, and determines the amount of time to wait before returning the UTIM_OUT error.

This configuration entry is equivalent to a member of the ADMIN group making the call ctLOKTIMOUT(-1, ctLTOallusers | ctLTOdiagnostic, timeoutSEC).

Note The effect of the configuration entry can be turned off by a call of the form ctLOKTIMOUT(-1, ctLTOallusers, 0).

If a user calls ctLOKTIMOUT() with a datno equal to -1 in order to set a timeout value on all data files for the user, the user can selectively change or turn off the timeout by making additional calls to ctLOKTIMOUT() specifying the data file number.

Lock Statistics

Locking statistics have an inconsistency when a lock request is removed from a list of waiting lock requests. When a lock request times out with this new feature, it is removed from the wait list. For instance, if a thread is waiting for a lock and it is killed by ctadmn, the lock is removed from the waiting list, however, the lock statistics do not reflect this. In fact, the count of currently blocked locks will be off (too high) by one for each lock request removed from a wait list. A new lock statistic has been added to account explicitly for lock requests that have been removed from the wait list: “killed.” It is treated in the same manner as the deadlock category.

CHECKLOCK_FILE

CHECKLOCK_FILE

Enables or disables ctCHECKLOCK mode for specified data files. This file mode can be invoked a number of ways. A file can be created with this set or it can be opened with this set. In V11.5 and later, you can use this server keyword to enable it dynamically.

Note In V13.0.3 onwards, we enable ctCHECKLOCK on all files by default, since AUTO_CHECKLOCK is set to YES, overriding CHECKLOCK_FILE. You can change this behavior by setting AUTO_CHECKLOCK to NO.

When enabled, the server will block all updates to the file without a write lock, returning an error 57. This allows you to debug situations where two processes might attempt to update the same record in an overlapping manner. This is primarily used in non-transaction files, as transaction-controlled files always require a write lock for updates. You can use the wildcard character "*" to specify multiple files.

The following FairCom Server configuration option enables ctCHECKLOCK mode for data files whose names match filespec:

CHECKLOCK_FILE +filespec

• where filespec is the name of a file, which can include wildcards, as described in FairCom DB Standard Wildcards. filespec needs to match the actual file name including extension.

This option takes effect immediately: all currently open and subsequently opened or created data files whose name match filespec have ctCHECKLOCK enabled.

The following FairCom Server configuration option is used to undo the effect of the CHECKLOCK_FILE +filespec:

CHECKLOCK_FILE -filespec

This option disables the ctCHECKLOCK mode for data files whose name match filespec (which can include wildcards) and whose ctCHECKLOCK option was turned on by the ctCHECKLOCK +filespec.

This option takes effect immediately: all currently open data files whose names match filespec have ctCHECKLOCK disabled, and subsequently opened or created data files whose names match filespec will not have ctCHECKLOCK enabled (unless another CHECKLOCK option has been specified that matches the data file name, or the file mode at file open or create time specifies the ctCHECKLOCK mode).

This feature is also available at runtime via the ctSETCFG() API call.

Default: Off

COMPATIBILITY LKISAM_MODES

COMPATIBILITY LKISAM_MODES

LockISAM() will return BMOD_ERR if the lokmod parameter includes any modifier bits that are intended for FairCom use only.

In V11.0 and later, adding COMPATIBILITY LKISAM_MODES to the ctsrvr.cfg file will disable this.

Default: Off

Do not use this keyword unless instructed to by FairCom.

ITIM_RETRY_DEFER

ITIM_RETRY_DEFER <defer_time>

Introduces a delay before internally retrying an ISAM record read operation when an ITIM_ERR (160) is encountered. <defer_time> specifies the time in milliseconds for which the server sleeps a thread that encounters error ITIM_ERR during an ISAM record read operation before retrying the ISAM record read operation. As before, the maximum number of ITIM_ERR retries for a particular ISAM record read operation is determined by the ITIM_RETRY_LIMIT configuration option.

ITIM_RETRY_DEFER -1 disables the delay between ITIM_ERR retries.

Comments

If you frequently encounter ISAM record read operations failing with error ITIM_ERR, consider what the error code is revealing about your application’s design: if you properly use record locking, ITIM_ERR can still occur if many users are updating the same records in sequence (that is, each of a number of threads reads the record with a lock, updates the record--changing the key value--and unlocks the record). In this case, increasing the ITIM_RETRY_LIMIT and ITIM_RETRY_DEFER settings can help avoid the ITIM_ERR errors, however, this may be at the expense of application performance, by introducing additional retries and delays between retries. In such a situation, consider ways to change the application to reduce the number of users that are attempting to update the same records at the same time.

Default: -1

See Also

ITIM_RETRY_LIMIT

ITIM_RETRY_LIMIT

ITIM_RETRY_LIMIT <# of retries before returning ITIM_ERR>

In a multi-user environment, it is possible that an index may become out of sync with the data temporarily while another user is performing an update operation. Typically, error ITIM_ERR (160) is returned under these circumstances. It may be practical in some situations to retry the operation as the index is eventually updated. To accomplish this, the ITIM_ERR retry limit is configurable.

In addition, SNAPSHOT output now contains the value of the limit and the number of failed retry loops. Before this change, only the number of retries was reported by the SNAPSHOT.

Default: Typically 10 or 20

See Also

ITIM_RETRY_DEFER

DIAGNOSTICS DLOK_ERR

DIAGNOSTICS DLOK_ERR

Enables logging of DLOK_ERR (42) lock error information to CTSTATUS.FCS.

The log entry shows the filename, data record offset, and the lock owner.

Example output:

Mon Jun 05 15:18:42 2006
 - User# 00012 DLOK_ERR: file=vcusti offset=0x0000-00002899 owner=11

DIAGNOSTICS LOCK_DUMP

DIAGNOSTICS LOCK_DUMP

Enable the use of the LockDump() function for non ADMIN users. The ADMIN user account can call the LockDump() function without this keyword enabled.

Default: Disabled