@PushAndReplace

This @Function provides a special one-way replicator with additional replace logic. It was created for a customer-specific project requirement and is not intended as a replacement for classic Domino replication.
It is intended for special cases in which documents must be transferred in a controlled way from a source database to a target database, while specific field contents in the target document are adjusted using key/replace lists.

The function replicates documents from the database referenced by FROMDBHANDLE1 to the database referenced by TODBHANDLE2.
Replication is performed only in the direction from FROMDBHANDLE1 to TODBHANDLE2. Only documents that match the Notes-compatible selection formula FORMULA3 and belong to the document classes specified in NOTECLASSES5 are processed.
The databases do not have to be replicas of each other.
After a document has been replicated to the target database, the created or updated document in the target database is modified using the specified key, replace, target, and default lists.

The lists
TEXTLISTActKey,
TEXTLISTKeyFieldName,
TEXTLISTReplaceFieldName,
TEXTLISTTargetFieldName,
FNLISTTargetFieldFlags,
FNLISTOperationFlags,
TEXTLISTDefaultFieldName, and
TEXTLISTDefaultValue

belong together by position. This means that the elements at the same position in these lists form one replace rule.

For each of these replace rules, the following logic is applied to the replicated target document:
1. The name of a field is taken from TEXTLISTKeyFieldName. This field must exist in the current target document as TEXT or TEXTLIST. The corresponding key from TEXTLISTActKey is searched for in this field.
2. If the key is found, the element at the same list position is read from the field whose name is taken from TEXTLISTReplaceFieldName.
3. The value determined in step 2 is written to the field whose name is taken from TEXTLISTTargetFieldName. The field flags for this target field are taken from FNLISTTargetFieldFlags.

If the key is not found, a default value is used.
First, the current target document is checked for a field whose name is taken from TEXTLISTDefaultFieldName. If this field exists and has the data type TEXT or TEXTLIST, its content is used as the replacement value.
If this field does not exist, the corresponding value from TEXTLISTDefaultValue is used instead.
FNLISTOperationFlags can be used to control whether only the default text, only the default field, or automatically the default field first and then the default text should be used.

After all replace rules have been applied successfully, helper fields are removed from the target document.
First, a list of field names is read from the field whose name is specified by TEXTRemoveFieldNamesFieldName. These fields are removed from the current target document.
Then all fields whose names are specified in TEXTLISTRemoveFieldNames are also removed from the current target document.
If an error occurs during this replace and cleanup logic, the affected document is not replicated to the database referenced by TODBHANDLE2. In this case, the fourth element of the optional error list FNLISTERROR7 is incremented by one.

In case of a replication conflict, the document in the database referenced by TODBHANDLE2 is always the conflict loser.

The function returns an FNLIST containing the replication result:
Element 1: number of updated documents in TODBHANDLE2
Element 2: number of newly created documents in TODBHANDLE2
Element 3: number of deleted documents in TODBHANDLE2

FN4:
Bit   HEX   Meaning
01   0001   Lesen
02   0002   Schreiben
03   0004   Modify
04   0008   Delete

Note:
When replication uses asymmetric rights assignments, behavior may occur that appears contradictory at first glance.
Example: Database A is allowed to replicate documents to database B. However, database B does not have delete rights in database A.
If a document is first replicated from A to B and then deleted in B, a deletion stub is created in B. This deletion stub remains in the database until the CutOffTD; see also @GetDBReplicaInfo.
Because B does not have delete rights in A, the deletion is not replicated from B to A. The original document therefore still remains in A.
However, as long as the deletion stub exists in B, the document that still exists in A is also not replicated again from A to B. For the replication logic, the document in B is still considered deleted during this period.
Only after the deletion stub in B has been removed after the CutOffTD has expired can the document be transferred from A to B again during a later replication. This can make it appear as if the document suddenly reappears in B.
This behavior corresponds to the behavior of the Domino Replicator when replication rights are assigned asymmetrically.

NOTECLASSES5:
DEC   BIT   Meaning
00000   XX   No Notes   no documents
00001   01   Documents   data documents
00002   02   Policy Note   About-database document
00004   03   Form Note   form design documents
00008   04   View Note   view design documents
00016   05   Icon Note   icon document
00032   06   Design Collection Note   view documents
00064   07   ACL Info Note   ACL info document
00128   08   Help-Index-Note   
00256   09   Help Note   help database document
00512   10   Filter Note   macro design documents
01024   11   Field Note   field design documents
02048   12   Replication Note   replication documents
04096   13   Private_Design   private design documents

32768   16   Default Note of Each   the default document of each

32767   01-15   Notes   all documents
32766   02-15   All Non-Document Notes   all non-data documents

To specify multiple document classes, add the values of the relevant classes or build them using @BitVektor.

FNREPLICATIONFLAGS6:
Bit   HEX   Meaning
01   0001   Localize links (Doc; View; DB) in databases with different replica IDs.

FNLISTERROR7:
When the optional return parameter FNLISTERROR7, is used, error statistics are returned in it.

Element   Meaning
1   Error UpdateCount TODBHANDLE2
2   Error CreateCount TODBHANDLE2
3   Error DeleteCount TODBHANDLE2
4   Error Replacer TODBHANDLE2

