Trbegin

Trbegin is used to start a database transaction.

Syntax

 Trbegin TABLE_LIST

• TABLE_LIST is a list of TABLE separated by commas.
• TABLE can be either a table name or an abbreviation of a table already declared.

Examples

# This function debits an account ACCOUNT1 and credits and account ACCOUNT2 with an AMOUNT value# It manages a transaction except if a transaction is already in progress# It also updates a statistical table# Returns [V]CST_AOK if the operation was successful, otherwise returns [V]CST_AERROR.Funprog TRANSFER(ACCOUNT1, ACCOUNT2, AMOUNT)Value Char ACCOUNT1(), ACCOUNT2()Value Decimal AMOUNTLocal Integer IF_TRANS# Start the transaction if no transaction is in progressLocal File ACCOUNT [ACC]If adxlogTrbegin [ACC], STATISTICSIF_TRANS=0Else# The transaction has been started by the calling programIF_TRANS=1Endif# Debit operation (CODE is a unique index so only one database line is updated)Update ACCOUNT Where CODE=ACCOUNT1 With BALANCE=BALANCE-AMOUNTIf fstat# If IF_TRANS=1, the transaction must been aborted by the calling programIf IF_TRANS=0 : Rollback : EndifEnd [V]CST_AERROREndif# Credit operationUpdate ACCOUNT Where CODE=ACCOUNT2 With BALANCE=BALANCE+AMOUNTIf fstat# If IF_TRANS=1, the transaction must been aborted by the calling programIf IF_TRANS=0 : Rollback : EndifEnd [V]CST_AERROREndif# Updates account movement statisticsUpdate [STA] Where STACODE="ACCOUNTS" With MOVEMENTS=MOVEMENTS+1If fstat# If IF_TRANS=1, the transaction must been aborted by the calling programIf IF_TRANS=0 : Rollback : EndifEnd [V]CST_AERROREndif# The operation is successful. If IF_TRANS=1, the transaction must been committed by the calling programIf IF_TRANS=0 : Commit : EndifEnd [V]CST_AOK

Description and comments

• Trbegin is used to start a database transaction, which is a set of operations that update the database tables including counters.
• If the Trbegin instruction is used with the abbreviation of a table that has been opened before, the Filter options that have been previously placed on the table will continue to apply.
• If the Trbegin instruction is used with the name of a table that is not yet opened, the table will automatically be opened as a LocalFile instruction.
• If the Trbegin instruction is used with the name of a table that is already opened, the table will automatically be reopened as a LocalFile instruction. This means that the Filter options that have been previously placed on the table will no longer apply. They will be restored after the end of the transaction.
• When the transaction ends, the tables opened before the transaction stay open and the tables opened by Trbegin or after Trbegin are closed, except those redeclared with an existing abbreviation.
• Commit can only be carried out in the script or subprogram level that executed the Trbegin.
• A single level of transaction is supported by the Sage X3 engine. Thus, if a subprogram that performs an autonomous transaction is called within another transaction, the Trbegin / Commit / Rollback instructions must be executed in the calling nested level. The fact that a transaction is already in progress is defined by the value of adxlog: if a transaction is in progress, its value is 1, otherwise it is 0.
• Even if some tables have not been declared in Trbegin, but were opened before the transaction started, the updates on these tables will be parts of the transaction. They will be committed or rolled back on the Commit / Rollback as well as the updates done on the table explicitly declared in Trbegin.
• The data updated in a transaction is automatically locked. It is therefore recommended to avoid writing transactions that are too long, and especially not to have a waiting loop inside a transaction (this would create deadlocks).
• Writing a transaction inside a For ... WithLock syntax does not work properly. The transaction must include the For loop.

Associated errors

See also

File, Commit, Rollback, Onerrgo, Read, Write, Writeb, Rewrite, RewriteByKey, Delete, DeleteBykey, Lock, adxlog.