The TROLLBACK command terminates a transaction by causing a ROLLBACK, which removes all database updates performed within a transaction. A TROLLBACK without an argument also sets $TLEVEL and $TRESTART to zero (0). Issuing a TROLLBACK when no transaction is in progress ($TLEVEL=0) produces 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 is rolled 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 to a $TLEVEL other than zero (0) leaves $REFERENCE empty. This behavior is same as a full TROLLBACK to $TEVEL=0.
For an example of the use of the TROLLBACK command, see Chapter 5: “General Language Features of M”.