$TLEVEL (ObjectScript)
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.
-
Each TSTART increments $TLEVEL by 1.
-
Each TCOMMIT decrements $TLEVEL by 1.
-
Each TROLLBACK 1 decrements $TLEVEL by 1.
-
A TROLLBACK resets $TLEVEL to 0.
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:
-
An initial START TRANSACTION sets $TLEVEL to 1. Additional START TRANSACTION statements have no effect on $TLEVEL.
-
Each SAVEPOINT statement increments $TLEVEL by 1.
-
A ROLLBACK TO SAVEPOINT pointname statement decrements $TLEVEL. The amount of decrement depends on the savepoint specified.
-
A COMMIT resets $TLEVEL to 0.
-
A ROLLBACK resets $TLEVEL to 0.
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.
-
When $TLEVEL=0, the Terminal prompt displays the namespace name (by default). For example, USER>
-
When $TLEVEL>0, the Terminal prompt displays the TLn: prefix before the namespace name, n being an integer 1 through 255. For example, TL4:USER>.
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