Skip to main content
AskMe (beta)
Loading icon
Responses may be inaccurate. Learn more about AskMe.

Journal.Restore

class Journal.Restore extends %Library.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) ;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()

Property Inventory

Method Inventory

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 methods: AbortOnDatabaseErrorDisplayToLogical(), AbortOnDatabaseErrorGet(), AbortOnDatabaseErrorIsValid(), AbortOnDatabaseErrorLogicalToDisplay(), AbortOnDatabaseErrorNormalize(), AbortOnDatabaseErrorSet()
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 methods: AbortOnJournalErrorDisplayToLogical(), AbortOnJournalErrorGet(), AbortOnJournalErrorIsValid(), AbortOnJournalErrorLogicalToDisplay(), AbortOnJournalErrorNormalize(), AbortOnJournalErrorSet()
property DisableJournaling as %Boolean [ InitialExpression = 1 ];
Whether to disable journaling of the applied updates (for performance purpose)
Property methods: DisableJournalingDisplayToLogical(), DisableJournalingGet(), DisableJournalingIsValid(), DisableJournalingLogicalToDisplay(), DisableJournalingNormalize(), DisableJournalingSet()
property Dismount as %Boolean [ InitialExpression = 0 ];
To dismount databases whose updates were skipped due to errors
Property methods: DismountDisplayToLogical(), DismountGet(), DismountIsValid(), DismountLogicalToDisplay(), DismountNormalize(), DismountSet()
property Filter as %String;
Specify a filter routine such as "^ZJRNFILT" to apply to every selected updates during journal restore
Property methods: FilterDisplayToLogical(), FilterGet(), FilterIsValid(), FilterLogicalToDisplay(), FilterLogicalToOdbc(), FilterNormalize(), FilterSet()
property FirstFile as %String [ Required ];
The first journal file to process
Property methods: FirstFileDisplayToLogical(), FirstFileGet(), FirstFileIsValid(), FirstFileLogicalToDisplay(), FirstFileLogicalToOdbc(), FirstFileNormalize(), FirstFileSet()
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 methods: JournalLocationBuildValueArray(), JournalLocationCollectionToDisplay(), JournalLocationCollectionToOdbc(), JournalLocationDisplayToCollection(), JournalLocationDisplayToLogical(), JournalLocationGet(), JournalLocationGetObject(), JournalLocationGetObjectId(), JournalLocationGetSwizzled(), JournalLocationIsValid(), JournalLocationLogicalToDisplay(), JournalLocationLogicalToOdbc(), JournalLocationNormalize(), JournalLocationOdbcToCollection(), JournalLocationSet(), JournalLocationSetObject(), JournalLocationSetObjectId()
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 methods: JournalLogDisplayToLogical(), JournalLogGet(), JournalLogIsValid(), JournalLogLogicalToDisplay(), JournalLogLogicalToOdbc(), JournalLogNormalize(), JournalLogSet()
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 methods: LastFileDisplayToLogical(), LastFileGet(), LastFileIsValid(), LastFileLogicalToDisplay(), LastFileLogicalToOdbc(), LastFileNormalize(), LastFileSet()
property MarkerTrigger as %String;
Specify a routine (or tag) such as "MARKER^ZJRNFILT" to be invoked on journal markers during journal restore
Property methods: MarkerTriggerDisplayToLogical(), MarkerTriggerGet(), MarkerTriggerIsValid(), MarkerTriggerLogicalToDisplay(), MarkerTriggerLogicalToOdbc(), MarkerTriggerNormalize(), MarkerTriggerSet()
property RollBack as %Boolean [ InitialExpression = 1 ];
To roll back incomplete transactions at the end of journal restore
Property methods: RollBackDisplayToLogical(), RollBackGet(), RollBackIsValid(), RollBackLogicalToDisplay(), RollBackNormalize(), RollBackSet()
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 methods: SourceDatabasesBuildValueArray(), SourceDatabasesCollectionToDisplay(), SourceDatabasesCollectionToOdbc(), SourceDatabasesDisplayToCollection(), SourceDatabasesDisplayToLogical(), SourceDatabasesGet(), SourceDatabasesGetObject(), SourceDatabasesGetObjectId(), SourceDatabasesGetSwizzled(), SourceDatabasesIsValid(), SourceDatabasesLogicalToDisplay(), SourceDatabasesLogicalToOdbc(), SourceDatabasesNormalize(), SourceDatabasesOdbcToCollection(), SourceDatabasesSet(), SourceDatabasesSetObject(), SourceDatabasesSetObjectId()
property StartPosition as %String;
The position of the first journal file to begin processing at
Property methods: StartPositionDisplayToLogical(), StartPositionGet(), StartPositionIsValid(), StartPositionLogicalToDisplay(), StartPositionLogicalToOdbc(), StartPositionNormalize(), StartPositionSet()
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.
Property methods: SwitchOnCurrentJournalDisplayToLogical(), SwitchOnCurrentJournalGet(), SwitchOnCurrentJournalIsValid(), SwitchOnCurrentJournalLogicalToDisplay(), SwitchOnCurrentJournalNormalize(), SwitchOnCurrentJournalSet()

Methods

method %OnClose() as %Status
Inherited description: 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
Inherited description: 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.
See SelectUpdates() on how to ensure the SourceDatabase argument is in a proper form.
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).
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.
method UseJournalLocation(JournalDirectory As %SysPath) as %Status
Set up JournalLocation

Inherited Members

Inherited Methods

FeedbackOpens in a new tab