Basic Journaling Operations

Start Journaling

If journaling is stopped, you can start it using the ^JRNSTART routine or by selecting option 1, Begin Journaling, from the ^JOURNAL routine menu. See Start Journaling Using ^JRNSTART for details.

Stop Journaling

Stopping journaling system wide has a number of undesirable consequences, as described in Journal Freeze on Error Setting is No.

When you stop journaling, transaction processing ceases. If a transaction is in progress when you stop journaling, the complete transaction may not be entered in the journal. To avoid this problem, it is best to make sure all users are off the system before stopping journaling.

If you stop journaling and InterSystems IRIS crashes, the startup recovery process does not roll back incomplete transactions started before journaling stopped since the transaction may have been committed but not journaled.

In contrast, transactions are not affected in any adverse way by switching journal files. Rollback correctly handles transactions spanning multiple journal files created by journal switching; so, if possible, it is better to switch journal files than to stop journaling.

You can stop journaling using the ^JRNSTOP routine or by selecting option 2, Stop Journaling, from the ^JOURNAL routine menu. See Stop Journaling Using ^JRNSTOP for details.

View Journal Files

You can view a journal file on the Journals page of the Management Portal (System Operation > Journals).

1. On the Journals page, you can use the Filter box to shorten the list of journal files if necessary.

   If the instance is configured as a mirror member, all journal files including mirrored and nonmirrored are displayed by default. Optionally click the link containing the mirror name, for example Mirror Journal Files Of 'MUNDANE', to display a list of mirror journal files only. If the instance is configured as a reporting async member of multiple mirrors, there is a separate link for the journal files from each mirror. To return to displaying all journal files, click the All Journal Files link.

   Note:

   For information about mirror journal files, see Journal Files and Journal History Log and Mirror Synchronization.

2. To view a journal file, click View in the row of the journal file you want to see. The journal file is displayed record by record on the View Journal page. Fields include the following:

   • Offset — Offset number for the record within the journal file.

   • Time — Time at which the buffer containing this journal record was created (not the time at which the operation described in the record occurred).

   • Process — ID of the process that created the record.

   • Type — Type of operation described by the record. (The Journal File Operations table in Display Journal Records Using ^JRNDUMP provides information about the values that appear in the Type column.)

   • InTransaction — Whether or not the operation occurred as part of a transaction.

   • GlobalNode — Global node that was changed by the operation.

   • Database — Database in which the change occurred.

3. You can:

   1. Click in the Offset column of a record to view a dialog box containing its details.

   2. Choose whether to color code the records by the time of buffer creation, the process that performed the operation recorded in the journal, the type of operation, whether the operation was part of a transaction, the global involved in the operation, or the database involved in the operation.

   3. Search for a particular record set of records using the Match boxes and the Search button.

      1. For a manual search, set the first drop-down to the column you want to search by, select an operator such as “equal to” or “not equal to”, and enter the value you want to match in the right-most box, then click Search.

      2. To match a particular cell in one of the columns, just double-click in that cell. For example, to find all journal records containing KILL operations, double-click in any cell in the Type column containing KILL. The operator drop-down is automatically set to “equal to” but you can change that before pressing Search.

You can also use the ^JRNDUMP utility to display the entire journal and the SELECT^JRNDUMP entry point to display selected entries. See Display Journal Records Using ^JRNDUMP for details.

Switch Journal Files

The system automatically switches the journal file in the following situations:

• After a successful backup of an InterSystems IRIS database

• When the current journal file grows to the maximum file size allowed (configurable on the Journal Settings page)

• When the journal directory becomes unavailable and you specified an alternate directory

• After updating settings in the Journal Settings page of the Management Portal (System Administration > Configuration > System Configuration > Journal Settings).

Switching the journal file is preferable to stopping and starting journaling because during the latter process, any global operations that occur after stopping but before restarting are not journaled.

To manually switch journal files:

1. Navigate to the Journals page of the Management Portal (System Operation > Journals).

2. Click Switch Journal above the list of database journal files.

3. Confirm the journal switch by clicking OK.

You can also switch journal files using the ^JRNSWTCH routine or by selecting option 3, Switch Journal File from the ^JOURNAL routine menu. See Switch Journal Files Using ^JRNSWTCH for details.

Switch Journal Directories

As described in Configuring Journal Settings, journaling automatically switches to the secondary journaling directory (assuming it is configured) if the primary directory becomes unwritable for any reason. To manually switch journaling directories, do the following:

1. Navigate to the Journals page of the Management Portal (System Operation > Journals).

2. Click Switch Directory above the list of database journal files.

3. Confirm the journal switch by clicking OK.

