Caché ObjectScript Reference
$TLEVEL
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
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, Caché 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.
The MV command (with no argument) enters the interactive MultiValue Shell and immediately rolls back any open transactions. Upon exiting the MultiValue Shell the current $TLEVEL value is 0. The MV command with a MultiValue command line argument does not affect the current transaction level.
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