Class Reference
IRIS for UNIX 2018.1.1
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

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)
	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 Properties Methods Queries Indices ForeignKeys Triggers
2 13 23 1


Address ECPSystemID InTransaction JobID Next
NextAddress Prev PrevAddress ProcessID RemoteSystemID
TimeStamp Type TypeName

%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 Count ECPSystemIDGet
GetAddressNear GetPhysicalLocation GetRealPIDSYSinFilter InTransactionGet
JobIDGet NextAddressGet NextGet PIDLookup
PrevAddressGet PrevGet ProcessIDGet RemoteSystemIDGet
Restore TimeStampGet TypeNameGet

%SYS.Journal.Marker %SYS.Journal.SetKillRecord


• 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 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 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 ];
Use RemoteSystemID if you're comparing records to ensure that two identical process IDs refer to the same real process/transaction.
• 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'.
• method ECPSystemIDGet() as %Integer
This is a Get accessor method for the ECPSystemID property.
• 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
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, MirrorDatabaseName As %String
Returns a list of journal records.
Comparable (pseudo-)SQL statement:
  SELECT Columns FROM FileName WHERE Offsets... AND Match(Column)...

Full path of the journal file
(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)
(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)
(Optional) If 1, list records in the reverse order of their addresses.
(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).

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

Copyright © 1997-2018 InterSystems Corporation, Cambridge, MA