Skip to content

DF_LOCK_TIMEOUT

See Also: Get_Attribute, Set_Attribute, DF_LOCK_DELAY

The time, in milliseconds, after which an ungranted lock will be considered an error.

Level

Global

Type

Numeric, temporary

Access

Read / Write

Values

Milliseconds rounded up to the nearest second.

Remarks

When a lock request fails, additional lock attempts will be executed until the lock is either granted or the DF_LOCK_TIMEOUT time has passed. If a network is slow to grant locks (thus generating premature lock-time out errors), adjust the value of the DF_LOCK_TIMEOUT attribute higher.

The default lock timeout of the Embedded Database is 16 minutes and 16 seconds. The total time is determined by two settings: the DF_LOCK_TIMEOUT attribute and the Transaction_Retry count.

The DF_LOCK_TIMEOUT setting specifies the time a lock will wait before generating the DFERR_LOCK_TIMEOUT (4106) error. This setting is in milliseconds rounded up to the nearest full second, added to the minimal value of 1 second. For example:

  • Setting it to 1 will result in a timeout of 2 seconds.
  • Setting it to 1500 will result in a timeout of 3 seconds.

The default value is 60000 (61 seconds).

The Transaction_Retry count is the number of times the transaction will be retried after receiving the lock timeout error. It can be manipulated using Get_Transaction_Retry and Set_Transaction_Retry. Every time a retry occurs, the object that initiated the transaction fires a Verify_Retry (function returns integer) event. This event can stop the retry mechanism by returning a non-zero value.

Default Settings

  • DF_LOCK_DELAY = 0
  • DF_LOCK_TIMEOUT = 60000
  • Transaction_Retry = 15

Example Changes

You could change these to:

  • DF_LOCK_DELAY = 100
  • DF_LOCK_TIMEOUT = 3000
  • Transaction_Retry = 14

These new defaults would generate a lock timeout error to the user after 1 minute.

Procedure ShowLockAttributes
    Integer iLockDelay
    Integer iLockTimeout
    Integer iLockTimeoutSeconds
    Integer iTransactionRetry
    Integer iTotal
    Integer iHour
    Integer iMin
    Integer iSec
    String sTotal

    Get_Attribute DF_LOCK_DELAY To iLockDelay
    Get_Attribute DF_LOCK_TIMEOUT To iLockTimeout
    Get_Transaction_Retry To iTransactionRetry

    Move (((iLockTimeout + 999) / 1000) + 1) To iLockTimeoutSeconds
    Move ((iLockTimeoutSeconds * iTransactionRetry) + iLockTimeoutSeconds) To iTotal

    If (iTotal >= 3600) Begin
        Move (iTotal / 3600) To iHour
        Move (Mod(iTotal, 3600)) To iTotal
    End

    If (iTotal >= 60) Begin
        Move (iTotal / 60) To iMin
        Move (Mod(iTotal, 60)) To iTotal
    End

    Move iTotal To iSec
    Move (Right("00" + String(iHour), 2) + ":" + ;
          Right("00" + String(iMin), 2) + ":" + ;
          Right("00" + String(iSec), 2)) To sTotal

    Showln "Current lock settings:"
    Showln "  Lock delay: " iLockDelay " milliseconds."
    Showln "  Lock timeout: " iLockTimeoutSeconds " seconds."
    Showln "  Transaction retry: " iTransactionRetry " times."
    Showln "  Total time before timeout error occurs: " sTotal
End_Procedure // ShowLockAttributes

The sample procedure above shows the current lock attribute settings and the total time before a lock timeout error occurs.

Procedure SetLockAttributes
    Set_Attribute DF_LOCK_DELAY To 100
    Set_Attribute DF_LOCK_TIMEOUT To 3000
    Set_Transaction_Retry To 14
End_Procedure // SetLockAttributes

The sample procedure above sets the lock attributes to values such that the time before a lock timeout error occurs is one minute.