Oracle GoldenGate-Funktionen mit User Exits erweitern

User Exits sind benutzerdefinierte Routinen, die Sie in C-Programmiercode schreiben und während der Extract- oder Replicat-Verarbeitung aufrufen. User Exits erweitern und passen die Funktionalität der Extract- und Replicat-Prozesse mit minimaler Komplexität und Risiken an. Mit User Exits können Sie auf Datenbankereignisse reagieren, wenn diese auftreten, ohne die Produktionsprogramme zu ändern.

Hinweis: Wenn Sie CUSEREXITS verwenden, muss die Umgebungsvariable LD_LIBRARY_PATH erweitert werden. Standardmäßig ist das Verzeichnis $OGG_HOME/lib Teil des Home-Verzeichnisses der Oracle GoldenGate-Software. Sie wird vom Deployment-Verzeichnis je nach Entwurf getrennt. Wenn zusätzliche gemeinsam verwendete Objekte für User Exit-Funktionen hinzugefügt werden müssen, wird empfohlen, dass Sie das Verzeichnis $OGG_HOME/lib nicht verwenden und einen anderen Speicherort auswählen. Bei CUSEREXITS müssen Sie die Umgebungsvariable LD_LIBRARY_PATH auf einen anderen Speicherort erweitern.

Implementierung von User Exits

Sie können User Exits als Alternative oder in Verbindung mit den Spaltenkonvertierungsfunktionen verwenden, die in Oracle GoldenGate verfügbar sind. User Exits können eine bessere Alternative zu den integrierten Funktionen sein, da ein User Exit Daten nur einmal (wenn die Daten extrahiert werden) und nicht zweimal (wenn die Daten extrahiert werden und einmal zur Durchführung der Transformation) verarbeitet.

Es gibt folgende Möglichkeiten, wie Sie User Exits implementieren können:

• Führen Sie arithmetische Vorgänge, Datumskonvertierungen oder Tabellen-Lookups aus, während Sie eine Zuordnung zwischen Tabellen vornehmen.

• Implementieren Sie Funktionen zur Datensatzarchivierung offline.

• Reagieren Sie auf ungewöhnliche Datenbankereignisse auf benutzerdefinierte Weise, indem Sie beispielsweise eine E-Mail-Nachricht oder eine Seite basierend auf einem Ausgabewert senden.

• Summen zusammenfassen und Statistiken sammeln

• Datensatz bearbeiten

• Ungültige Daten reparieren.

• Berechnen Sie die Nettodifferenz in einem Record vor und nach einer Aktualisierung.

• Akzeptieren oder lehnen Sie Datensätze für die Extraktion oder Replikation basierend auf komplexen Kriterien ab.

• Normalisieren Sie eine Datenbank während der Konvertierung.

Oracle GoldenGate-Datensatzinformationen für die Routine verfügbar machen

Die Basis für die meisten User Exit-Verarbeitungen ist die Funktion EXIT_CALL_PROCESS_RECORD. Bei Extract wird diese Funktion kurz vor der Ausgabe eines Datensatzpuffers in den Trail aufgerufen. Bei Replicat wird es kurz vor dem Anwenden eines Datensatzes auf das Ziel aufgerufen. Wenn die Zuordnung zwischen Quelle und Ziel in der Parameterdatei angegeben ist, erfolgt das Ereignis EXIT_CALL_PROCESS_RECORD nach der Zuordnung.

Wenn EXIT_CALL_PROCESS_RECORD aufgerufen wird, stehen ihm der Datensatzpuffer und andere Datensatzinformationen über Callback-Routinen zur Verfügung. Der User Exit kann den Datensatz zuordnen, transformieren, bereinigen oder andere Vorgänge ausführen. Wenn der Vorgang abgeschlossen ist, kann der User Exit einen Status zurückgeben, der angibt, ob der Datensatz von Extract oder Replicat verarbeitet oder ignoriert werden soll.

User Exits erstellen

