@PushAndReplace

Diese @Function stellt einen speziellen One-Way-Replikator mit zusätzlicher Replace-Logik bereit. Sie ist aus einer kundenprojektspezifischen Anforderung entstanden und ist nicht als Ersatz für die klassische Domino-Replikation gedacht. Sie dient Sonderfällen, in denen Dokumente kontrolliert von einer Quelldatenbank in eine Zieldatenbank übertragen und dabei bestimmte Feldinhalte im Zieldokument anhand von Key-/Replace-Listen angepasst werden müssen.

Repliziert Dokumente aus der durch FROMDBHANDLE1 referenzierten Datenbank in die durch TODBHANDLE2 referenzierte Datenbank.

Die Replikation erfolgt nur in Richtung FROMDBHANDLE1 nach TODBHANDLE2. Es werden nur die Dokumente berücksichtigt, die der Notes-kompatiblen Selection Formula FORMULA3 entsprechen und zu den in NOTECLASSES5 angegebenen Dokumentklassen gehören.

Die Datenbanken müssen keine Repliken voneinander sein.

Nach der Replikation eines Dokuments in die Zieldatenbank wird das dort erzeugte oder aktualisierte Dokument anhand der angegebenen Key-, Replace-, Target- und Default-Listen verändert.

Die Listen

TEXTLISTActKey,
TEXTLISTKeyFieldName,
TEXTLISTReplaceFieldName,
TEXTLISTTargetFieldName,
FNLISTTargetFieldFlags,
FNLISTOperationFlags,
TEXTLISTDefaultFieldName und
TEXTLISTDefaultValue

gehören positionsweise zusammen. Das bedeutet: Die jeweils gleich positionierten Elemente dieser Listen bilden zusammen eine Replace-Regel.

Für jede dieser Replace-Regeln wird im replizierten Zieldokument folgende Logik ausgeführt:
1. Aus TEXTLISTKeyFieldName wird der Name eines Feldes entnommen. Dieses Feld muss im aktuellen Zieldokument als TEXT oder TEXTLIST vorhanden sein. In diesem Feld wird nach dem zugehörigen Key aus TEXTLISTActKey gesucht.
2. Wird der Key gefunden, wird aus dem Feld, dessen Name aus TEXTLISTReplaceFieldName entnommen wird, das Element an derselben Listenposition gelesen.
3. Der so ermittelte Wert wird in das Feld geschrieben, dessen Name aus TEXTLISTTargetFieldName entnommen wird. Die Field Flags für dieses Zielfeld werden aus FNLISTTargetFieldFlags entnommen.

Wird der Key nicht gefunden, wird ein Default-Wert verwendet.
Dazu wird zunächst geprüft, ob im aktuellen Zieldokument ein Feld mit dem Namen aus TEXTLISTDefaultFieldName existiert. Falls dieses Feld vorhanden ist und den Datentyp TEXT oder TEXTLIST hat, wird dessen Inhalt als Ersatzwert verwendet.
Falls dieses Feld nicht existiert, wird der entsprechende Wert aus TEXTLISTDefaultValue verwendet.
Über FNLISTOperationFlags kann gesteuert werden, ob ausschließlich der Default-Text, ausschließlich das Default-Feld oder automatisch zuerst das Default-Feld und danach der Default-Text verwendet werden soll.

Nachdem alle Replace-Regeln erfolgreich angewendet wurden, werden Hilfsfelder aus dem Zieldokument entfernt.
Zunächst wird aus dem Feld mit dem Namen TEXTRemoveFieldNamesFieldName eine Liste von Feldnamen gelesen. Diese Felder werden aus dem aktuellen Zieldokument gelöscht.
Anschließend werden zusätzlich alle Felder gelöscht, deren Namen in TEXTLISTRemoveFieldNames angegeben sind.

Tritt während dieser Replace- und Bereinigungslogik ein Fehler auf, wird das betreffende Dokument nicht in die Datenbank TODBHANDLE2 repliziert. In diesem Fall wird das vierte Element der optionalen Fehlerliste FNLISTERROR7 um eins erhöht.

Im Fall eines Replizierkonflikts ist das Dokument in der Datenbank TODBHANDLE2 immer der Conflict Loser.

Die Funktion gibt eine FNLIST mit den Replikationsergebnissen zurück:
Element 1: Anzahl aktualisierter Dokumente in TODBHANDLE2
Element 2: Anzahl neu erstellter Dokumente in TODBHANDLE2
Element 3: Anzahl gelöschter Dokumente in TODBHANDLE2

FN4:
Bit   HEX   Bedeutung
01   0001   Lesen
02   0002   Schreiben
03   0004   Ändern
04   0008   Löschen

