T4.3: Ensures Data Integrity

InterSystems IRIS automatically journals any global update that is part of a transaction, regardless of the global journal state setting for the database in which the affected global resides. This ensures complete transaction integrity and recoverability even for non-journaled databases. When a transaction begins with TSTART, the $TLEVEL special variable increments to track nesting depth. All SET and KILL operations on globals within the transaction are recorded in the journal with transaction markers.

The journal contains specific transaction record types: BT (Begin Transaction) when $TLEVEL was zero, and BTL (Begin Transaction with Level) for nested transactions. During a transaction, journal entries accumulate but actual commitment is deferred until the outermost TCOMMIT decrements $TLEVEL to 0. This deferred commitment allows nested transactions to be individually rolled back while maintaining overall transaction consistency. The journal write cycle ensures that TCOMMIT operations request a flush of journal data to disk, with configurable synchronous commit behavior determining whether the operation waits for disk write completion.

Within transactions, the journal provides both atomicity and durability. If a system crash occurs during a transaction, InterSystems IRIS uses journal entries during startup recovery to roll back any incomplete transactions, ensuring that no partial transaction changes remain in the database. The journal also records transaction markers that identify transaction boundaries, enabling tools like %SYS.Journal.System.GetImageJournalInfo() to analyze transaction history and identify open transactions. This comprehensive journaling of transactional operations is fundamental to ACID compliance in InterSystems IRIS.

Outside of transactions, journaling behavior is controlled by the database-level Global Journal State property, which can be either Yes or No. The journaling state is a property of the database, not individual globals. By default, all databases you create are journaled. In newly installed InterSystems IRIS instances, the IRISAUDIT, IRISSYS, and USER databases are journaled by default, while IRISLIB, IRISTEMP, and IRISLOCALDATA databases are not journaled. Operations to globals in IRISTEMP are never journaled; you should map temporary globals to the IRISTEMP database to avoid unnecessary journal overhead.

When a global update occurs outside a transaction, InterSystems IRIS checks the Global Journal State of the database containing that global. If the state is Yes, the SET or KILL operation is journaled. If the state is No, the operation is not journaled. This differs fundamentally from transactional behavior, where updates are journaled regardless of the database journal state. The journal write cycle operates continuously, with journal sync operations triggered every two seconds when the system is idle, or more frequently under active load.

Non-transactional journaling provides crash recovery capability but not atomicity guarantees. If a system crash occurs, journal recovery at startup reapplies all journaled operations since the last write daemon pass, ensuring that committed global updates are preserved. However, without transaction boundaries, there is no automatic rollback of incomplete operations. Operations on local variables, process-private globals, and special variables like $TEST are never journaled, whether inside or outside transactions. Understanding this distinction is critical for designing robust applications that balance data integrity requirements with performance optimization through selective journaling.

Minimizing journal volume and performance impact requires careful planning of journal configuration and application design. Journal file compression should be enabled using the CompressFiles CPF setting, which is enabled by default for new InterSystems IRIS installations. This significantly reduces the amount of disk space consumed by journal files without impacting recovery capability. For storage architecture, InterSystems recommends placing the primary and alternate journal directories on storage devices that are separated from the devices used by databases and the write image journal (WIJ). While these different devices may be different logical unit numbers (LUNs) on the same storage area network (SAN), the general rule is the more separation the better, with separate sets of physical drives highly recommended.

The major benefits of separating database/WIJ storage from primary and alternate journal storage include isolating journal directories from failures that may compromise the databases, ensuring journaling can continue when the primary directory becomes unavailable, and achieving I/O concurrency that most applications require. The default installation creates a single journal directory as both primary and alternate, but this should be reconfigured as soon as possible after installation. Application design decisions also significantly impact journal volume: map temporary globals and working data to IRISTEMP database, which is never journaled, and consider disabling journaling for databases that contain only transient data or data that can be easily reconstructed from other sources.