Die folgenden Anweisungen helfen Ihnen beim Erstellen von User Exits auf Windows- und UNIX-Systemen. Weitere Informationen zu den Parametern und Funktionen, die in diesen Anweisungen beschrieben werden, finden Sie unter Referenz für Oracle GoldenGate für Windows und UNIX.

Hinweis: Bei User Exits muss die Groß-/Kleinschreibung bei Datenbankobjektnamen beachtet werden. Namen werden genau so zurückgegeben, wie sie in der Hostdatenbank definiert sind. Objektnamen müssen vollqualifiziert sein.

So erstellen Sie User Exits

1. Erstellen Sie im C-Code entweder ein gemeinsam genutztes Objekt (UNIX-Systeme) oder eine DLL (Windows) und erstellen oder exportieren Sie eine Routine, die aus dem Replicat aufgerufen werden soll. Diese Routine ist der Kommunikationspunkt zwischen Oracle GoldenGate und Ihren Routinen. Nennen Sie die Routine, was Sie wollen. Die Routine muss die folgenden Parameter für das Beenden von Oracle GoldenGate-Benutzern akzeptieren:

   • EXIT_CALL_TYPE: Gibt an, wann die Routine während der Verarbeitung aufgerufen wird.

   • EXIT_CALL_RESULT: Stellt eine Antwort auf die Routine bereit.

   • EXIT_PARAMS: Stellt Informationen für die Routine bereit. Mit dieser Funktion können Sie die Option EXITPARAM der Anweisung TABLE oder MAP verwenden, um einen Parameter, der eine Literalzeichenfolge ist, an den User Exit zu übergeben. Dies ist nur während des Beendigungsaufrufs gültig, um einen bestimmten Datensatz zu verarbeiten. Mit dieser Funktion können Sie auch Parameter übergeben, die beim Start des Exit-Aufrufs mit der Option PARAMS des Parameters CUSEREXIT angegeben wurden.

2. Nehmen Sie im Quellcode die Datei usrdecs.h auf. Die Datei usrdecs.h ist die Include-Datei für die User Exit API. Es enthält Typdefinitionen, Rückgabestatuswerte, Callback-Funktionscodes und eine Reihe anderer Definitionen. Die Datei usrdecs.h wird im Oracle GoldenGate-Verzeichnis installiert. Ändern Sie diese Datei nicht.

3. Nehmen Sie gegebenenfalls Oracle GoldenGate-Callback-Routinen in den User Exit auf. Callback-Routinen rufen Datensatz- und Anwendungskontextinformationen ab und ändern den Inhalt von Datensätzen. Um eine Callback-Routine zu implementieren, verwenden Sie die Funktion ERCALLBACK im gemeinsam verwendeten Objekt. Die Benutzer-Callback-Routine verhält sich je nach Funktionscode, der an die Callback-Routine übergeben wird, unterschiedlich.

ERCALLBACK (*function_code*, *buffer*, *result_code*);

Where:

- *function_code* is the function to be executed by the callback routine.

- *buffer* is a void pointer to a buffer containing a predefined structure associated with the specified function code.

- *result_code* is the status of the function that is executed by the callback routine. The result code that is returned by the callback routine indicates whether or not the callback function was successful.

- On Windows systems, Replicat export the `ERCALLBACK` function that is to be called from the user exit routine. The user exit must explicitly load the callback function at run-time using the appropriate Windows API calls.

1. Nehmen Sie den Parameter CUSEREXIT in die Replicat-Parameterdatei auf. Dieser Parameter akzeptiert den Namen des gemeinsam verwendeten Objekts oder der DLL und den Namen der exportierten Routine, die aus dem Replicat aufgerufen werden soll. Sie können den vollständigen Pfad des gemeinsam verwendeten Objekts oder der DLL angeben oder die Standardsuchstrategie des Betriebssystems das gemeinsam verwendete Objekt suchen lassen.

CUSEREXIT {*DLL* | *shared_object*} *routine*
[, INCLUDEUPDATEBEFORES]
[, PARAMS '*startup_string*']

