Class Reference
%SYS.Journal.File
Server:irisdocs1
Instance:IRISLATEST
User:UnknownUser
 
-
  [ENSLIB] >  [%SYS] >  [Journal] >  [File]
Private  Storage

persistent class %SYS.Journal.File extends %Persistent

Journal file related API

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
2 8 56 6


Summary

Properties
ClusterStartTime ClusterStartTime0 End FirstRecord
LastMarker LastRecord Name

Methods
%AddToSaveSet %AddToSyncSet %BuildIndices %CheckConstraints
%CheckConstraintsForExtent %ClassIsLatestVersion %ClassName %ComposeOid
%ConstructClone %Delete %DeleteExtent %DeleteId
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Exists
%ExistsId %Extends %GUID %GUIDSet
%GetLock %GetParameter %GetSwizzleObject %Id
%IsA %IsModified %IsNull %KillExtent
%LockExtent %LockId %New %NormalizeObject
%ObjectIsNull %ObjectModified %Oid %OnBeforeAddToSync
%OnDetermineClass %Open %OpenId %OriginalNamespace
%PackageName %PurgeIndices %Reload %RemoveFromSaveSet
%ResolveConcurrencyConflict %RollBack %Save %SaveDirect
%SerializeObject %SetModified %SortBegin %SortEnd
%SyncObjectIn %SyncTransport %UnlockExtent %UnlockId
%ValidateIndices %ValidateObject CheckIntegrity ClusterStartTime0Get
ClusterStartTimeGet EndGet FirstRecordGet GetGUID
GetMaxSize GetMirrorGUID GetNext GetPrev
GetReason GetRecordAfter GetRecordAt GetSystemGUID
IsValidJournal LastEncrypted LastMarkerGet LastRecordGet
Open Purge PurgeAll PurgeOne
RequiredForClusterRecovery RequiredForRecovery RequiredForRollback Restore
RestorePIDList Summary TranslateReason Use


Parameters

• parameter DOMAIN = "%Utility";
Default Localization Domain
• parameter READONLY = 1;
READONLY = 1 means that objects can be created, opened but not saved or deleted. Tables are projected to SQL as READONLY.

Properties

