Purge Interval Replication Control (PIRC) is a new replication setting which is designed to prevent old documents which may have been deleted from replicating back into a database after their deletion stubs have been purged. This problem has been encountered by many customers. The most common case occurs when an old version of a NAB (Domino Directory) is brought back online after several months or years. When this occurs, previously deleted person documents, group documents, server documents, and other design elements can replicate back into the environment because the deletion stubs have already been purged. PIRC prevents these documents from replicating back into the environment.

How PIRC Works
PIRC prevents documents from replicating back in two ways. The first is by modifying the ‘since time’ used by the replicator. If the server that is initiating the replication is release 8.5.3 and therefore PIRC-aware, then the algorithm to determine which documents qualify for replication has been changed to use the later of the PIRC date or the Since time contained in the replication history. This prevents the older documents from being replicated. Also, a DDM event is generated showing the number of documents skipped by PIRC.

The second way in which PIRC prevents older documents from replicating in is by stopping the documents from being added to the database via NoteUpdate. This method occurs when a non-PIRC aware server is pushing older documents to the PIRC-aware server. In this case, NoteUpdate code will compare the SequenceTime of the document to the PIRC date. If the document is older, a DDM event will be logged and the document will be rejected. Note that the source server is unaware that the document was rejected. Therefore its logs will show that all documents were successfully replicated. However, the PIRC server will log the server name and the documents that were rejected, thus allowing the administrator to track down old replicas of the database and remove them from the environment.

PIRC keys off the Cutoff date of a database. The cutoff date is the date when purge last ran. Purge is the process which removes deletion stubs from a database. Purge runs at one-third of the purge interval. So if the purge interval is set to 90 days, then a database may have deletion stubs up to 120 days old. Therefore PIRC will use this date to prevent documents older than this date from replicating into the database. If the cutoff date is not set in a database, which happens when replication history is cleared, the current date minus the purge interval is used.

Enabling PIRC
There are three ways to enable PIRC on a database:

1) For an individual database, the property can be set via the Replication Options dialog box under the Space Savings tab. A check box has been added to enable/disable the feature.

2) You can implement PIRC through compact. Compact ‘-PIRC On’ and ‘-PIRC Off’ will toggle the option. This can be used to enable or disable PIRC on multiple databases with one command. Note: This does nothing to existing documents in the database – for example, it will not remove older documents as the “Remove documents not modified in the last N days” replication setting does when the check box is enabled.

3) You can set PIRC through the database options settings in the Administration Client. This also allows an administrator to set PIRC on multiple databases simultaneously.

Considerations Before Enabling PIRC
Before enabling PIRC you must make sure that all the documents you expect to replicate in, have replicated in. The design of PIRC blocks documents older than the cutoff date from replicating into the database. Therefore you must take care that the database has replicated with all the replicas in the environment. This is especially important if some of the replicas are partial.

Overriding PIRC
A replica process NOPIRC switch has been added to the replication task to temporarily overrride the PIRC setting without having to disable it. This is useful if there is ever the need to synchronize two replicas of a database but you do not want to expose the database to other replicas in the environment. The ‘-NOPIRC’ switch tells the replicator to override PIRC. Note that you must be an administrator of the server or be allowed to create new replicas on the server in order to use the NOPIRC switch. This includes the server in the case of a PUSH. Also the NOPIRC switch overrides the replication history by setting the since time to zero. This way when the NOPIRC switch is used, a full replication is done between the two databases bringing them into sync without exposing either databases to other replicas in the environment.

Design/Replace Considerations
With PIRC enabled on a database, special care is needed in order to push out design changes, because templates tend to contain design elements that do not change over a long period of time. Once these design elements are older than the Purge Interval, PIRC would block them from replicating. In order to avoid this problem, the Design Modification TimeDate was added to the database. This time/date is updated in the database whenever design refresh or replace is run, and it actually modifies one or more design elements. PIRC compares this time to the PIRC time and if it is newer, PIRC will allow all non-data notes to replicate into the destination database. This will allow a new design or newly modified design elements to replicate out through the environment even if PIRC is enabled on the databases.