Where:

- *DLL* is a Windows DLL and *shared_object* is a UNIX shared object that contains the user exit function.

- `INCLUDEUPDATEBEFORES` gets before images for `UPDATE` operations.

- `PARAMS `*'startup_string'* supplies a startup string, such as a startup parameter.

Beispiel 9-41: Basissyntax, UNIX

CUSEREXIT eruserexit.so MyUserExit

Beispiel 9-42: Basissyntax in Windows

CUSEREXIT eruserexit.dll MyUserExit

Unterstützung der Zeichensatzkonvertierung in User Exits

Um die Datenintegrität aufrechtzuerhalten, muss ein User Exit den Zeichensatz der Zeichentypdaten verstehen, die er mit einem Oracle GoldenGate-Prozess austauscht. Oracle GoldenGate User Exit-Logik bietet Globalisierungsunterstützung für:

• Zeichenbasierte Datenbankmetadaten, wie die Namen von Katalogen, Schemas, Tabellen und Spalten

• die Werte von Zeichenspalten, wie CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2 und NCLOB, sowie Zeichenfolgenbasierte Zahlen, Datum/Uhrzeit und Intervalle.

Durch die richtige Konvertierung zwischen Zeichensätzen können Spaltendaten von einem Datenbanktyp und Zeichensatz an einen anderen richtig verglichen, bearbeitet, konvertiert und zugeordnet werden. Der größte Teil dieser Verarbeitung wird ausgeführt, wenn der EXIT_CALL_PROCESS_RECORD-Aufruftyp aufgerufen wird und der Datensatzpuffer und andere Datensatzinformationen über Callback-Routinen verfügbar gemacht werden.

Der User Exit hat einen eigenen Session-Zeichensatz. Dies wird durch die Callback-Funktionen GET_SESSION_CHARSET und SET_SESSION_CHARSET definiert. Der Aufruferprozess ermöglicht die Konvertierung zwischen Zeichensätzen, wenn sich der Zeichensatz des User Exit vom Hosting-Kontext des Prozesses unterscheidet.

Um diese Unterstützung in User Exits zu aktivieren, gibt es den Callback-Funktionscode GET_DATABASE_METADATA. Mit dieser Funktion kann der User Exit Datenbankmetadaten abrufen, z.B. das Gebietsschema und den Zeichensatz der Zeichentypdaten, die er mit dem Prozess austauscht, der ihn aufruft (Extract, Data Pump, Replicat). Außerdem wird zurückgegeben, wie die Datenbank die Groß-/Kleinschreibung von Objektnamen behandelt, wie Namen in Anführungszeichen und ohne Anführungszeichen behandelt und wie Objektnamen gespeichert werden.

Weitere Informationen zu diesen Komponenten finden Sie unter Referenz für Oracle GoldenGate für Windows und UNIX.

Verwenden von Makros zum Prüfen von Namensmetadaten

Der Objektname, der von der User Exit API übergeben wird, ist der genaue Name, der im User Exit Session-Zeichensatz codiert ist, und genau derselbe Name, der aus der Datenbank abgerufen wird. Wenn der User Exit den Objektnamen mit einer Literalzeichenfolge vergleicht, muss der User Exit das Datenbankgebietsschema abrufen und dann die Zeichenfolge normalisieren, damit sie mit dem Objektnamen in derselben Codierung verglichen wird.

Oracle GoldenGate stellt die folgenden Makros bereit, die vom User Exit aufgerufen werden können, um die Metadaten der Datenbankobjektnamen zu prüfen. Beispielsweise kann ein Makro verwendet werden, um zu prüfen, ob bei einem Tabellennamen in Anführungszeichen die Groß-/Kleinschreibung beachtet wird und ob er auf dem Datenbankserver in Groß- und Kleinschreibung gespeichert ist. Diese Makros werden in der Datei usrdecs.h definiert.

Tabelle 20-Makros für Metadatenprüfung

