Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%SYS.Journal.System

abstract class %SYS.Journal.System extends %Library.RegisteredObject

Journaling related API

Method Inventory

Methods

classmethod ActivateEncryption(EnableStartup As %Boolean = 1) as %Status
Activate journal encryption such that new updates go to encrypted journal files.
classmethod DeactivateEncryption(DisableStartup As %Boolean = 1) as %Status
Deactivate journal encryption such that new updates go to unencrypted journal files.
classmethod GetAlternateDirectory(ByRef Status As %Status) as %String
Return the path of the secondary journal directory
classmethod GetClusterJournalLog() as %String
Return the path of the cluster journal log
classmethod GetCurrentFile() as %SYS.Journal.File
Return the object reference to current journal file
classmethod GetCurrentFileCount() as %Integer
Return the file count of current journal file
classmethod GetCurrentFileName() as %String
Return the path of current journal file
classmethod GetCurrentFileOffset() as %Integer
Returns the ending offset of the last journal record in current journal file; 0 if journaling is off
classmethod GetFreeSpace() as %Integer
Return the free space available for journal files
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)
classmethod GetJournalFilePrefix() as %String
Return the journal file name prefix
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)
classmethod GetPrimaryDirectory(ByRef Status As %Status) as %String
Return the path of the primary journal directory, which is not necessarily the current journal directory
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)
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.
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)
classmethod IsDisabled(Status As %String = "", ByRef Cause As %String) as %Boolean
TRUE if journaling is disabled system wide
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.
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
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.
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)
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.
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.
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

classmethod SetAlternateDirectory(dir As %String, create As %Boolean) as %String
classmethod SetJournalFilePrefix(prefix As %String, create As %Boolean) as %String
Set the journal file prefix string. This string is prefixed to the mmddyyyy.nnn journal file name when a new journal file is created. Journal file prefixes can be used to distinguish journal files from different Cache instances if it is necessary to store journal files from several instances in the same directory. It is better practice to use separate directories, possibly separate subdirectories of a common directory, for each Cache instance. Changes to the journal file prefix require a Cache restart to become active.
classmethod SetPrimaryDirectory(dir As %String, create As %Boolean) as %Status
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
classmethod Stop() as %Status
Purpose: Stop journaling system wide
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.
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
classmethod Sync() as %Integer
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.

classmethod WhereCommitted() as %Integer
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()

Queries

query Progress()
Selects File Name As %String, File Count As %Integer, Offset As %Integer, Offset Committed As %Integer, TimeStamp As %String
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.
query Status()
Selects Main Status As %String, Cause As %String, Full Status As %String
Returns status of the journaling system.

Example: 

    s rs=##class(%RemoteResultSet).%New("%SYS.Journal.System:Status")
    s rs.UserName="_system"
    s rs.Password="sys"
    s rs.ConnectionString="hostname[port]:%SYS" 
    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.
query Summary()
Selects Parameter As %String, Value As %String
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") }

Inherited Members

Inherited Methods

FeedbackOpens in a new tab