Skip to main content

%SYS.Journal.System

Class %SYS.Journal.System Extends %RegisteredObject [ Abstract, System = 4 ]

Journaling related API

Methods​

Start​

ClassMethod Start(curdir As %String, altdir As %String, maxsiz As %Integer, expsiz As %Integer, prefix As %String, okshdw As %Boolean = 0) As %Status

Purpose: Start journaling

Optional parameters for journaling:

  • curdir: primary journal directory
  • altdir: alternate journal directory
  • maxsiz: max size of journal file in bytes
  • expsiz: [Windows & VMS only] unit increment of journal file size in bytes
  • prefix: a string preceding the standard journal file name YYYYMMDD.NNN shdwok: OK to share directory with shadow journal files despite potential file conflicts (DEFAULT = 0) Returns OK on success

Stop​

ClassMethod Stop() As %Status

Purpose: Stop journaling system wide

RollToNextFile​

ClassMethod RollToNextFile(Reason As %Integer, ByRef NewFile As %String) As %Status

Purpose: Roll journaling to next file, without any journal property change (to activate)

Input:

  • Reason: reason for the switch (0 = unspecified, 1 = user-initiated, etc.); Output:
  • NewFile: the path of the file to which journaling has switched (if successfully) Return success or error status.

Caveat: Journal history global is NOT updated, a la journal daemon

GetTheOtherDirectory​

ClassMethod GetTheOtherDirectory(ByRef Directory As %String = "", ByRef Type As %Integer = 0) As %Integer

Get the path of the journal directory other than the current one.
Directory: The journal directory different from the current one or "" if none
Type: 1 if Directory is Primary or 2 if Directory is Secondary or 0 if Directory is "" (meaning no other directory)

SwitchDirectory​

ClassMethod SwitchDirectory(ByRef NewFile As %String = "") As %Status

Switch journaling to the other journal directory if specified
Return (by reference) the path of current journal file after a successful switch.

SwitchFile​

ClassMethod SwitchFile(curdir As %String, altdir As %String, maxsiz As %Integer, expsiz As %Integer, okshdw As %Boolean = 0, reason As %Integer) As %Status

Purpose: Switch journal file (and optionally change one or more journaling parameters)

Optional parameters for journaling:

  • curdir: primary journal directory
  • altdir: alternate journal directory
  • maxsiz: max size of journal file in bytes
  • expsiz: [Windows & VMS only] unit increment of journal file size in bytes
  • shdwok: OK to share directory with shadow journal files despite potential file conflicts (DEFAULT = 0)
  • reason: reason for journal switch (DEFAULT: by user) Returns OK on success

GetDefaults​

ClassMethod GetDefaults(ByRef curdir As %String, ByRef altdir As %String, ByRef maxsize As %Integer, ByRef expqty As %Integer, ByRef prefix As %String, ByRef shortnam As %String, curfile As %String, jrnall As %Integer) As %Status [ Internal, PublicList = (curdir, altdir, maxsize, expqty, prefix, shortnam, curfile, jrnall) ]

IsJournalEncryptionEnabled​

ClassMethod IsJournalEncryptionEnabled(Type As %Integer = 1) As %Integer

Return current journal encryption status.
Type - 1: Run time journal encryption status (default).
2: Startup journal encryption status.
3: Run time or Startup encryption status.
Retrun 1 if journal encryption status is enabled, otherwise return 0.

ActivateEncryption​

ClassMethod ActivateEncryption(EnableStartup As %Boolean = 1) As %Status

Activate journal encryption such that new updates go to encrypted journal files.

DeactivateEncryption​

ClassMethod DeactivateEncryption(DisableStartup As %Boolean = 1) As %Status

Deactivate journal encryption such that new updates go to unencrypted journal files.

OKNoDBEncKeyNow​

ClassMethod OKNoDBEncKeyNow() As %Status

Return OK if DBEncKey is not required for individual jobs to roll back their own open transactions (i.e., OK to deactivate DBEncKey); otherwise, return an error indicating why DBEncKey must stay activated.

OKNoDBEncKeyAtStartup​

ClassMethod OKNoDBEncKeyAtStartup(LocalOnly As %Boolean = 0) As %Status

Return OK if DBEncKey is not required at startup (i.e., OK to disable DBEncKey activation at startup); otherwise, return an error indicating why DBEncKey must be activated at startup.

IsEncKeyInUse​

ClassMethod IsEncKeyInUse(DBEncKeyID As %String) As %Boolean