DDM Events and PIRC
When PIRC blocks a note that is being pushed from a non-PIRC server, a Replication DDM event is created.

"PIRC Warning: Replicator skipped <x> data document(s) in <database name> from <server name>"

PIRC will also generate a DDM even when the replicator skips documents that qualified in the search formula. This is an indication that another replica of the database is attempting to push old data into the database. The following events will be seen in DDM under Replication:

"PIRC Warning: Replicator skipped <x> data document(s) in <database name> from <server name>"
"PIRC Warning: Replicator skipped <x> non-data document(s) in <database name> from <server name>"

A replication DDM event will also be logged when someone issues a replication command with the -n, no pirc, switch.

"PIRC override for DB <database name>"

Fixup Changes Related to PIRC

Changes were made to fixup to help with the scenario where a corrupted document is found and deleted with no deletion stub. This is the common practice of fixup in order to allow a good copy of this note to replicate in from another replica. Along with deleting the document, fixup would also clear the replication history to allow a full search to occur in order to find these documents on next replication. With a PIRC enabled database, this procedure would no longer work if the documents modified time is older than the PIRC interval.

In order to solve this problem fixup was modified to no longer clear the replication history in this case. Fixup will now put the UNID of the deleted document onto a list contained in a special object in the database. Then when the next scheduled replication occurs, if this list exists, these documents are added to the list of documents to replicate, allowing replication to recover these deleted documents while not having to clear the history. PIRC will also allow these documents to replicate into the database even if they are older than the PIRC date. A DDM event is generated when a document is deleted from a database and its UNID is added to this list. UNID’s will remain on this list only until the are replicated back in or they have been on the list for longer than the PIRC interval. In either case, when they are removed from the list another DDM event is generated.

New DDM Messages related to fixup:

"Warning: Fixup purged corrupt document UNID (:) from testserver/IBM"

"Warning: Replication restored document UNID (:) from testserver/IBM"

"Warning: Replication did not restore corrupt document, time expired, UNID (:) from testserver/IBM"

Debugging PIRC

If you require more information about exactly what PIRC is doing, you can set the DEBUG_REPL_PIRC notes.ini setting. Setting it to a value of 1 will display information about the PIRC date and summary information of the notes that PIRC blocked. Setting it to a value of 2 or greater will display information about the individual notes that PIRC is blocking. It displays whether the notes are data or non-data or if they are deletions as well as their UNIDs..

Common Questions Related to PIRC

Q. How do I protect a database from replicating in documents that were deleted years ago when an old server or an old copy of a database is brought online?

A. Enable PIRC on all replicas of the database in your environment you want to protect.

Q. I am pushing a database from an 8.52 server to an 8.53 server where the database has PIRC enabled. I see the error “Error Invalid Document” on the server’s log.

A. With PIRC enabled on the destination server, documents older than the PIRC data will be rejected and a DDM event will be logged. The error is returned to the server but it is an error that the replicator will ignore. So the replicator will continue to replicate the entire database. Note that this error is only displayed on the server console when the notes.ini parameter DEBUG_REPL is set.

Q. I want to enable PIRC on several databases on a server. What is the best way to do that?

A. There are two ways to do this. You can either use the administration client and set the option using the advanced options tool, or create an indirect file containing the list of databases on which you want to enable PIRC. Then use the compact -PIRC on command and pass it the indirect file.

Q, How do I easily tell which databases on a server are PIRC enabled?

A. You can use the ‘show directory’ command at the server console. A column has been added to the output for PIRC. Also the ‘show directory -pirconly’ command will list only PIRC-enabled databases.

Related Technotes

http://www-01.ibm.com/support/docview.wss?rs=0&uid=swg21098733

http://www-01.ibm.com/support/docview.wss?rs=475&context=SSKTWP&context=SSKTMJ&dc=DB520&q1=documents+and+replication+and+old&uid=swg21225071&loc=en_US&cs=utf-8&lang=en