Macro	Was es überprüft
supportsMixedCaseIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank einen Namen ohne Anführungszeichen eines angegebenen Datentyps in gemischter Groß-/Kleinschreibung behandelt und den Namen in gemischter Groß-/Kleinschreibung speichert.
supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps in gemischter Groß-/Kleinschreibung als Groß-/Kleinschreibung behandelt und den Namen in gemischter Groß-/Kleinschreibung speichert.
storesLowerCaseIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps ohne Anführungszeichen in Groß- und Kleinschreibung behandelt und den Namen in Kleinbuchstaben speichert.
storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps in gemischter Groß-/Kleinschreibung nicht berücksichtigt und den Namen in Kleinbuchstaben speichert.
storesMixedCaseIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps ohne Anführungszeichen in Groß- und Kleinschreibung behandelt und den Namen in Groß- und Kleinschreibung speichert.
storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps in gemischter Groß-/Kleinschreibung nicht berücksichtigt und den Namen in gemischter Groß-/Kleinschreibung speichert.
storesUpperCaseIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps ohne Anführungszeichen in Groß-/Kleinschreibung behandelt und den Namen in Großbuchstaben speichert.
storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )	Gibt an, ob die Datenbank den Namen eines angegebenen Datentyps in gemischter Groß-/Kleinschreibung nicht berücksichtigt und den Namen in Großbuchstaben speichert.

Zeichenformat beschreiben

Der Eingabeparameter column_value_mode beschreibt das Zeichenformat der Daten, die verarbeitet werden, und wird in mehreren Funktionscodes verwendet. In der folgenden Tabelle wird die Bedeutung der Formatcodes EXIT_FN_RAW_FORMAT, EXIT_FN_CHAR_FORMAT und EXIT_FN_CNVTED_SESS_FORMAT pro Datentyp beschrieben.

Tabelle 21 column_value_mode_matrix Bedeutungen

Datentyp	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
CHAR "abc"	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert 0000 0004 61 62 63 20	"abc"-Codierung in ASCII oder EBCDIC. NULL beendet. Tailing Spaces werden getrimmt.	"abc" im Zeichensatz für User Exit Session codiert. NOT NULL beendet. Tailing-Leerzeichen werden standardmäßig abgeschnitten, es sei denn, der Parameter GLOBALS NOTRIMSPACES ist angegeben.
NCHAR 0061 0062 0063 0020	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert. 0000000080000061006200630020	"abc" (in UTF8 codiert) oder beim ersten Byte abgeschnitten, je nachdem, ob NCHAR als UTF-8 behandelt wird. NULL beendet. Nachgestellte Leerzeichen werden abgeschnitten.	"abc" im Zeichensatz für User Exit Session codiert. NOT NULL beendet. Tailing-Leerzeichen werden standardmäßig abgeschnitten, es sei denn, der Parameter GLOBALS NOTRIMSPACES ist angegeben.
VARCHAR2 "abc"	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	"abc"-Codierung in ASCII oder EBCDIC. NULL beendet. Kein Abschneiden.	"abc" im Zeichensatz für User Exit Session codiert. NOT NULL beendet. Kein Abschneiden.
NVARCHAR2 0061 0062 0063 0020	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	"abc" (in UTF8 codiert) oder beim ersten Byte abgeschnitten, je nachdem, ob NVARCHAR2 als UTF-8 behandelt wird. NULL beendet. Kein Abschneiden.	"abc" im Zeichensatz für das Beenden der Benutzersitzung codiert. NOT NULL beendet. Kein Abschneiden.
CLOB	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	Ähnlich wie VARCHAR2, aber nur bis zu 4K Byte ausgeben. NULL beendet. Kein Abschneiden.	Ähnlich wie VARCHAR2, aber nur Ausgabedaten, die im Zeichensatz für das Beenden der Benutzersession angefordert wurden. NOT NULL beendet. Kein Abschneiden.
NCLOB	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	Ähnlich wie NVARCHAR2, aber nur bis zu 4K Byte ausgeben. NULL beendet. Kein Abschneiden.	Ähnlich wie NVARCHAR2, aber nur Ausgabedaten, die im Zeichensatz für das Beenden der Benutzersession angefordert wurden. NOT NULL beendet. Kein Abschneiden.
NUMBER 123.89	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	"123.89" in ASCII oder EBCDIC codiert. NULL beendet.	"123.89" codiert in Zeichensatz für User Exit Session. NOT NULL beendet.
DATE 31-May-11	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	"2011-05-31" codiert in ASCII oder EBCDIC. NULL beendet.	"2011-05-31" codiert in Zeichensatz für User Exit-Session. NOT NULL beendet.
TIMESTAMP 31-May-11 12.00.00 AM	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	"2011-05-31 12.00.00 Uhr" codiert in ASCII oder EBCDIC. NULL beendet.	"2011-05-31 12.00.00 AM" codiert in Zeichensatz für User Exit-Session. NOT NULL beendet.
Interval Year to Month or Interval Day to Second	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	NA	NA
RAW	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert	2-Byte-Nullindikator + 2-Byte-Länge Info + Spaltenwert