TRUE if the given DBEncKeyID is used on journal files required for recovery

IsDisabled​

ClassMethod IsDisabled(Status As %String = "", ByRef Cause As %String) As %Boolean

TRUE if journaling is disabled system wide

IsPaused​

ClassMethod IsPaused(Status As %String = "", ByRef Cause As %String) As %Boolean

TRUE if journaling is paused system wide (when there is an ongoing journal switch)

IsFrozen​

ClassMethod IsFrozen(Status As %String = "", ByRef Cause As %String) As %Boolean

TRUE if journaling is frozen system wide (i.e., journal updates are blocked), typically when there is a journaling error and the system is set up to freeze on such errors.

IsGettingIOError​

ClassMethod IsGettingIOError(Status As %String = "", ByRef Cause As %String) As %Boolean

TRUE if there is a journaling error, from which the system may be trying to recover

GetLastFileName​

ClassMethod GetLastFileName() As %String

Get the path of the last journal file on the system -- meaningful only if current journal file name = "" (i.e., journaling hasn't started)

GetCurrentFileName​

ClassMethod GetCurrentFileName() As %String

Return the path of current journal file

GetCurrentFile​

ClassMethod GetCurrentFile() As %SYS.Journal.File

Return the object reference to current journal file

GetCurrentFileOffset​

ClassMethod GetCurrentFileOffset() As %Integer

Returns the ending offset of the last journal record in current journal file; 0 if journaling is off

GetCurrentFileCount​

ClassMethod GetCurrentFileCount() As %Integer

Return the file count of current journal file

GetStateString​

ClassMethod GetStateString() As %String

Returns the state of the journaling system as a string. Values are:

"Normal" (Enabled and running normally)
"Disabled" (stopped)
"Suspended" (due to I/O error)
"Frozen" (due to I/O error)
"Paused" (during journal file switch)

Frozen and Suspended are the same state (I/O error occurred), but they differ in the action processes take (freeze or discard journal data respectively) when they encounter this state.

GetState​

ClassMethod GetState() As %Integer

Returns the state of the journaling system as an Integer
0 - Enabled
1 - Disabled (stopped)
2 - Suspended (due to I/O error)
3 - Frozen (due to I/O error)
4 - Paused (during journal file switch)

Sync​

ClassMethod Sync() As %Integer [ CodeMode = expression ]

Purpose: Sync (commit) journal data to disk

Returns a journal offset. It is guaranteed that journal data at or prior to the offset are on disk by the time Sync() returns.

Caveat: It is possible that journal file has been switched by the time Sync() returns. In that case, it is unpredictable which journal file the returned offset refers to and one might have to repeat Sync() until journal file remains the same before and after.

WhereCommitted​

ClassMethod WhereCommitted() As %Integer [ CodeMode = expression ]

Purpose: Report what portion of the journal has been committed to disk

Returns a journal offset. It is guaranteed that journal data at or prior to the offset are on disk.

Caveat: see Sync

GetImageJournalInfo​

ClassMethod GetImageJournalInfo(ByRef JournalFileName As %String, ByRef JournalFileOffset As %Integer, ByRef JournalFileCount As %Integer, ByRef OpenTransFileOffset As %Integer, ByRef OpenTransFileCount As %Integer) As %Status

Return the journal checkpoint information stored in the WIJ (aka Write Image Journal)

GetClusterJournalLog​

ClassMethod GetClusterJournalLog() As %String

Return the path of the cluster journal log

GetPrimaryDirectory​

ClassMethod GetPrimaryDirectory(ByRef Status As %Status = {$$$OK}) As %String

Return the path of the primary journal directory, which is not necessarily the current journal directory

GetAlternateDirectory​

ClassMethod GetAlternateDirectory(ByRef Status As %Status = {$$$OK}) As %String

Return the path of the secondary journal directory

GetJournalFilePrefix​

ClassMethod GetJournalFilePrefix() As %String

Return the journal file name prefix

SetPrimaryDirectory​

ClassMethod SetPrimaryDirectory(dir As %String, create As %Boolean) As %Status

SetAlternateDirectory​

ClassMethod SetAlternateDirectory(dir As %String, create As %Boolean) As %String

GetFreeSpace​

ClassMethod GetFreeSpace() As %Integer

Return the free space available for journal files

VerifyJournalDirectory​

ClassMethod VerifyJournalDirectory(dir As %String, create As %Boolean) As %Status [ Internal, Private ]

VerifyJournalFilePrefix​

ClassMethod VerifyJournalFilePrefix(prefix As %String) As %Status [ Internal ]

GetHistoryHeader​

ClassMethod GetHistoryHeader(jrnlogfd As %String, ByRef header As %String, Mirror As %Boolean = 0) As %Status [ Deprecated, Internal ]

PurgeHistory​

ClassMethod PurgeHistory(DaysOld As %Integer = 100) As %Status [ Deprecated, Internal ]

DisableJournalWithAllRole​

ClassMethod DisableJournalWithAllRole() As %Status [ Internal ]

GetDejournalReaderSettings​

ClassMethod GetDejournalReaderSettings(ByRef CacheSize As %Integer, ByRef ReadAheadSize As %Integer, ByRef disableaio As %Integer) As %Status [ Internal ]

GetDejournalSettings​

ClassMethod GetDejournalSettings(type As %String, name As %String, ByRef numpref As %Integer, ByRef quesiz As %Integer, ByRef stksiz As %Integer, ByRef sizmod As %Integer, ByRef numupd As %Integer, ByRef rangemax As %Integer, ByRef maxpref As %Integer, ByRef inorder As %Integer) As %Status [ Internal ]

Supported 'type' values are: "jrnrest" for journal restore, "jrnrest1" for journal restore at InterSystems IRIS startup or set to abort on DB errors, "shadow" for shadowing, "mirror" for regular mirroring and "mircatchup" for mirror catchup. All but journal restore ("jrnrest" or "sturest") also requires a name (shadow or mirror name). For "shadow", quesiz is also an input for default limit on gmheap, in pages.[HYY2181] Returned parameters: numpref - initial/minimal # of (active) prefetchers (0 = no prefetching) quesiz - size of the dejournal queue, in pages stksiz - size of the dejournal stack, in pages NB: A -1 value for stksiz tells the caller to use its own default. sizmod - a flag indicating whether quesiz or stksiz is also a maximum, used as an argument of $zu(78,50). 2 = quesiz and stksiz are in pages (same as 0) +4 = quesiz is also the maximum size +8 = stksiz is also the maximum size NB: A user-specified quesiz or stksiz is in bytes, whereas we return in pages. numupd - # of updaters rangemax - max # of updates between the foremost and the hindmost updaters maxpref - max # of prefetchers inorder - updates should be applied in order, except for db's listed in ^MIRROR(mirrorname,"APD",db) if any. Note: A user-specified "" value (NOT undefined) is equivalent to -1 here. A user-specified 0 value means NO (for prefetching only) or default algorithm.

StatusExecute​

ClassMethod StatusExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

Returns status of the journaling system.

Example:s rs=##class(%ResultSet).%New("%SYS.Journal.System:Status") s rc=rs.Execute() w rc while rs.Next() { w rs.Data("Main Status"),! h 10 } Here the journaling status of a remote system is retrieved and displayed every 10 seconds. See %RemoteResultSet for details on how to use it.

StatusFetch​

ClassMethod StatusFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

StatusClose​

ClassMethod StatusClose(ByRef qHandle As %Binary) As %Status [ Internal ]

ProgressExecute​

ClassMethod ProgressExecute(ByRef qHandle As %Binary, GetCommitted As %Integer) As %Status [ Internal ]

Returns info on journaling progress Example:s rs=##class(%ResultSet).%New("%SYS.Journal.System:Progress") s rc=rs.Execute() w rc while rs.Next() { w $zdt(rs.Data("TimeStamp"),8),": ",$j(rs.Data("Offset"),10)," ",rs.Data("File Name"),! h 10 } Here the current journal file name and offset are retrieved and displayed every 10 seconds.

ProgressFetch​

ClassMethod ProgressFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal ]

ProgressClose​

ClassMethod ProgressClose(ByRef qHandle As %Binary) As %Status [ Internal ]

SummaryExecute​

ClassMethod SummaryExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

Query returns a summary of the journaling system status.

Example:s rs=##class(%ResultSet).%New("%SYS.Journal.System:Summary") s rc=rs.Execute() w !,rs.GetColumnHeader(1),?40," ",rs.GetColumnHeader(2),! while rs.Next() { w !,rs.Data("Parameter"),?40," ",rs.Data("Value") }

SummaryFetch​

ClassMethod SummaryFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = SummaryExecute ]

SummaryClose​

ClassMethod SummaryClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = SummaryFetch ]