Skip to main content

Journal.Restore

Class Journal.Restore Extends %RegisteredObject [ System = 4 ]

Example 1 (Restore everything in selected journal files of current InterSystems IRIS instance): s RestOref=##class(Journal.Restore).%New() s RestOref.FirstFile="20100107.001" s RestOref.LastFile="20100107.002" s Status=RestOref.Run() Example 2 (Restore selected globals in selected databases from foreign journal files): s RestOref=##class(Journal.Restore).%New() s RestOref.FirstFile="/another_system/20100107.001" ;copied from another InterSystems IRIS instance s RestOref.LastFile="/another_system/20100107.002" ;copied from another InterSystems IRIS instance s RestOref.JournalLog="/another_system/journal.log" ;copied from another InterSystems IRIS instance d RestOref.UseJournalLocation("/another_system") ;and so on (where to locate journal files) s Status=RestOref.CheckJournalIntegrity(1) ;to populate property 'SourceDatabases' with database paths collected from the journal files to be restored s key="" for { s SourceDatabase=RestOref.SourceDatabases.GetNext(.key) q:key="" w !,SourceDatabase," => " r TargetDatabase s Status=RestOref.RedirectDatabase(SourceDatabase,TargetDatabase) s Status=RestOref.SelectUpdates(SourceDatabase,GlobalName1) s Status=RestOref.SelectUpdates(SourceDatabase,GlobalName2) ;and so on } s Status=RestOref.Run()

Parameters​

TYPE​

Parameter TYPE = 0;

This corresponds to the fromrest parameter in journal restore utility.
fromrest is set by the caller of journal restore utility to indicate the type of journal restore (or the type of the caller). For example, ^JCONVERT sets fromrest=8 to instructs journal restore to write out the updates to a file instead of applying them to databases. Some types of restore have their own parameters (e.g., the path of an output file for fromrest=8), so a subclass for each type seems logical.
^JRNRESTO sets fromrest=0, which is the default here.

Properties​

StartTime​

Property StartTime As %TimeStamp [ Private ];

JournalLog​

Property JournalLog As %String;

Path of a journal history log where the selected journal files are listed
Default: the journal history log of local InterSystems IRIS instance.
Set JournalLog=-1 to override the default without specifying a journal log.

JournalLocation​

Property JournalLocation As list Of %String;

A list of directories where the selected journal files are located
Required if JournalLog has a non-default value.

StartPosition​

Property StartPosition As %String;

The position of the first journal file to begin processing at

FirstFile​

Property FirstFile As %String [ Required ];

The first journal file to process

LastFile​

Property LastFile As %String;

The last journal file to process
Default: the last journal file listed in the journal history log given by JournalLog

SelectedFiles​

Property SelectedFiles As %String [ MultiDimensional, Private ];

A list of selected journal files in their current location

zsvalsav​

Property zsvalsav As %Integer [ InitialExpression = 0, Private ];

Original value of $ZSTORAGE to be restored upon close

SourceDatabases​

Property SourceDatabases As list Of %String;

A list of database directories stored in the selected journal files for verifying the source database directories given in the DatabaseRedirection property if specified

DatabaseRedirection​

Property DatabaseRedirection As %String [ MultiDimensional, Private ];

An array of SourceDatabase -> TargetDatabase for database redirection
If none specified, apply updates to the original databases s JrnRestOref=##class(Journal.Restore).%New() s Status=JrnRestOref.RedirectDatabase(SourceDatabase,TargetDatabase)

SelectedUpdates​

Property SelectedUpdates As %String [ MultiDimensional, Private ];

A table of (SourceDatabase,GlobalName) selected to be restored
If none specified, restore everything from the selected journal files s JrnRestOref=##class(Journal.Restore).%New() s Status=JrnRestOref.SelectUpdates(SourceDatabase,GlobalName)

AbortOnJournalError​

Property AbortOnJournalError As %Boolean [ InitialExpression = 1 ];

whether to abort journal restore if an update would have to be skipped due to a journal-related problem (e.g., journal corruption, missing journal files, etc.)

AbortOnDatabaseError​