User Exits upgraden

Die usrdecs.h-Datei ist versioniert, um die Abwärtskompatibilität mit vorhandenen Benutzerausgängen zu ermöglichen, wenn Verbesserungen oder Upgrades, wie neue Funktionen oder strukturelle Änderungen, zu einem neuen Oracle GoldenGate-Release hinzugefügt werden. Die Version der Datei usrdecs.h wird beim Start von Replicat oder Extract in der Berichtsdatei gedruckt.

Um die neue User Exit-Funktionalität zu verwenden, müssen Sie Ihre Routinen neu kompilieren, um die neue Datei usrdecs aufzunehmen. Routinen, die keine neuen Funktionen verwenden, müssen nicht neu kompiliert werden.

Beispiele für die Verwendung von User Exit-Funktionen anzeigen

Oracle GoldenGate installiert die folgenden Beispieldateien zum Beenden des Benutzers im Verzeichnis UserExitExamples des Oracle GoldenGate-Installationsverzeichnisses:

• exitdemo.c zeigt, wie Sie den User Exit initialisieren, Callbacks an bestimmten Exit Points ausgeben und Daten ändern. Außerdem wird gezeigt, wie Sie den vollqualifizierten Tabellennamen oder einen bestimmten Metadatenteil abrufen, z.B. den Namen des Katalogs oder Containers, das Schema oder nur den nicht qualifizierten Tabellennamen. Darüber hinaus zeigt diese Demo, wie DDL-Daten verarbeitet werden. Die Demo ist für keinen Datenbanktyp spezifisch.

• exitdemo_utf16.c zeigt, wie UTF16-codierte Daten (sowohl Metadaten als auch Spaltendaten) in den Callback-Strukturen für Informationen verwendet werden, die zwischen dem User Exit und dem Caller-Prozess ausgetauscht werden.

• exitdemo_more_recs.c zeigt ein Beispiel dafür, wie Sie denselben Eingabedatensatz mehrmals verwenden, um mehrere Zieldatensätze zu generieren.

• exitdemo_lob.c zeigt ein Beispiel für den Lesezugriff auf LOB-Daten.

• exitdemo_pk_befores.c zeigt, wie Sie auf die Vor- und Nach-Image-Teile eines Primärschlüsselaktualisierungsdatensatzes sowie auf die Vor-Images regulärer Aktualisierungen (Nicht-Schlüsselaktualisierungen) zugreifen. Außerdem wird gezeigt, wie Sie Zielzeilenwerte mit SQLEXEC in der Replicat-Parameterdatei abrufen, um Konflikte zu erkennen. Die daraus resultierenden abgerufenen Werte aus dem Ziel werden beim Eintreten des User Exit als Zieldatensatz zugeordnet.

Jedes Verzeichnis enthält die *.c-Dateien sowie makefiles und eine readme.txt-Datei.