persistent class %SYS.Journal.Record
extends %Persistent
Journal record related API
To retrieve a record, first open the journal file containing the record if it is not already open:
Set jrnforef = ##class(%SYS.Journal.File).%OpenId(FilePath)
where FilePath is the path of the journal file.
Then get the record by specifying its location (
Address) in the journal file
Set jrecoref = jrnforef.GetRecordAt(Address)
or
Set jrecoref = ##class(%SYS.Journal.Record).%OpenId(Address)
Records are polymorphic -- for example, the reference returned above would be one to a
SetKillRecord object if the record is a SET or KILL.
• 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.
• property Address
as %String [ ReadOnly ];
Location of the record in the journal file
• property InTransaction
as %Integer [ Calculated ];
Whether the record is part of a transaction
• property JobID
as %Integer [ Calculated ];
Internal jobid stored with each journal record in the journal file
• property Next
as %SYS.Journal.Record [ Calculated ];
Reference to next record or NULLOREF if this is the last record in the file
• property NextAddress
as %Integer [ Calculated ];
Location of next record or 0 if this is the last record in the file
• property Prev
as %SYS.Journal.Record [ Calculated ];
Reference to previous record or NULLOREF if this is the first record in the file
• property PrevAddress
as %Integer [ Calculated ];
Location of previous record or 0 if this is the first record in the file
• property ProcessID
as %Integer [ Calculated ];
Operating system process id for the process which created the journal record.
This is calculated by taking the jobid stored in the journal record and
looking up the corresponding process id in a translation table maintained by
the system. If the process id cannot be calculated, the jobid with the string
"(jid") appended is returned.
• property RemoteSystemID
as %Integer [ Calculated ];
• property TimeStamp
as %TimeStamp [ Calculated ];
Time stamp of the record (not necessarily the creation time of the record)
• property Type
as %Library.JournalRecordType [ ReadOnly ];
Type of the record in numeric form
• property TypeName
as %String [ Calculated ];
Type of the record in string form
• classmethod %OnDetermineClass(OID As %ObjectIdentity, ByRef Class As %String)
as %Status
This callback method is invoked by the %Open method to
determine the classname of the object specified by oid.
• classmethod Count(File As %String, Sort As %String = "ALL")
as %Status
Provides an analysis of the activity for global records in a journal file.
Records are counted by type and the amount of activity for each global is
calculated as a percentage of the total for that record type.
The output is written to the current device.
Parameters are:
File - Journal file to count (by default the current journal file)
Sort - By default the counts for all types of global journal records
are kept individually. You may have the counts grouped as general SET or KILL
records by entering the 'Sort' parameter as 'GROUP'.
• classmethod GetAddressNear(Offset As %Integer = 0, Before As %Boolean = 0)
as %Integer
Return the address of a valid record that is nearest to and >= (or <= if Before=1) the given offset; 0 if no such a record
• classmethod GetPhysicalLocation(ByRef Offset As %Integer, ByRef FileName As %String)
as %Status
Return the physical location of a record, given by Offset and Filename, in Offset and FileName.
The virtual and physical locations of a record may differ due to a journal switch.
The API assumes a %SYS.Journal.System.Sync() has been issued to commit the journal record in question to disk
• method InTransactionGet()
as %Integer
This is a Get accessor method for the InTransaction property.
• method JobIDGet()
as %Integer
This is a Get accessor method for the JobID property.
• method NextAddressGet()
as %Integer
This is a Get accessor method for the NextAddress property.
• method NextGet()
as %SYS.Journal.Record
This is a Get accessor method for the Next property.
• classmethod PIDLookup(Offset As %String)
as %String
Given an address in the currently open journal file, read the
jobid from the journal record and translate this to an operating
system process id using the jobid->pid translation table. Returns
the corresponding pid or "<jobid>(jid)" if the pid cannot be
determined.
• method PrevAddressGet()
as %Integer
This is a Get accessor method for the PrevAddress property.
• method PrevGet()
as %SYS.Journal.Record
This is a Get accessor method for the Prev property.
• method ProcessIDGet()
as %Integer
This is a Get accessor method for the ProcessID property.
• method RemoteSystemIDGet()
as %Integer
This is a Get accessor method for the RemoteSystemID property.
• method Restore(Detail As %Integer)
as %Status
a place holder
• method TimeStampGet()
as %TimeStamp
This is a Get accessor method for the TimeStamp property.
• method TypeNameGet()
as %String
This is a Get accessor method for the TypeName property.
• query List(FileName As %String, ByRef Columns As %String, ByRef Offsets As %Integer, ReverseOrder As %Boolean = 0, Match As %List = "")
Selects
Address As %Integer, Type As %Library.JournalRecordType, TypeName As %String, PrevAddress As %Integer, NextAddress As %Integer, InTransaction As %Integer, TimeStamp As %TimeStamp, ProcessID As %Integer, RemoteSystemID As %Integer, ClusterSequence As %Integer, DatabaseName As %String, GlobalReference As %String, GlobalNode As %String, NumberOfValues As %Integer, NewValue As %String, OldValue As %String, Collation As %Integer, Bit Position As %Integer, Bit OldLength As %Integer, Marker MID As %Integer, Marker Sequence As %Integer, Marker Text As %String
Returns a list of journal records.
Comparable (pseudo-)SQL statement:
SELECT Columns FROM FileName WHERE Offsets... AND Match(Column)...
Parameters:-
FileName
-
Full path of the journal file
-
Columns
-
(Optional) Names of the selected columns as either a comma-delimited string or an array with column names being the keys.
If unspecified or given as "*", all available columns are returned.
Note: Availability of a column depends on the type of a record and other circumstances. For example, the "OldValue" column applies to only some SET or KILL records (SetKillRecord or derived) -
Offsets
-
(Optional) An array of the addresses of the selected records.
Independently, the top node gives the offset to begin listing records with. When combined with the ReverseOrder parameter, this limits the records to those with Address > Offsets (if ReverseOrder is 0 or not specified) or Address < Offsets (if ReverseOrder is 1) -
ReverseOrder
-
(Optional) If 1, list records in the reverse order of their addresses.
-
Match
-
(Optional) A LIST string to select records whose value in a certain column meets a certain criterion.
The string consists of three elements:-
Column name
-
Operator (e.g., "[", "=", etc.)
-
Value
representing the operation: [Column name] [Operator] [Value] (e.g., Address > 160000).
Examples:
To retrieve all available info about all records in current journal file,
s rs=##class(%ResultSet).%New("%SYS.Journal.Record:List")
s jrnf=##class(%SYS.Journal.System).GetCurrentFileName()
w rs.Execute(jrnf)
w rs.Execute(jrnf,"Address,Type,GlobalNode",160000,1)
To retrieve all available columns of records involving the ^SYS global (but not its subnode),
w rs.Execute(jrnf,,,,$lb("GlobalNode","=","SYS"))
