Transaction Processing

The available transaction processing commands are summarized in the following sections. These Python, SQL, and ObjectScript commands are identical in functionality, with any exceptions noted in the command definition below.

Transaction commands, such as begin, commit, and rollback, are recorded in the journal and can be accessed via the Management Portal (System Operation > Journals). Journaling plays a critical role in supporting backups and ensuring disaster recovery. Read about backups and journaling to learn more.

The following are examples of transaction processing. The code below performs database modifications and then transfers funds from one account to another:

Python SQL class

# Transfer funds from one account to another in Python with SQL

def transfer(from_account, to_account, amount):
  try:
    iris.tstart()
    iris.sql.exec("UPDATE Bank.Account SET Balance = Balance - ? WHERE AccountNum = ?", (amount, from_account))
    iris.sql.exec("UPDATE Bank.Account SET Balance = Balance + ? WHERE AccountNum = ?", (amount, to_account))
    iris.tcommit()
    return "Transfer succeeded"
  except Exception as e:
    iris.trollbackone()
    return f"Transaction failed: {e}"

START TRANSACTION;

UPDATE Bank.Account
SET Balance = Balance - 500
WHERE AccountNum = '12345';

UPDATE Bank.Account
SET Balance = Balance + 500
WHERE AccountNum = '67890';

COMMIT;

 ClassMethod TransferFunds(from As %String, to As %String, amount As %Double) As %Status
 {
    // Transfer funds from one account to another in ObjectScript
    tstart
    try {
        set acctFrom = ##class(Bank.Account).%OpenId(from)
        set acctTo = ##class(Bank.Account).%OpenId(to)
        if acctFrom = "" || acctTo = "" {
            throw ##class(%Exception.StatusException).CreateFromStatus($$$ERROR("Account not found"))
        }
  
        set acctFrom.Balance = acctFrom.Balance - amount
        set acctTo.Balance = acctTo.Balance + amount
  
        set status = acctFrom.%Save()
        $$$ThrowOnError(status)
        set status = acctTo.%Save()
        $$$ThrowOnError(status)
  
        tcommit
        return $$$OK
    } catch ex {
        trollback 1
        return ex.AsStatus()
    }
 }

A transaction typically consists of a sequence of atomic operations that either completes entirely or not at all. If an error or system malfunction interrupts the transaction, the system uses rollback logic you've defined to undo any completed operations to restore the state before the failure. To cite the example of a bank transaction, rolling back an incomplete transaction prevents money from being removed from one account but not credited to another in the case of a system crash mid-process. As long as the removal of money from one account is grouped in the same transaction as depositing the money in another, a rollback ensures that each account is credited appropriately.

When developing your transaction, include a rollback command for error handling. Using structured error-handling mechanisms — such as TRY-CATCH in ObjectScript or try except in Python — is best practice. InterSystems IRIS is equipped to manage rollbacks automatically in cases of system failure or process termination. For more information, see system automated rollbacks.

Applications typically implement a rollback command in the error-handling block, such as CATCH in TRY/CATCH or EXCEPT in TRY/EXCEPT. To roll back the current nested level of transactions:

• Python: iris.trollbackone()

• SQL: ROLLBACK TO SAVEPOINT

• ObjectScript: trollback 1

The following code samples illustrate how to use rollback commands within transactions, along with error handling to maintain data integrity.

Each sample starts a transaction and sets up an error handler. Operations on data structures or variables are executed, including an intentional error to trigger the rollback. If an error occurs, the handler undoes all changes and displays "Transaction Failed." If the line triggering an error were deleted and no error occurs, the transaction is committed successfully with a commit command, and a success message, “Transaction Committed," is displayed.

Python ObjectScript class

def rollback_example():
    try:
        iris.tstart()
        # Withdraw too much from the account to simulate a failure
        result1 = iris.sql.exec("UPDATE Bank.Account SET Balance = Balance - 1000 WHERE AccountNum = ?", "12345")
        result2 = iris.sql.exec("UPDATE Bank.Account SET Balance = Balance + 1000 WHERE AccountNum = ?", "67890")
        
        # Simulate a failure if the balance drops below zero
        balance = iris.sql.exec("SELECT Balance FROM Bank.Account WHERE AccountNum = ?", "12345").first()[0]
        if balance < 0:
            raise Exception("Insufficient funds")

        iris.tcommit()
        print("Transaction Committed")
    except Exception as e:
        iris.trollbackone()
        print(f"Transaction Failed: {e}")

 TRY {
    NEW balance
    tstart
    &sql(UPDATE Bank.Account SET Balance = Balance - 1000 WHERE AccountNum = '12345')
    &sql(UPDATE Bank.Account SET Balance = Balance + 1000 WHERE AccountNum = '67890')
    
    &sql(SELECT Balance INTO :balance FROM Bank.Account WHERE AccountNum = '12345')
    IF balance < 0 {
        THROW ##class(%Exception.StatusException).CreateFromStatus($$$ERROR("Insufficient funds"))
    }
 
    tcommit
    WRITE !, "Transaction Committed"
 } CATCH ex {
    trollback 1
    WRITE !, "Transaction Failed: ", ex.DisplayString()
 }

 ClassMethod RollbackExample() As %Status
 {
    try {
        // Open account objects
        set acctFrom = ##class(Bank.Account).%OpenId("12345")
        set acctTo = ##class(Bank.Account).%OpenId("67890")
        if (acctFrom = "" || acctTo = "") {
            throw ##class(%Exception.StatusException).CreateFromStatus($$$ERROR("Account not found"))
        }
 
        // Attempt fund transfer with rollback on failure
        if (acctFrom.Balance < 1000) {
            throw ##class(%Exception.StatusException).CreateFromStatus($$$ERROR("Insufficient funds"))
        }
 
        tstart
        set acctFrom.Balance = acctFrom.Balance - 1000
        set acctTo.Balance = acctTo.Balance + 1000
 
        set status = acctFrom.%Save()
        $$$ThrowOnError(status)
        set status = acctTo.%Save()
        $$$ThrowOnError(status)
 
        tcommit
        write "Transaction Committed",!
        return $$$OK
    } catch ex {
        trollback 1
        write "Transaction Failed: ", ex.DisplayString(),!
        return ex.AsStatus()
    }
 }

