%SYS.Journal.Record

persistent class %SYS.Journal.Record extends %Library.Persistent

SQL Table Name: %SYS_Journal.Record

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)

  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.

Method Inventory

%OnDetermineClass()
Count()
ECPSystemIDGet()
FetchRows()
GetAddressNear()
GetPhysicalLocation()
GetRealPIDSYSinFilter()
InTransactionGet()
JobIDGet()
NextAddressGet()
NextGet()
PIDLookup()
PrevAddressGet()
PrevGet()
ProcessIDGet()
RemoteSystemIDGet()
Restore()
TimeStampGet()
TypeNameGet()

Parameters

parameter DOMAIN = %Utility;

Default Localization Domain

parameter READONLY = 1;

Inherited description: READONLY = 1 means that objects can be created, opened but not saved or deleted. Tables are projected to SQL as READONLY.

Properties

property Address as %String [ ReadOnly ];

Location of the record in the journal file

Property methods: AddressDisplayToLogical(), AddressGet(), AddressIsValid(), AddressLogicalToDisplay(), AddressLogicalToOdbc(), AddressNormalize()

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.

Property methods: ECPSystemIDDisplayToLogical(), ECPSystemIDIsValid(), ECPSystemIDLogicalToDisplay(), ECPSystemIDNormalize()

property InTransaction as %Integer [ Calculated ];

Whether the record is part of a transaction

Property methods: InTransactionDisplayToLogical(), InTransactionIsValid(), InTransactionLogicalToDisplay(), InTransactionNormalize()

property JobID as %Integer [ Calculated ];

Internal jobid stored with each journal record in the journal file

Property methods: JobIDDisplayToLogical(), JobIDIsValid(), JobIDLogicalToDisplay(), JobIDNormalize()

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 methods: NextAddressDisplayToLogical(), NextAddressIsValid(), NextAddressLogicalToDisplay(), NextAddressNormalize()

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 methods: PrevAddressDisplayToLogical(), PrevAddressIsValid(), PrevAddressLogicalToDisplay(), PrevAddressNormalize()

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 methods: ProcessIDDisplayToLogical(), ProcessIDIsValid(), ProcessIDLogicalToDisplay(), ProcessIDNormalize()

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.

Property methods: RemoteSystemIDDisplayToLogical(), RemoteSystemIDIsValid(), RemoteSystemIDLogicalToDisplay(), RemoteSystemIDNormalize()

property TimeStamp as %TimeStamp [ Calculated ];

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

Property methods: TimeStampDisplayToLogical(), TimeStampIsValid(), TimeStampLogicalToDisplay(), TimeStampNormalize(), TimeStampOdbcToLogical()

property Type as %Library.JournalRecordType [ ReadOnly ];

Type of the record in numeric form

Property methods: TypeDisplayToLogical(), TypeGet(), TypeIsValid(), TypeLogicalToDisplay(), TypeNormalize()

property TypeName as %String [ Calculated ];

Type of the record in string form

Property methods: TypeNameDisplayToLogical(), TypeNameIsValid(), TypeNameLogicalToDisplay(), TypeNameLogicalToOdbc(), TypeNameNormalize()

Methods

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

Inherited description: 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'.

method ECPSystemIDGet() as %Integer

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

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

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

method InTransactionGet() as %Integer

method JobIDGet() as %Integer

method NextAddressGet() as %Integer

method NextGet() as %SYS.Journal.Record

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

method PrevGet() as %SYS.Journal.Record

method ProcessIDGet() as %Integer

method RemoteSystemIDGet() as %Integer

method Restore(Detail As %Integer) as %Status

a place holder

method TimeStampGet() as %TimeStamp

method TypeNameGet() as %String

Queries

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, MirrorDatabaseName 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)

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

Indexes

index (IDKEY on ) [IdKey, Type = key];

Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()