TCOMMIT (ObjectScript)
Synopsis
TCOMMIT:pc
TC:pc
Argument
Argument | Description |
---|---|
pc | Optional — A postconditional expression. |
Description
TCOMMIT marks the successful end of a transaction initiated by the corresponding TSTART.
TCOMMIT decrements the value of the $TLEVEL special variable. InterSystems IRIS terminates the transaction only if $TLEVEL goes to 0. Usually this is when TCOMMIT has been called as many times as TSTART. Changes made during nested transactions are not committed until $TLEVEL=0.
Calling TCOMMIT when $TLEVEL is already 0 results in a <COMMAND> error. This can occur if you issue a TCOMMIT when no transaction is in progress, when the number of TCOMMIT commands is larger than the number of TSTART commands, or following a TROLLBACK command. The corresponding $ZERROR value consists of <COMMAND>, the location of the error (for example +3^mytest), and the data literal *NoTransaction.
Argument
pc
An optional postconditional expression. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions.
Examples
You use TCOMMIT with the TROLLBACK and TSTART commands. See TROLLBACK and TSTART for examples of how to use these transaction processing commands together.
Nested TSTART / TCOMMIT
InterSystems IRIS supports the nesting of the TSTART/TCOMMIT commands, so that modules can issue their TSTART/TCOMMIT pairs correctly, independent of any other TSTART/TCOMMIT issued in the modules that called them or in the modules they call. The current nesting level of the transaction is tracked by the special variable $TLEVEL. The transaction is committed when the outermost matching TCOMMIT is issued; that is, when $TLEVEL goes back to 0.
You can roll back individual nested transactions by calling TROLLBACK 1 or roll back all current transactions by calling TROLLBACK. TROLLBACK rolls back the whole transaction that is in effect — no matter how many levels of TSTART were issued — and sets $TLEVEL to 0.
Synchronous Commit
A TCOMMIT command requests a flush of the journal data involved in that transaction to disk. Whether to wait for this disk write operation to complete is a configurable option:
-
To configure this option for the current process, use the %SYSTEM.Process.SynchCommit()Opens in a new tab method.
-
To configure this option system-wide, go to the Management Portal, select System Administration, Configuration, Additional Settings, Compatibility. View and edit the current setting of SynchCommit. When set to “true”, TCOMMIT does not complete until the journal data write operation completes. When set to “false”, TCOMMIT does not wait for the write operation to complete. The default is “false”. A restart is required for a change to the SynchCommit setting to take effect.
SQL and Transactions
ObjectScript and SQL transaction commands are fully compatible and interchangeable, with the following exception:
ObjectScript TSTART and SQL START TRANSACTION both start a transaction if no transaction is current. However, START TRANSACTION does not support nested transactions. Therefore, if you need (or may need) nested transactions, it is preferable to start the transaction with TSTART. If you need compatibility with the SQL standard, use START TRANSACTION.
ObjectScript transaction processing provides limited support for nested transactions. SQL transaction processing supplies support for savepoints within transactions.