InterSystems IRIS automatically performs a rollback in cases of system failure or specific events such as process termination. Transaction rollback occurs automatically during each of the three following circumstances:

• At the time of InterSystems IRIS startup, if recovery is needed. When you start InterSystems IRIS and it determines that recovery is required, the system rolls back any incomplete transactions.

• Process termination. Halting a process using a HALT command (for your current process) automatically or the ^RESJOB utility (for other running processes that are NOT your current process) affects in-progress transactions differently depending on the process type. Halting a non-interactive process (or a background job) results in the system automatically rolling back the transaction. If the process is interactive, the system displays a prompt in that process's Terminal session, asking whether to commit or rollback the transaction. This applies whether the process is halted directly or through ^RESJOB.

• System managers roll back incomplete transactions by running the ^JOURNAL utility. When you select the Restore Globals From Journal option from the ^JOURNAL utility main menu, the journal file is restored, and all incomplete transactions are rolled back.

Journaling ensures transaction integrity by recording a time-sequenced log of database changes. Each instance of InterSystems IRIS maintains a journal that logs all SET and KILL operations made during transactions—regardless of the journal setting of the affected databases—as well as all SET and KILL operations for databases whose Global Journal State is set to "Yes.”

Backups can be performed during transaction processing; however, the resulting backup file may contain partial or uncommitted transactions, which could compromise transactional consistency if restored in isolation.

In the event of a disaster that requires restoring from a backup:

1. Restore the backup file

2. Apply journal files to the restored copy of the database

Applying journal files restores all journaled updates—from the time of the backup up to the point of failure—to the recovered database. Applying journals maintains transactional integrity by completes any partial transactions and rolls back those that were not committed.

For more information, see also:

• ECP Recovery Process, Guarantees, and LimitationsOpens in a new tab

• JournalingOpens in a new tab

• Importance of JournalsOpens in a new tab

• Backup and RestoreOpens in a new tab

• $INCREMENT and $SEQUENCE in Transactions and Rollbacks

• Lock Behavior with Transactions

You can temporarily suspend all current transactions within a process using the TransactionsSuspended() method. Changes made while transactions are suspended cannot be rolled back. Changes made before or after the suspension are still able to be rolled back. This is a potent feature that should be used with caution. If used recklessly, it can lead to incomplete and irreversible changes, which may affect data integrity. Use it only when rollback behavior is not needed and data consistency is not at risk. Suspending transactions can be appropriate in specific, controlled cases—such as bypassing rollback for audit logging, improving performance on low-risk operations, or ensuring certain changes persist during administrative tasks.

To suspend all current transactions, invoke one of the following methods:

• In Python, call the TransactionsSuspended() method of the iris.system.Process class. This method takes a boolean argument: 1 suspends all current transactions and 0 (default) resumes them. It returns a boolean indicating the previous state.

• In ObjectScript, call the TransactionsSuspended()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. This method takes a boolean argument: 1 suspends all current transactions and 0 (default) resumes them. It returns a boolean indicating the previous state.

There is no SQL equivalent to TransactionsSuspended().

While ^%ETN remains functional for compatibility with legacy systems, you should use structured exception handling and explicit rollback commands in modern applications. Further details are provided in the ^%ETN documentation.Opens in a new tab

^%ETN is a legacy utility that remains available for handling incomplete transactions in certain systems. If an error occurs during a transaction and you have not explicitly handled rollback using a rollback command, ^%ETN or FORE^%ETN will prompt the user to commit or rollback the transaction. Committing an incomplete transaction can compromise logical database integrity. To prevent this, use structured error-handling mechanisms as recommended in the section on error handling alongside explicit rollback commands.

If your application invokes ^%ETN or FORE^%ETN in an interactive process (such as running a routine in the Terminal) after an error with an active transaction, the user sees the following prompt before the process terminates:

You have an open transaction.
Do you want to perform a (C)ommit or (R)ollback?
R =>

If the user do not respond within 30 seconds, the system automatically rolls back the transaction. In a background job, the rollback happens immediately without displaying a prompt.

By default, ^%ETN and FORE^%ETN exit using HALT. In a background job, HALT automatically rolls back the transaction. In an interactive process, HALT prompts the user to either commit or rollback. However, the BACK^%ETN and LOG^%ETN entry points do display a prompt or automatically roll back failed transactions; the user must explicitly roll back using trollback 1 before calling these routines.