|
|
|
ctLOKTIMOUT
Sets a timeout period for a blocking lock.
Declaration
NINT ctLOKTIMOUT(FILNO datno, LONG mode, LONG timeoutSEC)
Description
In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering
ctLOKTIMOUT() specifies a type of blocking lock. These blocking locks can return a timeout error to indicate a lock request timed out. This is useful to avoid exceptionally long held locks in a system.
Timeouts, measured in seconds, can be specified for blocking lock requests made on data files. There are various ways the timeout can be specified, and in all of them, a zero timeout indicates NO timeout, not a zero timeout. If a lock request fails because of a time out, error code UTIM_OUT (827) is returned.
The long name of the function is SetBlockingLockTimeout(). If datno is -1, then the call is interpreted to apply to all data files. A zero timeoutSEC means to turn off the timeout. There are two options for mode:
Symbolic Constant |
Description |
ctLTOdiagnostic |
Specifies that a message is to be sent to CTSTATUS.FCS each time a lock times out. |
ctLTOallusers |
Specifies that the timeout applies to all users, not just the calling user; only a member of the ADMIN group can use the ctLTOallusers mode, otherwise error LADM_ERR (589) is returned. |
FairCom Server Configuration
A FairCom Server configuration keyword has been defined to set a value for the blocking lock timeout on server startup. Specify the following in your ctsrvr.cfg file:
BLOCKING_LOCK_TIMEOUT_SEC <timeoutSEC>
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.
Return Values
Value |
Symbolic Constant |
Explanation |
|---|---|---|
589 |
LADM_ERR |
Member of ADMIN group required. |
827 |
UTIM_OUT |
A blocking lock request timed out from a ctLOKTIMOUT() call. |
See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.
Here are some ways the API can be used to specify a timeout value.
Examples
LONG my_fileno;
LONG block_timeout = 10;
/* A data file for the calling user */
ctLOKTIMOUT(my_fileno, 0, block_timeout)
/* All data files for the calling user */
ctLOKTIMOUT(-1, 0, block_timeout)
/* A data file, all users */
ctLOKTIMOUT(my_fileno, ctLTOallusers, block_timeout)
/* All data files, all users */
ctLOKTIMOUT(-1, ctLTOallusers, block_timeout)
In any of the above calls, ctLTOdiagnostic could be OR-ed into the mode parameter.