Hinweis:
Bei Replikationen mit asymmetrischer Rechtezuweisung kann es zu einem Verhalten kommen, das auf den ersten Blick widersprüchlich wirkt.
Beispiel: Datenbank A darf Dokumente nach Datenbank B replizieren. Datenbank B hat jedoch keine Löschrechte in Datenbank A.
Wird nun ein Dokument zunächst von A nach B repliziert und anschließend in B gelöscht, entsteht in B ein Deletion Stub. Dieser Deletion Stub bleibt bis zum CutOffTD der Datenbank erhalten; siehe hierzu auch @GetDBReplicaInfo.
Da B keine Löschrechte in A hat, wird die Löschung nicht von B nach A repliziert. Das ursprüngliche Dokument bleibt also in A weiterhin vorhanden.
Solange der Deletion Stub in B existiert, wird das in A noch vorhandene Dokument jedoch auch nicht erneut von A nach B repliziert. Für die Replikationslogik gilt das Dokument in B in diesem Zeitraum weiterhin als gelöscht.
Erst wenn der Deletion Stub in B nach Ablauf des CutOffTD entfernt wurde, kann das Dokument bei einer späteren Replikation wieder von A nach B übertragen werden. Dadurch kann es so wirken, als würde das Dokument plötzlich wieder in B erscheinen.
Dieses Verhalten entspricht dem Verhalten des Domino-Replicators bei asymmetrisch vergebenen Replikationsrechten.

NOTECLASSES5:
DEC   BIT   Bedeutung
00000   XX   No Notes   keine Dokumente
00001   01   Documents   Daten-Dokumente
00002   02   Policy-Note   Über-DB-Dokument
00004   03   Form-Note   Masken-Design-Dokumente
00008   04   View-Note   Ansicht-Design-Dokumente
00016   05   Icon-Note   Piktogramm-Dokument
00032   06   Design-Collection-Note   Ansicht-Dokumente
00064   07   ACL-Info-Note   ACL-Info-Dokument
00128   08   Help-Index-Note   
00256   09   Help-Note   Hilfe-DB-Dokument
00512   10   Filter-Note   Macro-Design-Dokumente
01024   11   Feld-Note   Feld-Design-Dokumente
02048   12   Replication-Note   Replikations-Dokumente
04096   13   Privat_Design   Privat-Design-Dokumente

32768   16   Default-Note of Each   Von jedem das Vorgabe-Dokument

32767   01-15   Notes   Alle Dokumente
32766   02-15   All Non-Document-Notes   Alle nicht Daten-Dokumente

Um mehrere Dokumentenklassen anzugeben werden die Werte der betreffenden Klassen addiert oder durch @BitVektor aufgebaut.

FNREPLICATIONFLAGS6:
Bit   HEX   Bedeutung
01   0001   Lokalisieren von Links (Doc;View;DB) in Datenbanken mit unterschiedlicher ReplicaID.

FNLISTERROR7:
Bei Verwendung des optionalen Return-Parameter FNLISTERROR7, wird in diesem eine Error-Statistik zurückgegeben.

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

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

* Wenn keines dieser Bits gesetzt ist: wird, wenn möglich, das Default-Feld genutzt, anderenfalls der Default-Text.

FNLISTTargetFieldFlags:
DEC   BIT   Bedeutung
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

Um mehrere FieldFlags anzugeben werden die Werte addiert.

Beispiel: @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);

Die Dokumente aus der DB mit dem DBHANDLE FROMDBHANDLE1 werden in die DB mit dem DBHANDLE TODBHANDLE2 repliziert und verändert.

1.Beispiel für ein Dokument und dessen Änderung:

Dokument in DB1:
Feldname   Datentyp   FieldFlags   Inhalt (Listenseperator Semikolon)
KeyList   TEXTLIST   4   Key1;Key2;Key3
ReplaceList   TEXTLIST   4   User1;User2;User3
RemoveFieldsList   TEXTLIST   4   KeyList;ReplaceList;RemoveFieldsList
Form   TEXT   4   Test

repliziertes (und geändertes) Dokument in DB2:

Feldname   Datentyp   FieldFlags   Inhalt (Listenseperator Semikolon)
Target1   TEXT   1092   User1
Target2   TEXT   100   User3
Form   TEXT   4   Test

2.Beispiel für ein Dokument und dessen Änderung:

Dokument in DB1:
Feldname   Datentyp   FieldFlags   Inhalt (Listenseperator Semikolon)
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

repliziertes (und geändertes) Dokument in DB2:

Feldname   Datentyp   FieldFlags   Inhalt (Listenseperator Semikolon)
Target1   TEXT   1092   DefaultUser1
Target2   TEXT   100   User3
Form   TEXT   4   Test

3.Beispiel für ein Dokument und dessen Änderung:

Dokument in DB1:
Feldname   Datentyp   FieldFlags   Inhalt (Listenseperator Semikolon)
KeyList   TEXTLIST   4   Key2;Key3;Key4
ReplaceList   TEXTLIST   4   User2;User3;User4
RemoveFieldsList   TEXTLIST   4   KeyList;ReplaceList;RemoveFieldsList
Form   TEXT   4   Test

repliziertes (und geändertes) Dokument in DB2:

Feldname   Datentyp   FieldFlags   Inhalt (Listenseperator Semikolon)
Target1   TEXT   1092   DefaultValue Key1
Target2   TEXT   100   User3
Form   TEXT   4   Test

Hinweis zu diesen Beispiel-Dokumenten:
Felder die für das Verständnis der Replace-Logik nicht erforderlich sind ($UpdatedBy, $Revisions …) wurden nicht aufgeführt.