• property ClusterStartTime as %String [ Calculated ];
Cluster start time in %TimeStamp format or "" if not a cluster journal file
• property ClusterStartTime0 as %Integer [ Calculated ];
Cluster start time in time(0) format (i.e., # of seconds since the Epoch) or 0 if not a cluster journal file
• property End as %Integer [ Calculated ];
The end of the last valid record in the journal file (applicable to open file only)
• property FirstRecord as %SYS.Journal.Record [ Calculated ];
Object reference to the first record in the journal file (applicable to open file only)
• property LastMarker as %SYS.Journal.Marker [ Calculated ];
Object reference to the last marker record in the journal file (applicable to open file only)
• property LastRecord as %SYS.Journal.Record [ Calculated ];
Object reference to the last record in the journal file (applicable to open file only)
• property Name as %SysPath [ ReadOnly ];
Path of the journal file

Methods

• classmethod CheckIntegrity(ByRef jrnlist As %String, Detail As %Integer = 0, ByRef SrcDirs As %String, quietly As %Integer = 1) as %Status
Purpose: Check integrity of the journal file(s)
jrnlist can be either a file path or, if passed by reference, a number-indexed array of file paths, e.g.:
jrnlist(1)=path1, jrnlist(2)=path2, etc.
The file paths in the array should be in chronicle order, that is, path1 and path2 are assumed to have been created consecutively in the example above. If it is determined that the files in the given array do not meet that criterion, a single value 0 is returned (for "Invalid Parameter") and the top node of the array is set to the number index of the offending path.
Detail: If 1, scan each given journal file forward to locate the last record and verify it is the last record to be expected.
If 2, verify values stored in each record are retrievable.
If SrcDirs is set to 1 and passed by reference, the database directories used in the specified journal file(s) will be stored in SrcDirs array upon return.
• method ClusterStartTime0Get() as %Integer
This is a Get accessor method for the ClusterStartTime0 property.
• method ClusterStartTimeGet() as %String
This is a Get accessor method for the ClusterStartTime property.
• method EndGet() as %Integer
This is a Get accessor method for the End property.
• method FirstRecordGet() as %SYS.Journal.Record
This is a Get accessor method for the FirstRecord property.
• classmethod GetGUID(FileName As %String) as %String
Get the GUID assigned to the given journal file.
• classmethod GetMaxSize(FileName As %String) as %Integer
Purpose: Get max size of a journal file
• classmethod GetMirrorGUID(FileName As %String) as %String
• classmethod GetNext(FileName As %String, ByRef NextFileName As %String, MirOnly As %Boolean = 0, MirrorSetName As %String = "") as %Status
Purpose: Get journal file following the given journal file

• classmethod GetPrev(FileName As %String = "", ByRef PrevFileName As %String, InSession As %Boolean, MirOnly As %Boolean = 0, MirrorSetName As %String = "") as %Status
Purpose: Get journal file prior to the given journal file

InSession: whether to limit the search within a journal session (default=NO)

• classmethod GetReason(File As %SysPath) as %String
Return the reason for the creation of the given journal file (File) in string form
• method GetRecordAfter(Address As %Integer) as %SYS.Journal.Record
Return the object reference to the record after the given journal location (Address)
• method GetRecordAt(Address As %Integer) as %SYS.Journal.Record
Return the object reference to the record at the given journal location (Address)
• classmethod GetSystemGUID(FileName As %String) as %String
Get the GUID assigned to this system in the mirror configuration file.
This is used to help people identify which system created the journal file.
Since this comes from the config file, it's possible that this can change over time but its not supposed to.
• classmethod IsValidJournal(FileName As %String) as %Status
TRUE if the given FileName is a journal file
• classmethod LastEncrypted(OldestFile As %String = "", csn As %Integer = -1) as %String
Return the path of the last encrypted file no older than OldestFile if given
• method LastMarkerGet() as %SYS.Journal.Record
This is a Get accessor method for the LastMarker property.
• method LastRecordGet() as %SYS.Journal.Record
This is a Get accessor method for the LastRecord property.
• method Open(FileName As %String) as %Status
To open a journal file for record retrieval
• classmethod Purge(NDaysOld As %Integer, NBackupsOld As %Integer) as %Status
Purpose: Purge old journal files based on criteria given in number of days or backups, taking care not to purge files required for transaction rollbacks or crash recovery.

Parameters:

  • NDaysOld: journal files must be at least this # of days old to be purged
  • NBackupsOld: journal files must be older than this # of successive successful backups to be purged
If both parameters are specified, only one criterion has to be met to qualify a journal file for purging (subject to the restriction about rollback and crash recovery).
Note: It is the completion date, rather than the creation date, of a file that must meet the date criterion if specified. Thus, a file may not be OK to purge even though the date in its name appears to meet the date criterion.
• classmethod PurgeAll() as %Status
Purge all journal files except those required for transaction rollbacks or crash recovery.
Warning: Post-backup journal files are not necessarily preserved.
• classmethod PurgeOne(FilePath As %String, PurgeTimeH As %String, LogOnly As %Integer = 0) as %Status
Purpose: Purge the journal file with the given name

Warning: This method does NOT check for open transactions before deleting the journal file.

FilePath: the full path of the journal file to purge
PurgeTimeH: Time of purging in $H format
LogOnly: if 1, skip purging and log the purged file only. Default = 0

• classmethod RequiredForClusterRecovery(ByRef FileName As %String, ByRef FileCount As %Integer, SkipSelf As %Boolean = 0) as %Status
Return the path of the oldest journal file on each node that is required for cluster recovery, which includes rolling forward and back transactions.
FileName = # of nodes where journal recovery is required
FileName(csn) = the path of the oldest journal file on node <#csn>
If SkipSelf = 1, skip the node where the method is called (local node is covered by RequiredForRecovery()
• classmethod RequiredForRecovery(ByRef FileName As %String, ByRef FileCount As %Integer) as %Status
Return the name of the oldest journal file required for crash recovery, which includes rolling forward and backward transactions.
FileName="" if journaling is disabled, meaning that none is required, as transactions cannot be rolled forward or backward from a pre-disabling file
• classmethod RequiredForRollback(ByRef FileName As %String, ByRef FileCount As %Integer) as %Status
Return the path of the oldest journal file containing open transactions.
FileName: the oldest file containing open transactions or current journal file
FileCount: the file counter value assigned to the file
• classmethod Restore(FileName As %String, Detail As %Integer = 0) as %Status
Purpose: (virtually) restore the journal
• classmethod RestorePIDList(FileName As %String) as %Status
Purpose: Regenerate the jobid->PID translation table based on records stored in the specified journal file
• classmethod Summary(FilePath As %String, ByRef DataFields As %String) as %Status

FileCount: the file counter value assigned to the file
• classmethod TranslateReason(reason As %Integer = 0) as %String
Translate the numeric reason for the creation of a new journal file to string form
• method Use() as %Integer
To use an open journal file for record retrieval (necessary when you have multiple journal file instances open at the same time and need to switch from one file to another).

Queries

• query ByTimeReverseOrder(FileName As %String)
Selects Name As %String, Size As %Integer, Creation Time As %TimeStamp, Reason As %String
Returns journal file names and file sizes in the reverse order of time (i.e., latest file first)
• query ClusterList(FileName As %String = "", TimeOrder As %Boolean = 0, CSN As %Integer = -1)
Selects Name As %String, Size As %Integer, Cluster Start Time As %TimeStamp, First Sequence As %Integer, Last Sequence As %Integer, Cluster System Number As %Integer, Reason As %String, Creation Time As %TimeStamp, Cluster Start Time UTC As %Integer
Information on cluster journal files
By default, files are listed in reverse order of time, unless TimeOrder = 1
If FileName is specified, files are listed until FileName is reached (depend on TimeOrder)
If CSN is given, only files belong to the node are listed.
• query DatabaseList(FilePath As %String)
Selects sfn As %Integer, Database Path or Alias As %String
Returns sfn's and paths/names of databases in a journal file
• query MirrorByTimeReverseOrder(FileName As %String, MirrorSetName As %String)
Selects Name As %String, Size As %Integer, Creation Time As %TimeStamp, Reason As %String
• query Purgeable(DaysToKeep As %Integer)
Selects FilePath As %String, MirrorName As %String
Returns paths of journal files (along with their mirror names if any) that are eligible for purging based on the default or given criteria.
DaysToKeep: How many days of journal files to keep. Use default (current system setting) if left unspecified. If 0, none is purgeable; if <0, all files are purgeable except those required for transaction rollback and crash recovery.
• query Search(String As %String, FileName As %String, Offset As %Integer, Backward As %Boolean)
Selects Offset As %Integer
Returns addresses of records in a given journal file that match a given string


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.