You can also switch journal directories by selecting option 13, Switch Journaling to Secondary/Primary Directory from the ^JOURNAL routine menu. See Switch Journaling Directories Using SWDIR^JOURNAL for details.

Display Journal File Profiles

You can display the global profile of a journal file, showing the globals that appear in the file’s records and the number of records each appears in, from the Journals page.

1. On the Journals page, you can use the Filter box to shorten the list of journal files if necessary.

2. To display a journal file profile, click Profile in the row of the appropriate journal file. The Journal Profile page displays with the profile on it. If the journal file has a large number of records, it may take a little while to build the profile.

3. You can sort the journal profile by global or by the cumulative size, in bytes, of all the records in which each global appears.

4. If the journal file is the current one, you can use the Recalculate button build the profile again after some time has passed.

Check Journal File Integrity

You can check the integrity of a journal file from the Journals page. This operation verifies that the journal file ends where it is expected to end, which verifies that there are no records missing from the end of the file.

1. On the Journals page, you can use the Filter box to shorten the list of journal files if necessary.

2. To run an integrity check on a journal file, click Integrity Check in the row of the appropriate journal file. The Journal Integrity Check page displays.

3. Select Check Details to scan the journal file record by record from the beginning to detect potential missing records.

4. Once you have clicked OK, a link to the Background Tasks page (System Operation > Background Tasks) appears, letting you view the status and results of the integrity check.

View Journal File Summaries

You can view summary information about a journal file on the Journal File Summary page. For example, you can find out whether the journal file is encrypted, and what databases are affected by the operations recorded in the journal file.

1. Click Journals from the System Operations menu of the home page to list the instance’s journal files. Use the Filter box to shorten the list if necessary.

2. To view information about a journal file, click Summary in the row of the appropriate journal file. The Journal File Summary page displays.

Purge Journal Files

You can schedule a task to run regularly that purges obsolete journal files. A new InterSystems IRIS instance contains a pre-scheduled Purge Journal task that is scheduled to run after the daily Switch Journal task that runs at midnight. For information about purging mirror journal files, see Purging Mirror Journal Files.

The purge process deletes journal files based on the When to purge journal files setting on the Journal Settings page; for information, see Configure Journal Settings.

You can also purge journal files using the PURGE^JOURNAL routine or by selecting option 6, Purge Journal Files from the ^JOURNAL routine menu. See Purge Journal Files Using PURGE^JOURNAL for details.

Purging Mirror Journal Files

Mirror journal files are subject to additional purge criteria because they must be successfully distributed by the primary failover member to the other mirror members and dejournaled on each to synchronize the mirrored databases (see Mirror Synchronization for a full description of this process). Transmission of the files to the backup is synchronous and always rapid when the mirror is operating normally, but transmission to asynchronous (async) members may take longer and may be delayed when an async is disconnected from the mirror. Backup and DR async members must also follow the same policy as the primary, since they are eligible to become primary in failover or disaster recovery situations. Mirror journal files are therefore purged as follows:

• On the primary failover member, a file is purged when the local journal file purge criteria have been met (see Configure Journal Settings) and when it has been received by the backup (if there is one) and all async members, whichever takes longer. If an async has been disconnected from the mirror for more than 14 days, however, files are purged even if that async has not yet received them.

• On the backup failover member (if there is one) and any disaster recovery (DR) async members, a file is purged when it has been fully dejournaled on that member, when local journal file purge criteria have been met, and when it has been received by all async members, with the same exception for asyncs that have been disconnected for more than 14 days.

• On reporting async members, mirror journal files are purged immediately after they have been dejournaled by default, to ensure that async mirror members do not run out of space (particularly when they are receiving journal files from multiple mirrors). You can optionally configure a reporting async to instead retain the files and purge them according to local journal file purge criteria; see Editing or Removing an Async Member.

No mirror journal file containing a currently open transaction is ever purged on any mirror member.

Restore Journal Files

After a system crash or disk hardware failure, recreate your database by restoring your backup copies. If you have been journaling and your journal file is still accessible, you can further restore your databases by applying changes since the last backup recorded in the journal files to the databases.

To restore the journal files:

1. First confirm that all users exit InterSystems IRIS.

2. If journaling is enabled for the instance, stop journaling using ^JRNSTOP (see Stop Journaling Using ^JRNSTOP).

3. Restore the latest backup of your database.

4. Run the journal restore utility. See Restore Globals From Journal Files Using ^JRNRESTO for details.

5. Restart journaling if it is disabled.

See Also

• Introduction to Journaling

• Configuring Journaling

• Journaling Utilities

• Journaling I/O Errors

• Special Considerations for Journaling