Additional optimization strategies include managing journal file retention policies appropriately - only purge journal files that were closed prior to the last known good backup. Set the number of days and number of successful backups after which to keep journal files based on your recovery time objectives and storage capacity. Consider implementing journal archiving to copy journal files to archive storage when they reach maximum size, optionally purging the original after successful archiving. Monitor journal I/O performance through Management Portal metrics and adjust the journal buffer size if needed. The Freeze on error setting should be carefully considered: setting it to Yes prioritizes data integrity over availability by freezing the system if both primary and alternate journal devices fail, while No allows the system to continue with journaling disabled.

Effective transaction management begins with proper pairing of TSTART and TCOMMIT commands. TSTART marks the beginning of a transaction and increments $TLEVEL, while TCOMMIT marks successful completion and decrements $TLEVEL. The transaction is only committed when $TLEVEL returns to 0, meaning the outermost TCOMMIT has been executed. Calling TCOMMIT when $TLEVEL is already 0 results in a COMMAND error, so always check transaction state before issuing transaction control commands. InterSystems IRIS supports nested transactions up to 255 levels, allowing modules to issue their own TSTART/TCOMMIT pairs independently of calling code.

Transaction management requires comprehensive error handling. Use TRY-CATCH blocks with TROLLBACK in the CATCH section to ensure transactions are rolled back on errors. TROLLBACK has two forms: TROLLBACK 1 rolls back only the current nesting level and decrements $TLEVEL by 1, while TROLLBACK (without argument) rolls back all transactions and resets $TLEVEL to 0. Be cautious with nested transactions - if you TROLLBACK 1 an inner transaction and then TCOMMIT the outer transaction, the inner rollback is preserved. Conversely, if you TCOMMIT an inner transaction but TROLLBACK the outer transaction, all changes including the "committed" inner transaction are rolled back because actual commitment is deferred until $TLEVEL reaches 0.

Lock management within transactions requires special attention. By default, locks issued within a transaction are held until the end of the transaction, even if explicitly released. This default can be overridden when setting the lock. Transaction suspension using %SYSTEM.Process.TransactionsSuspended() suspends journaling of changes, and TROLLBACK cannot roll back changes made while transactions were suspended. For performance optimization, consider using synchronous commit (%SYSTEM.Process.SynchCommit()) to control whether TCOMMIT waits for journal data to be written to disk. The default is asynchronous (faster but slightly less durable), while synchronous mode ensures durability at the cost of transaction latency. Monitor transaction duration and avoid long-running transactions that hold locks and increase rollback overhead.

InterSystems IRIS automatically rolls back incomplete transactions in several scenarios. During recovery after a system crash, which occurs as part of InterSystems IRIS startup, the system uses journal entries to roll back any transactions that were in progress at the time of the failure. When you halt your process while transactions are in progress, the system automatically rolls back those transactions. If you terminate a process using the Terminate option from the Processes page of the Management Portal (System Operation > Processes), the system handles rollback differently depending on how the process was initiated: for processes started with the Job command, transactions are automatically rolled back; for user processes, the system prompts whether to commit or roll back incomplete transactions.

ROLLFAIL errors occur when TROLLBACK cannot successfully complete the rollback operation. Common causes include journal files being unavailable, corrupted, or deleted; the database being dismounted during the transaction; or journaling being disabled before database changes were made. The system behavior when a ROLLFAIL occurs depends on the Freeze on error journal configuration setting. If Freeze on error is not set (the default), the process receives a ROLLFAIL error, the transaction is closed, and any locks retained for the transaction are released - this trades data integrity for system availability. If Freeze on error is set, the process halts and the clean job daemon (CLNDMN) retries rolling back the transaction, potentially causing the system to hang while locks remain held - this trades availability for data integrity.

Prevention of rollback failures requires understanding what cannot be rolled back. TROLLBACK does not restore changes to local variables, process-private globals, special variables like $TEST, the current namespace, or LOCK operations. Additionally, $INCREMENT and $SEQUENCE operations on globals are not rolled back - these operations are atomic but not transactional. To prevent ROLLFAIL errors, ensure journaling remains enabled throughout transactions, avoid dismounting databases that contain globals modified in active transactions, maintain adequate disk space for journal files, and configure proper primary and alternate journal directories. When designing applications, structure transactions to be as short as possible, implement proper error handling with explicit TROLLBACK in CATCH blocks, and validate that critical operations completed successfully before committing transactions.