Transaction Parameters

The requirements for the level of data consistency (or transaction isolation) are determined by the application and may also differ for different types of transactions within the application. It is therefore the developer's responsibility to tell Tamino which kind of transactional behaviour is required in order to achieve the correct balance between the required level of concurrency and transaction isolation.

For this purpose Tamino provides the following parameters which may be manipulated by an application:

The isolationLevel Parameter

The isolationLevel parameter determines the level of isolation for a transaction and depending on the isolation level chosen it determines the types of locks that will be set on database objects for the duration of the transaction as described in Isolation Levels in Tamino. In addition the locking behaviour of Tamino may by influenced by the lockMode parameter.

The default value of the isolationLevel parameter depends on the chosen session mode.

For more information see section The _isolationLevel Parameter of the X-Machine Programming manual.

The lockMode Parameter

The lockMode parameter overrides the default locking behaviour of Tamino as determined by the isolation level. This effect is also described in detail in Isolation Levels in Tamino.

Overriding the default locking behaviour of Tamino influences the level of isolation achieved within a transaction and must therefore be used with care. In most cases, there is no need to explicitly set a different lockMode, the specified setting of the isolationLevel normally should provide the required functionality.

There are three possible options to choose:

  1. "shared"
    In most isolation levels setting the lockMode parameter to the value "shared" might have only little or no effect.

  2. "unprotected"
    Setting the lockMode parameter to "unprotected" weakens the locks set by the default behaviour determined by the chosen isolation level whereas setting the parameter to the value "protected" result in stronger locks.

  3. "protected"
    Strengthening the locks by setting the lockMode parameter to "protected" can be used with all read commands. It raises the locks set on the documents retrieved to an X lock. This may be useful in situations where a document is read to be updated later in the transaction. By setting the X lock required for the update already at the time the document is read, the lock escalation from S to X is avoided and therefore the possibility of deadlock situation may be avoided.

Additionally, the following rules apply:

  1. Weakening or strengthening locks for update commands has no effect in most cases.

  2. There is no explicit default setting for the lockMode parameter, as Tamino’s locking behaviour is determined by the chosen isolation level.

For more information, see section The _lockMode Parameter of the X-Machine Programming manual.

The querysearchmode Parameter

The optional parameter querysearchmode specifies whether a query will run in an atomic way, i.e. setting index locks until the request completes, or whether it is acceptable for concurrent requests to access and possibly modify the indexes while the query is running. Thus, the effect of this parameter is to specify to what extent the locking settings can be weakened during a dirty read (i.e. with _isolationLevel=uncommittedDocument/none or _lockMode=unprotected, but not _lockMode=shared or protected). The parameter can be used for a single query at a time, and cannot be set at a session-wide level. The parameter allows the following settings:

  • _querysearchmode=accurate
    All indexes required by the query are locked. This is the default setting, and applies automatically if the parameter is not specified.

  • _querysearchmode=approximate
    Indexes required by the query are not locked, but subsequent postprocessing will be performed if necessary.

  • _querysearchmode=nonserialized
    Indexes required by the query are not locked, but additional postprocessing is omitted.

For more information, see sections The _xql command and The _xquery command of the X-Machine Programming manual.

The lockWait Parameter

With the lock wait mode parameter you can determine the strategy of how to proceed if a resource required for the transaction is locked. If the lock wait mode is set to "no", the transaction will be rolled back. Otherwise, if "yes" is chosen, the application will wait for the required resource to become available.

The default value of this option depends on the chosen session mode.

For more information see section The _lockWait Parameter of the X-Machine Programming manual.

Time Limits for Transactions

Tamino provides the possibility to specify a transaction time limit for applications or transaction users. It performs an automatic rollback operation on transactions that exceed the value of the specified limit. The following topics are discussed in this context:

The maximumTransactionDuration Parameter

The maximumTransactionDuration parameter sets the maximum duration of a transaction. If the time a transaction takes exceeds this limit, Tamino automatically rolls back the transaction, undoing all modifications done so far in that transaction and releasing all locks.

Notes:

  1. The user session however remains opened even after the forced rollback.
  2. This parameter was previously named _transactionTimeout.

The maximum duration of a transaction is important in case a transaction "hangs". As long as a transaction is active, all locks it has acquired remain and may prevent concurrent transactions to proceed. The reason why a transaction does not terminate may be manifold.

One possible cause is that the application has been implemented in such a way that external resources are used within a transaction which may cause the transaction to wait. In general these situations are to be avoided. Another cause could be that a deadlock situation has arisen in which two or more transaction wait for each other to relinquish locks. Tamino detects deadlocks caused by locks inside of Tamino before a transaction timeout occurs. For deadlocks caused by resources outside of Tamino, a transaction timeout is the only way by which the deadlock can be resolved. The first transaction that is rolled back due to a transaction timeout will relinquish its locks which may allow other transaction waiting for the release of these locks to continue.

It is recommended to set the maximumTransactionDuration parameter as low as possible so that Tamino is capable to release locks quickly in case a transaction does not terminate. Obviously, it is even more important to minimize the possibilities in which transactions do not terminate by avoiding using external resources which may cause delays within the boundaries of a transaction and by avoiding deadlock situations.

The default value for the maximumTransactionDuration parameter is set by the Tamino server property maximum transaction duration.

For more information see section The _maximumTransactionDuration Parameter of the X-Machine Programming manual.

The nonActivityTimeout Parameter

The nonActivityTimeout parameter sets the maximum time an active Tamino session can be idle. If an active Tamino session is idle for longer than this time, Tamino automatically rolls back any open transaction and closes the session. The effect is the same as if a _rollback and _disconnect is executed in that order. Any attempt by an application to use that session, will result in a Tamino response with an error code indicating that the session is no longer alive.

For more information see section The _ nonActivityTimeout Parameter of the X-Machine Programming manual.

Time Measurement

The time measurement for a transaction begins when the first database access (i.e. query, process, delete, create schema or delete schema commands) occurs after an initiating "connect" command or a previous commit or rollback command is executed, and ends when the program issues a disconnect, commit, or rollback command.