Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
		44	3

Methods
%%OIDGet	%AddToSaveSet	%ClassIsLatestVersion	%ClassName
%ConstructClone	%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty
%DispatchMethod	%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty
%Extends	%GetParameter	%IsA	%IsModified
%New	%NormalizeObject	%ObjectModified	%OriginalNamespace
%PackageName	%RemoveFromSaveSet	%SerializeObject	%SetModified
%ValidateObject	ActivateEncryption	DeactivateEncryption	GetAlternateDirectory
GetClusterJournalLog	GetCurrentFile	GetCurrentFileCount	GetCurrentFileName
GetCurrentFileOffset	GetFreeSpace	GetImageJournalInfo	GetJournalFilePrefix
GetLastFileName	GetPrimaryDirectory	GetState	GetStateString
IsDisabled	IsFrozen	IsGettingIOError	IsPaused
OKNoDBEncKeyAtStartup	OKNoDBEncKeyNow	ProgressClose	ProgressExecute
ProgressFetch	RollToNextFile	SetAlternateDirectory	SetJournalFilePrefix
SetPrimaryDirectory	Start	StatusClose	StatusExecute
StatusFetch	Stop	SummaryClose	SummaryExecute
SummaryFetch	SwitchFile	Sync	WhereCommitted

• 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 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 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 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

• 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") }