%SYS.Journal.Record

Class %SYS.Journal.Record Extends %Persistent [ StorageStrategy = JournalRecordStorage, System = 4 ]

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.

Parameters

READONLY

Parameter READONLY = 1;

DOMAIN

Parameter DOMAIN = "%Utility";

Default Localization Domain

Properties

Address

Property Address As %String [ ReadOnly ];

Location of the record in the journal file

Type

Property Type As %Library.JournalRecordType [ ReadOnly ];

Type of the record in numeric form

TypeName

Property TypeName As %String [ Calculated ];

Type of the record in string form

Prev

Property Prev As %SYS.Journal.Record [ Calculated ];

Reference to previous record or NULLOREF if this is the first record in the file

Next

Property Next As %SYS.Journal.Record [ Calculated ];

Reference to next record or NULLOREF if this is the last record in the file

PrevAddress

Property PrevAddress As %Integer [ Calculated ];

Location of previous record or 0 if this is the first record in the file

NextAddress

Property NextAddress As %Integer [ Calculated ];

Location of next record or 0 if this is the last record in the file

TimeStamp

Property TimeStamp As %TimeStamp [ Calculated ];

Time stamp of the record (not necessarily the creation time of the record)

InTransaction

Property InTransaction As %Integer [ Calculated ];

Whether the record is part of a transaction

ProcessID

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.

JobID

Property JobID As %Integer [ Calculated ];

Internal jobid stored with each journal record in the journal file

RemoteSystemID

Property RemoteSystemID As %Integer [ Calculated ];

Use RemoteSystemID if you're comparing records to ensure that two identical process IDs refer to the same real process/transaction.

ECPSystemID

Property ECPSystemID As %Integer [ Calculated ];

ECPSystemID is RemoteSystemID with the top bits masked off.
Use ECPSystemID if the only thing of interest is whether it came from an ECP client, etc.

Methods

%OnDetermineClass

ClassMethod %OnDetermineClass(OID As %ObjectIdentity, ByRef Class As %String) As %Status

PIDLookup

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 "(jid)" if the pid cannot be determined.

%LoadData

Method %LoadData(Offset As %String, flag As %Boolean) As %Status [ Private ]

Count

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'.

TypeNameGet

Method TypeNameGet() As %String

PrevAddressGet

Method PrevAddressGet() As %Integer [ CodeMode = expression ]

NextAddressGet

Method NextAddressGet() As %Integer [ CodeMode = expression ]

PrevGet

Method PrevGet() As %SYS.Journal.Record

NextGet

Method NextGet() As %SYS.Journal.Record

GetAddressNear

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

GetPhysicalLocation

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

InTransactionGet

Method InTransactionGet() As %Integer

ProcessIDGet

Method ProcessIDGet() As %Integer

JobIDGet

Method JobIDGet() As %Integer

RemoteSystemIDGet

Method RemoteSystemIDGet() As %Integer

ECPSystemIDGet

Method ECPSystemIDGet() As %Integer

TimeStampGet

Method TimeStampGet() As %TimeStamp

Restore

Method Restore(Detail As %Integer) As %Status

a place holder

Fetch

Method Fetch(ByRef Row As %List, ByRef Columns As %String, Match As %List = "") As %Boolean [ Internal, PublicList = (col, match, Row, Columns) ]

ListExecute

ClassMethod ListExecute(ByRef qHandle As %Binary, FileName As %String, ByRef Columns As %String, ByRef Offsets As %Integer, ReverseOrder As %Boolean = 0, Match As %List = "") As %Status [ Internal ]

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:

1. Column name
2. Operator (e.g., "[", "=", etc.)
3. 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)To retrieve selected columns of the records located before or at file offset 160000 (i.e., Address ≤ 160000),w rs.Execute(jrnf,"Address,Type,GlobalNode",160000,1)Note that while the columns "Address" and "Type" are available for all records, the "GlobalNode" column is available for SET or KILL records (of class type SetKillRecord or its derived classes) only.

To retrieve all available columns of records involving the ^SYS global (but not its subnode),w rs.Execute(jrnf,,,,$lb("GlobalNode","=","SYS"))

FetchRows

ClassMethod FetchRows(ByRef qHandle As %Binary, FetchCount As %Integer = 0, ByRef RowSet As %List, ByRef AtEnd As %Integer) As %Status

ListFetch

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

ZUGlobalNodeGet

ClassMethod ZUGlobalNodeGet(offset As %Integer) As %String [ Internal ]

Utility classmethod for ZUGetAttr, duplicate of SetKillRecord class GlobalNodeGet method (not a class method)

ZUFetch

ClassMethod ZUFetch(ByRef qHandle As %Binary, offset As %Integer, ByRef Row As %List) As %Boolean [ Internal ]

Utility classmethod for ListFetch: iterate over journal records to find the next one satisfying the matching criteria

ListClose

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

GetRealPIDSYSinFilter

ClassMethod GetRealPIDSYSinFilter(jidsys As %String, ByRef ecpsysid As %Integer) As %String

[For use in a journal restore filter or shadow filter (^ZJRNFILT) only] Given a comma-delimited string of jid (job id) and remsysid that is passed to the user-specified filter, return the real pid (if available) and ECP system id (if any).

• jidsys = jid,remsysid
• ecpsysid = a real ECP system ID
• return: a real PID or ""