The TROLLBACK command terminates a transaction by initiating a rollback that removes all database updates performed within the transaction. When used without an argument or a zero (0) argument, TROLLBACK sets both $TLEVEL and $TRESTART to zero (0). If an application issues a TROLLBACK when no transaction is in progress ($TLEVEL=0), GT.M reports an error.
The format of the TROLLBACK command is:
TRO[LLBACK][:tvexpr] [intexpr]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The optional integer expression indicates an argument specifying incremental rollback. If the value of the argument expression is greater than zero, it specifies the value of $TLEVEL to be achieved by the rollback. If the value of the expression is less than zero, the result is the number of levels to rollback. For example; -1 means rollback one level. If the argument expression is zero, the effect is same as not specifying the argument, that is, the entire GT.M transaction rolls back.
Attempting to rollback more than $TLEVEL levels (the outermost transaction) generates an error.
When the TROLLBACK has no argument, at least two (2) spaces must follow the command to separate it from the next command on the line.
In order to allow for error recovery and/or access to the global context of the error, errors do not initiate implicit ROLLBACKs. Therefore, the code for handling errors during transactions should generally include a TROLLBACK. Because the TROLLBACK releases resources held by the transaction, it should appear as early as possible in the error handling code.
A TROLLBACK does not cause a transfer of control but is typically associated with one such as a QUIT (or GOTO).
TROLLBACK always leaves $REFERENCE empty.
For an example of the use of the TROLLBACK command, see Chapter 5: “General Language Features of M”.