Skip to main content


class Journal.Restore extends %Library.RegisteredObject

Example 1 (Restore everything in selected journal files of current Cache system):
  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 Cache system
  s RestOref.LastFile="/another_system/20100107.002" ;copied from another Cache system
  s RestOref.JournalLog="/another_system/journal.log" ;copied from another Cache system
  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()

Property Inventory

Method Inventory


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.


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 is not journaled, cannot be mounted, etc.)
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 Cache system.
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 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()


method CheckJournalIntegrity(Scan As %Integer = 0) as %Status
To check the selected journal files for problems (missing files, corruptions, etc.)
  • 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

Inherited Members

Inherited Methods

FeedbackOpens in a new tab