Property AbortOnDatabaseError As %Boolean [ InitialExpression = 0 ];

Whether to abort journal restore if an update would have to be skipped due to a database-related problem (e.g., a target database cannot be mounted, error applying an update, etc.).
If journal restore is aborted, databases will be left in a self-consistent state as of the record that caused the restore to be aborted. Parallel dejournaling will be disabled with this setting; otherwise, affected database(s) may not be self-consistent and will need to be recovered separately.

Filter​

Property Filter As %String;

Specify a filter routine such as "^ZJRNFILT" to apply to every selected updates during journal restore

MarkerTrigger​

Property MarkerTrigger As %String;

Specify a routine (or tag) such as "MARKER^ZJRNFILT" to be invoked on journal markers during journal restore

DisableJournaling​

Property DisableJournaling As %Boolean [ InitialExpression = 1 ];

Whether to disable journaling of the applied updates (for performance purpose)

SwitchOnCurrentJournal​

Property SwitchOnCurrentJournal As %Integer [ InitialExpression = 1 ];

If current journal file is among the journal files selected to be processed, the user has an option to switch journal file or stop journaling system wide.
This is necessary if DisableJournaling is NO, as otherwise the applied updates will be journaled in the file that will be dejournaled, resulting in data integrity issues.
Even if DisableJournaling is YES, it is still a good practice to switch journal file so that new updates will go into the new file.

RollBack​

Property RollBack As %Boolean [ InitialExpression = 1 ];

To roll back incomplete transactions at the end of journal restore

Dismount​

Property Dismount As %Boolean [ InitialExpression = 0 ];

To dismount databases whose updates were skipped due to errors

Methods​

UseJournalLocation​

Method UseJournalLocation(JournalDirectory As %SysPath) As %Status

Set up JournalLocation

SelectFiles​

Method SelectFiles(ByRef SelectedFiles As %String) As %Status [ Internal ]

Get a list of selected journal files using FirstFile, LastFile, JournalLog and JournalLocation

%OnClose​

Method %OnClose() As %Status

%OnNew​

Method %OnNew() As %Status

CheckJournalIntegrity​

Method CheckJournalIntegrity(Scan As %Integer = 0) As %Status

To check the selected journal files for problems (missing files, corruptions, etc.)
Scan

  • 0: look for missing files and inconsistent journal end offsets;
  • 1: also collect a list of database directories in the selected journal files and store them in SourceDatabases;
  • 2: also perform a more thorough (and more time-consuming) check by going through every record in the selected journal files, which could detect corruptions in the middle of a journal file that would otherwise go unnoticed until the read restore.

RedirectDatabase​

Method RedirectDatabase(SourceDatabase As %String, TargetDatabase As %String) As %Status

Set up journal restore to apply updates of SourceDatabase to TargetDatabase instead of SourceDatabase itself.
Note that for database redirection to take effect, you must also call SelectUpdates() for each database to be restored, even if you intend to have all databases restored.
This method can be called before or after the SelectUpdates() calls.
See SelectUpdates on how to ensure the SourceDatabase argument is in a proper form.

SelectUpdates​

Method SelectUpdates(SourceDatabase As %String, GlobalName As %String = "") As %Status

To select a database or a global in a database to restore
If GlobalName is not specified, all globals in SourceDatabase will be restored, unless you also call SelectUpdates(SourceDatabase,GlobalName) (before or after the call without GlobalName), in which case only the specified global(s) are restored.
GlobalName must begin with an alpha, "%", "*" or "?", followed by alphanumerics and "*?."s ("." for dot syntax).
You must make sure the 'SourceDatabase' argument is in the canonical form acceptable to journal restore. One way to ensure that is illustrated in Example 2 at the beginning of the class document, that is, by calling CheckJournalIntegrity with 1 to have SourceDatabases populated with database paths collected from the journal files to be restored.

Run​

Method Run() As %Status

To run journal restore

Monitor​

ClassMethod Monitor(StartTime As %TimeStamp, Interval As %Integer = 10) As %Status [ Internal ]

To monitor the progress of journal restore