docs.intersystems.com
Home  /  Application Development: Core Topics  /  ObjectScript Reference  /  ObjectScript Special Variables  /  $TLEVEL


ObjectScript Reference
$TLEVEL
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


Contains the current nesting level for transaction processing.
Synopsis
$TLEVEL
$TL
Description
$TLEVEL contains the current transaction level, the number of nested open transactions. The number of TSTART commands issued determines the transaction level.
A $TLEVEL of 0 cannot be decremented. Issuing a TROLLBACK (or TROLLBACK 1) when $TLEVEL=0 performs no operation. Issuing a TCOMMIT when $TLEVEL=0 results in a <COMMAND> error.
The maximum number of transaction levels is 255. Attempting to exceed 255 transaction levels generates a <TRANSACTION LEVEL> error.
This special variable cannot be modified using the SET command. Attempting to do so results in a <SYNTAX> error.
SQL and $TLEVEL
$TLEVEL is also set by SQL transaction statements as follows:
Despite their shared use of $TLEVEL, ObjectScript transaction processing differs from, and is incompatible with, SQL transaction processing. An application should not attempt to mix the two types of transaction processing statements within the same transaction.
Transaction Level and the Terminal Prompt
By default, if $TLEVEL is greater than 0 at the conclusion of a command line or program executed from the Terminal prompt, the current transaction level is displayed as a Terminal prompt prefix.
This Terminal prompt display is configurable, as described in ZNSPACE.
The SQL Shell prompt does not display the current transaction level. Upon exiting the SQL Shell the current $TLEVEL value is displayed at the Terminal prompt. This can including transaction levels established before entering the SQL Shell and transaction level changes that occurred while in the SQL Shell.
Examples
The following example shows that each TSTART increments $TLEVEL and each TCOMMIT decrements $TLEVEL:
  WRITE !,"transaction level ",$TLEVEL  // 0
  TSTART
  WRITE !,"transaction level ",$TLEVEL  // 1
  TSTART
  WRITE !,"transaction level ",$TLEVEL  // 2
  TCOMMIT
  WRITE !,"transaction level ",$TLEVEL  // 1
  TCOMMIT
  WRITE !,"transaction level ",$TLEVEL  // 0
The following example shows that repeated invocations of TSTART increment $TLEVEL, and TROLLBACK 1 decrements $TLEVEL.
  WRITE !,"transaction level ",$TLEVEL  // 0
  TSTART
  WRITE !,"transaction level ",$TLEVEL  // 1
  TSTART
  WRITE !,"transaction level ",$TLEVEL  // 2
  TROLLBACK 1
  WRITE !,"transaction level ",$TLEVEL  // 1
The following example shows that repeated invocations of TSTART increment $TLEVEL, and TROLLBACK resets $TLEVEL to 0.
  WRITE !,"transaction level ",$TLEVEL  // 0
  TSTART
  TSTART
  TSTART
  WRITE !,"transaction level ",$TLEVEL  // 3
  TROLLBACK
  WRITE !,"transaction level ",$TLEVEL  // 0
The following example shows that if $TLEVEL is 0, TROLLBACK commands have no effect:
  WRITE !,"transaction level ",$TLEVEL  // 0
  TROLLBACK
  WRITE !,"transaction level ",$TLEVEL  // 0
  TROLLBACK 1
  WRITE !,"transaction level ",$TLEVEL  // 0
  TROLLBACK
  WRITE !,"transaction level ",$TLEVEL  // 0
See Also