Learning
Documentation
Community
Open Exchange
Global Masters
Home / Class Reference / %SYS namespace / Journal.Restore
Private  Storage   

Journal.Restore


class Journal.Restore extends
%RegisteredObject

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) ;optional by itself, but necessary for setting up property SourceDatabases used below
	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()

Inventory


Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 18 9


Summary


Properties
AbortOnDatabaseError AbortOnJournalError DisableJournaling Dismount
Filter FirstFile JournalLocation JournalLog
LastFile MarkerTrigger RollBack SourceDatabases
SwitchOnCurrentJournal

Methods
%AddToSaveSet %ClassIsLatestVersion %ClassName %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IsA %IsModified %New
%NormalizeObject %ObjectModified %OnClose %OnNew
%OriginalNamespace %PackageName %RemoveFromSaveSet %SerializeObject
%SetModified %ValidateObject CheckJournalIntegrity RedirectDatabase
Run SelectUpdates UseJournalLocation


Parameters


• 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


• 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.
• 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.)
• property DisableJournaling as %Boolean [ InitialExpression = 1 ];
Whether to disable journaling of the applied updates (for performance purpose)
• property Dismount as %Boolean [ InitialExpression = 0 ];
To dismount databases whose updates were skipped due to errors
• property Filter as %String;
Specify a filter routine such as "^ZJRNFILT" to apply to every selected updates during journal restore
• property FirstFile as %String [ Required ];
The first journal file to process
• 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.
• 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.
• property LastFile as %String;
The last journal file to process
Default: the last journal file listed in the journal history log given by JournalLog
• property MarkerTrigger as %String;
Specify a routine (or tag) such as "MARKER^ZJRNFILT" to be invoked on journal markers during journal restore
• property RollBack as %Boolean [ InitialExpression = 1 ];
To roll back incomplete transactions at the end of journal restore
• 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
• 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.

Methods


• method %OnClose() as %Status
This callback method is invoked by the %Close method to provide notification that the current object is being closed.

The return value of this method is ignored.

• method %OnNew() as %Status
This callback method is invoked by the %New method to provide notification that a new instance of an object is being created.

If this method returns an error then the object will not be created.

It is passed the arguments provided in the %New call. When customizing this method, override the arguments with whatever variables and types you expect to receive from %New(). For example, if you're going to call %New, passing 2 arguments, %OnNew's signature could be:

Method %OnNew(dob as %Date = "", name as %Name = "") as %Status If instead of returning a %Status code this returns an oref and this oref is a subclass of the current class then this oref will be the one returned to the caller of %New method.

• 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.
• 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.
• method Run() as %Status
To run journal restore
• 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).
• method UseJournalLocation(JournalDirectory As %SysPath) as %Status
Set up JournalLocation