FNLISTOperationFlags:
DEC   BIT   Meaning
00001   01   Use only DefaultText *
00002   02   Use only DefaultField *

* If none of this bits is set: Use DefaultField if possible otherwise use DefaultText

FNLISTTargetFieldFlags:
DEC   BIT   Meaning
0001   01   SIGN
0002   02   SEAL
0004   03   SUMMARY
0008   04   
0016   05   SEALED
0032   06   READ/WRITE-ACCESS
0064   07   NAMES
0128   08   
0256   09   PLACEHOLDER
0512   10   PROTECTED
1024   11   READ-ACCESS

To specify multiple field flags, add the values.

Example: @PushAndReplace(FROMDBHANDLE1;TODBHANDLE2;FORMULA3;FN4;NOTECLASSES5;FNREPLICATIONFLAGS6;FNLISTERROR7;TEXTLISTActKey;TEXTLISTKeyFieldName;TEXTLISTReplaceFieldName;TEXTLISTTargetFieldName;FNLISTTargetFieldFlags;FNLISTOperationFlags;TEXTLISTDefaultFieldName;TEXTLISTDefaultValue;TEXTRemoveFieldNamesFieldName;TEXTLISTRemoveFieldNames)

FROMDBHANDLE1:=@OpenDB("REPL1.NSF");
TODBHANDLE2:=@OpenDB("REPL2.NSF");
FORMULA3:="SELECT @All";
FN4:=@BitVektor(1:2:3:4);
NOTECLASSES5:=1;
FNREPLICATIONFLAGS6:=1;
TEXTLISTActKey:="Key1":"Key3";
TEXTLISTKeyFieldName:="KeyList":"KeyList";
TEXTLISTReplaceFieldName:=ReplaceList":"ReplaceList";
TEXTLISTTargetFieldName:="Target1":"Target2";
FNLISTTargetFieldFlags:=1092:100;
FNLISTOperationFlags:=0:0;
TEXTLISTDefaultFieldName:="DefaultFieldName1":"DefaultFieldName2";
TEXTLISTDefaultValue:="DefaultValue Key1":"DefaultValue Key2";
TEXTRemoveFieldNamesFieldName:="RemoveFieldsList";
TEXTLISTRemoveFieldNames:="";
Ret:=@PushAndReplace(FROMDBHANDLE1;TODBHANDLE2;FORMULA3;FN4;NOTECLASSES5;FNREPLICATIONFLAGS6;FNLISTERROR7;TEXTLISTActKey;TEXTLISTKeyFieldName;TEXTLISTReplaceFieldName;TEXTLISTTargetFieldName;FNLISTTargetFieldFlags;FNLISTOperationFlags;TEXTLISTDefaultFieldName;TEXTLISTDefaultValue;TEXTRemoveFieldNamesFieldName;TEXTLISTRemoveFieldNames);
@LogReport(Ret;3);
@LogReport(FNLISTERROR7;3);

TODBHANDLE2:=@CloseDB(TODBHANDLE2);
FROMDBHANDLE1:=@CloseDB(FROMDBHANDLE1);

The documents from the DB with the DBHANDLE FROMDBHANDLE1 are replicated into the DB with the DBHANDLE TODBHANDLE2 and modified.

1. Example of a document and its modification:

Document in DB1:
Field name   Data type   Field flags   Content (list separator semicolon)
KeyList   TEXTLIST   4   Key1;Key2;Key3
ReplaceList   TEXTLIST   4   User1;User2;User3
RemoveFieldsList   TEXTLIST   4   KeyList;ReplaceList;RemoveFieldsList
Form   TEXT   4   Test

replicated (and modified) document in DB2:

Field name   Data type   Field flags   Content (list separator semicolon)
Target1   TEXT   1092   User1
Target2   TEXT   100   User3
Form   TEXT   4   Test

2. Example of a document and its modification:

Document in DB1:
Field name   Data type   Field flags   Content (list separator semicolon)
KeyList   TEXTLIST   4   Key2;Key3;Key4
ReplaceList   TEXTLIST   4   User2;User3;User4
DefaultFieldName1   TEXT   4   DefaultUser1
RemoveFieldsList   TEXTLIST   4   KeyList;ReplaceList;RemoveFieldsList;DefaultFieldName1
Form   TEXT   4   Test

replicated (and modified) document in DB2:

Field name   Data type   Field flags   Content (list separator semicolon)
Target1   TEXT   1092   DefaultUser1
Target2   TEXT   100   User3
Form   TEXT   4   Test

3. Example of a document and its modification:

Document in DB1:
Field name   Data type   Field flags   Content (list separator semicolon)
KeyList   TEXTLIST   4   Key2;Key3;Key4
ReplaceList   TEXTLIST   4   User2;User3;User4
RemoveFieldsList   TEXTLIST   4   KeyList;ReplaceList;RemoveFieldsList
Form   TEXT   4   Test

replicated (and modified) document in DB2:

Field name   Data type   Field flags   Content (list separator semicolon)
Target1   TEXT   1092   DefaultValue Key1
Target2   TEXT   100   User3
Form   TEXT   4   Test

Note on these example documents:
Fields that are not required to understand the replace logic ($UpdatedBy, $Revisions, etc.) are not listed.

Note : This text was machine-translated and may contain inaccuracies.