Filter Journal Records Using ^ZJRNFILT

InterSystems provides a journal filter mechanism to manipulate the journal file. The journal filter program is a user-written routine called ^ZJRNFILT whose format is shown below. This is called by the InterSystems IRIS journal restore program, ^JRNRESTO, and ensures that only selected records are restored. Create the ^ZJRNFILT routine using the following format:

ZJRNFILT(jidsys,dir,glo,type,restmode,addr,time)

Argument	Type	Description
jidsys	input	Two components separated by a comma: jid (job ID) and remsysid (for ECP only). Pass jidsys to the %SYS.Journal.Record.GetRealPIDSYSinFilterOpens in a new tab method (as shown in the “^ZJRNFILT Examples” below) to identify the PID (process ID) that generated the journal.
dir	input	Full pathname of the directory containing the IRIS.DAT file to be restored, as specified in the journal record.
glo	input	Global in journal record.
type	input	Command type in journal record (S for Set, K for Kill).
addr	input	Address of the journal record.
time	input	Time stamp of the record (in $horolog format). This is the time the journal buffer is created, not when the Set or Kill operation occurs, so it represents the earliest this particular operation could have happened.
restmode	output	0 - do not restore record. 1 - restore record.

^ZJRNFILT Considerations

Consider the following when using ^ZJRNFILT:

If the startup routine (^STU) calls ^JRNRESTO, it does not call the filter routine under any circumstances.
Journal restore only calls the journal filter (^ZJRNFILT) if it exists. If it does exist, the restore procedure prompts you to confirm the use of the filter in the restore process.
If you answer yes to use the journal filter, for every record in the journal file to restore, the routine calls the journal filter ^ZJRNFILT with the indicated input arguments to determine whether to restore the current record.
You can use any logic in your ^ZJRNFILT routine to determine whether or not to restore the record. Return confirmation through the output restmode argument.
If you are using the directory name, dir, in the ^ZJRNFILT routine logic, specify the full directory pathname.
The entire global reference is passed to ^ZJRNFILT for use in program logic.
When the journal restore process completes, it prompts you to confirm whether to rename the ^ZJRNFILT routine or delete it. If you choose to rename the filter, the utility renames it ^XJRNFILT and deletes the original ^ZJRNFILT.
The restore process aborts with an appropriate error message if any errors occur in the ^ZJRNFILT routine.

^ZJRNFILT Examples

Two globals, ^ABC and ^XYZ, are journaled. While journaling is turned on, the following code is executed, and the journal file records the Set and Kill operations for these globals:

 For I=1:1:500 Set ^ABC(I)=""
 For I=1:1:500 Set ^XYZ(I)=""
 For I=1:1:100 Kill ^ABC(I)

To restore all records for ^ABC only, the ^ZJRNFILT routine looks like this:

ZJRNFILT(jidsys,dir,glo,type,restmode,addr,time)    /*Filter*/
 Set restmode=1                                  /*Return 1 for restore*/
 If glo["XYZ" Set restmode=0                     /*except when it is ^XYZ*/
 Quit
 ;

To restore all records except the kill on ^ABC, the ^ZJRNFILT routine looks like this:

ZJRNFILT(jidsys,dir,glo,type,restmode,addr,time)    /*Filter*/
 Set restmode=1                                  /*Return 1 for restore*/
 If glo["^ABC",type="K" Set restmode=0           /*except if a kill on ^ABC*/
 Quit
 ;

In some cases (for example, when the jid is a PID or on a mirror member), remsysid is not the actual ECP system ID. In these cases, use the %SYS.Journal.Record.GetRealPIDSYSinFilterOpens in a new tab method to return the real ECP system ID as well as the real PID.
To pull the real PID (and ECP system PID) in a filter, the ^ZJRNFILT routine looks like this:
```
ZJRNFILT(jidsys,dir,glo,type,restmode,addr,time) ;
 SET restmode=0 ;test only
 SET pid=##class(%SYS.Journal.Record).GetRealPIDSYSinFilter(jidsys,.ecpsysid)
 DO ##class(%SYS.System).WriteToConsoleLog($SELECT(pid="":"jid="_+jidsys,1:"pid="_pid)_",ecpsysid="_ecpsysid)
 QUIT
```

To restore all records after a specific time, the ^ZJRNFILT routine looks like this:

ZJRNFILT(jidsys,dir,glo,type,restmode,addr,time) ;
 New zdh 
 Set zdh=$zdatetimeh("08/14/2015 14:18:31") ;in $H format as variable 'time'
 If time>zdh Set restmode=1 Quit
 If time<zdh Set restmode=0 Quit
 If $p(time,",",2)<$p(zdh,",",2) {
  Set restmode=0
 } Else {
    Set restmode=1
 }
 Quit

Restoring Mirror Journal Files