This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

%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)
  
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.

Property Inventory

Method Inventory

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(), ECPSystemIDGet(), ECPSystemIDIsValid(), ECPSystemIDLogicalToDisplay(), ECPSystemIDNormalize()
property InTransaction as %Integer [ Calculated ];
Whether the record is part of a transaction
Property methods: InTransactionDisplayToLogical(), InTransactionGet(), InTransactionIsValid(), InTransactionLogicalToDisplay(), InTransactionNormalize()
property JobID as %Integer [ Calculated ];
Internal jobid stored with each journal record in the journal file
Property methods: JobIDDisplayToLogical(), JobIDGet(), JobIDIsValid(), JobIDLogicalToDisplay(), JobIDNormalize()
Reference to next record or NULLOREF if this is the last record in the file
Property methods: NextAddressDisplayToLogical(), NextAddressGet(), NextAddressIsValid(), NextAddressLogicalToDisplay(), NextAddressNormalize(), NextGet()
property NextAddress as %Integer [ Calculated ];
Location of next record or 0 if this is the last record in the file
Property methods: NextAddressDisplayToLogical(), NextAddressGet(), NextAddressIsValid(), NextAddressLogicalToDisplay(), NextAddressNormalize()
Reference to previous record or NULLOREF if this is the first record in the file
Property methods: PrevAddressDisplayToLogical(), PrevAddressGet(), PrevAddressIsValid(), PrevAddressLogicalToDisplay(), PrevAddressNormalize(), PrevGet()
property PrevAddress as %Integer [ Calculated ];
Location of previous record or 0 if this is the first record in the file
Property methods: PrevAddressDisplayToLogical(), PrevAddressGet(), 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(), ProcessIDGet(), 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(), RemoteSystemIDGet(), RemoteSystemIDIsValid(), RemoteSystemIDLogicalToDisplay(), RemoteSystemIDNormalize()
property TimeStamp as %TimeStamp [ Calculated ];
Time stamp of the record (not necessarily the creation time of the record)
Property methods: TimeStampDisplayToLogical(), TimeStampGet(), TimeStampIsValid(), TimeStampLogicalToDisplay(), TimeStampNormalize(), TimeStampOdbcToLogical()
property Type as %Library.JournalRecordType [ ReadOnly ];
Type of the record in numeric form
Property methods: TypeDisplayToLogical(), TypeGet(), TypeIsValid(), TypeLogicalToDisplay(), TypeNameDisplayToLogical(), TypeNameGet(), TypeNameIsValid(), TypeNameLogicalToDisplay(), TypeNameLogicalToOdbc(), TypeNameNormalize(), TypeNormalize()
property TypeName as %String [ Calculated ];
Type of the record in string form
Property methods: TypeNameDisplayToLogical(), TypeNameGet(), 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 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:
  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 journal 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"))
  

Indices

index (IDKEY on ) [IdKey, Type = key];
Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods

Subclasses

Feedback