Utiliser des user exits pour étendre les fonctionnalités d'Oracle GoldenGate

Les user exits sont des routines personnalisées que vous écrivez dans le code de programmation C et que vous appelez au cours du traitement Extract ou Replicat. Les user exits étendent et personnalisent les fonctionnalités des processus Extract et Replicat avec un minimum de complexité et de risques. Avec les exits utilisateur, vous pouvez répondre aux événements de base de données lorsqu'ils se produisent, sans modifier les programmes de production.

Remarque : si vous utilisez CUSEREXITS, la variable d'environnement LD_LIBRARY_PATH doit être étendue. Par défaut, le répertoire $OGG_HOME/lib fait partie du répertoire de base du logiciel Oracle GoldenGate. Il est séparé du répertoire Deployment par conception. Si des objets partagés supplémentaires doivent être ajoutés pour les fonctions d'exit utilisateur, il est recommandé de ne pas utiliser le répertoire $OGG_HOME/lib et de choisir un autre emplacement. Pour CUSEREXITS, vous devez étendre la variable d'environnement LD_LIBRARY_PATH à un autre emplacement.

Quand implémenter des user exits

Vous pouvez utiliser des user exits comme alternative ou en association avec les fonctions de conversion de colonne disponibles dans Oracle GoldenGate. Les exits utilisateur peuvent être une meilleure alternative aux fonctions intégrées, car un exit utilisateur ne traite les données qu'une seule fois (lorsque les données sont extraites) plutôt que deux fois (une fois que les données sont extraites et une fois pour effectuer la transformation).

Vous pouvez implémenter des exits utilisateur de plusieurs manières :

Effectuer des opérations arithmétiques, des conversions de dates ou des recherches de table lors du mappage d'une table à une autre.
Implémenter des fonctions d'archivage des enregistrements hors ligne.
Répondez aux événements de base de données inhabituels de manière personnalisée, par exemple en envoyant un message électronique ou une page en fonction d'une valeur de sortie.
Cumuler des totaux et collecter des statistiques.
Manipulez un enregistrement.
Réparer les données non valides.
Calculer la différence nette dans un enregistrement avant et après une mise à jour.
Acceptez ou rejetez les enregistrements pour extraction ou réplication en fonction de critères complexes.
Normaliser une base de données lors de la conversion.

Rendre les informations d'enregistrement Oracle GoldenGate disponibles pour la routine

La fonction EXIT_CALL_PROCESS_RECORD est la base de la plupart des traitements d'exits utilisateur. Pour Extract, cette fonction est appelée juste avant la sortie d'un tampon d'enregistrement dans la trace (trail). Pour le processus Replicat, il est appelé juste avant qu'un enregistrement ne soit appliqué à la cible. Si le mapping source-cible est indiqué dans le fichier de paramètres, l'événement EXIT_CALL_PROCESS_RECORD a lieu après l'exécution du mapping.

Lorsque EXIT_CALL_PROCESS_RECORD est appelé, le tampon d'enregistrement et d'autres informations d'enregistrement lui sont accessibles via des sous-programmes de rappel. L'exit utilisateur peut mapper, transformer, nettoyer ou effectuer toute autre opération avec l'enregistrement de données. Lorsqu'il est terminé, l'exit utilisateur peut renvoyer un statut indiquant si l'enregistrement doit être traité ou ignoré par le processus Extract ou Replicat.

Créer des user exits

Les instructions suivantes vous aident à créer des exits utilisateur sur les systèmes Windows et UNIX. Pour plus d'informations sur les paramètres et les fonctions décrits dans ces instructions, reportez-vous à Référence pour Oracle GoldenGate pour Windows et UNIX.

Remarque : les exits utilisateur respectent la casse pour les noms d'objet de base de données. Les noms sont renvoyés exactement comme ils sont définis dans la base de données d'hébergement. Les noms d'objet doivent être entièrement qualifiés.

Pour créer des user exits

Dans le code C, créez un objet partagé (systèmes UNIX) ou une DLL (Windows) et créez ou exportez une routine à appeler à partir du processus Replicat. Cette routine est le point de communication entre Oracle GoldenGate et vos routines. Nommez la routine comme vous voulez. La routine doit accepter les paramètres d'exit utilisateur Oracle GoldenGate suivants :
- EXIT_CALL_TYPE : indique quand, au cours du traitement, la routine est appelée.
- EXIT_CALL_RESULT : fournit une réponse à la routine.
- EXIT_PARAMS : fournit des informations à la routine. Cette fonction vous permet d'utiliser l'option EXITPARAM de l'instruction TABLE ou MAP pour transmettre un paramètre qui est une chaîne littérale à l'exit utilisateur. Ceci n'est valide que lors de l'appel de sortie pour traiter un enregistrement spécifique. Cette fonction vous permet également de transmettre les paramètres spécifiés avec l'option PARAMS du paramètre CUSEREXIT au démarrage de l'appel de sortie.
Incluez le fichier usrdecs.h dans le code source. Le fichier usrdecs.h est le fichier d'inclusion de l'API d'exit utilisateur. Il contient des définitions de type, des valeurs de statut de retour, des codes de fonction de rappel et un certain nombre d'autres définitions. Le fichier usrdecs.h est installé dans le répertoire Oracle GoldenGate. Ne modifiez pas ce fichier.
Incluez les routines de callback Oracle GoldenGate dans l'exit utilisateur, le cas échéant. Les routines de rappel extraient les informations de contexte d'enregistrement et d'application et modifient le contenu des enregistrements de données. Pour implémenter une routine de rappel, utilisez la fonction ERCALLBACK dans l'objet partagé. La routine de rappel utilisateur se comporte différemment en fonction du code de fonction transmis à la routine de rappel.

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.

Incluez le paramètre CUSEREXIT dans le fichier de paramètres de réplication. Ce paramètre accepte le nom de l'objet partagé ou de la DLL et le nom de la routine exportée qui doit être appelée à partir du processus Replicat. Vous pouvez spécifier le chemin complet de l'objet partagé ou de la DLL ou laisser la stratégie de recherche standard du système d'exploitation localiser l'objet partagé.

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.

Exemple 9-41 Exemple de syntaxe de base, UNIX

CUSEREXIT eruserexit.so MyUserExit

Exemple 9-42 Exemple de syntaxe de base, Windows

CUSEREXIT eruserexit.dll MyUserExit

Prise en charge de la conversion de jeu de caractères dans les user exits

Pour préserver l'intégrité des données, un programme utilisateur doit comprendre le jeu de caractères des données de type caractère qu'il échange avec un processus Oracle GoldenGate. La logique d'exit utilisateur Oracle GoldenGate prend en charge la globalisation pour :

métadonnées de base de données basées sur des caractères, telles que les noms des catalogues, des schémas, des tables et des colonnes
les valeurs des colonnes de type caractère, telles que CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2 et NCLOB, ainsi que les nombres basés sur une chaîne, la date et l'heure et les intervalles.

La conversion correcte entre les jeux de caractères permet de comparer, de manipuler, de convertir et de mapper correctement les données de colonne d'un type de base de données et d'un jeu de caractères à un autre. La plupart de ce traitement est effectué lorsque le type d'appel EXIT_CALL_PROCESS_RECORD est appelé et que le tampon d'enregistrement et d'autres informations d'enregistrement sont disponibles via des routines de rappel.

L'exit utilisateur possède son propre jeu de caractères de session. Elle est définie par les fonctions de rappel GET_SESSION_CHARSET et SET_SESSION_CHARSET. Le processus appelant assure la conversion entre les jeux de caractères si le jeu de caractères de l'exit utilisateur est différent du contexte d'hébergement du processus.

Pour activer cette prise en charge dans les exits utilisateur, il existe le code de fonction de rappel GET_DATABASE_METADATA. Cette fonction permet à l'exit utilisateur d'obtenir des métadonnées de base de données, telles que les paramètres régionaux et le jeu de caractères des données de type caractère qu'il échange avec le processus qui les appelle (Extract, Data Pump, Replicat). Il renvoie également la façon dont la base de données traite la distinction entre les majuscules et les minuscules des noms d'objet, la façon dont elle traite les noms entre guillemets et non entre guillemets et la façon dont elle stocke les noms d'objet.

Pour plus d'informations sur ces composants, reportez-vous à Référence pour Oracle GoldenGate pour Windows et UNIX.

Utilisation de macros pour vérifier les métadonnées de nom

Le nom d'objet transmis par l'API d'exit utilisateur est le nom exact qui est codé dans le jeu de caractères de session d'exit utilisateur et exactement le même nom que celui extrait de la base de données. Si l'exit utilisateur compare le nom de l'objet à une chaîne littérale, l'exit utilisateur doit extraire les paramètres régionaux de la base de données, puis normaliser la chaîne afin qu'elle soit comparée au nom de l'objet dans le même codage.

Oracle GoldenGate fournit les macros suivantes qui peuvent être appelées par l'exit utilisateur pour vérifier les métadonnées des noms d'objet de base de données. Par exemple, une macro peut être utilisée pour vérifier si un nom de table entre guillemets est sensible à la casse et s'il est stocké en tant que casse mixte dans le serveur de base de données. Ces macros sont définies dans le fichier usrdecs.h.

Tableau 20 Macros pour la vérification des métadonnées

Macro	Ce qu'il vérifie
`supportsMixedCaseIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite un nom sans guillemet mixte d'un type de données spécifié comme sensible à la casse et stocke le nom en majuscules/minuscules.
`supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )`	Indique si la base de données traite le nom entre guillemets mixtes d'un type de données spécifié comme sensible à la casse et stocke le nom en majuscules/minuscules.
`storesLowerCaseIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite le nom sans guillemet mixte d'un type de données spécifié comme non sensible à la casse et stocke le nom en minuscules.
`storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite le nom entre guillemets mixtes d'un type de données spécifié comme non sensible à la casse et stocke le nom en minuscules.
`storesMixedCaseIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite le nom sans guillemet mixte d'un type de données spécifié comme non sensible à la casse et stocke le nom en majuscules/minuscules.
`storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite le nom entre guillemets d'un type de données spécifié comme non sensible à la casse et stocke le nom en majuscules/minuscules.
`storesUpperCaseIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite le nom sans guillemet mixte d'un type de données spécifié comme non sensible à la casse et stocke le nom en majuscules.
`storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )`	Indique si la base de données traite le nom entre guillemets mixtes d'un type de données spécifié comme non sensible à la casse et stocke le nom en majuscules.

Description du format de caractère

Le paramètre d'entrée column_value_mode décrit le format de caractère des données en cours de traitement et est utilisé dans plusieurs codes de fonction. Le tableau suivant décrit la signification des codes de format EXIT_FN_RAW_FORMAT, EXIT_FN_CHAR_FORMAT et EXIT_FN_CNVTED_SESS_FORMAT, par type de données.

Tableau 21 column_value_mode_matrix Significations

Type de données EXIT_FN_RAW_FORMAT EXIT_FN_CHAR_FORMAT EXIT_FN_CNVTED_SESS_FORMAT

Type de données	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
`CHAR` `"abc`"	Indicateur NULL de 2 octets + Informations sur la longueur sur 2 octets + valeur de colonne 0000 0004 61 62 63 20	"abc" encodé en `ASCII` ou `EBCDIC`. `NULL` a pris fin. Les espaces de queue sont découpés.	"abc" encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin. Les espaces de queue sont tronqués par défaut, sauf si le paramètre `GLOBALS` `NOTRIMSPACES` est spécifié.
`NCHAR` `0061 0062 0063 0020`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne. 0000 0008 00 61 0062 0063 0020	"abc" (encodé en `UTF8`) ou tronqué au premier octet, selon que `NCHAR` est traité comme UTF-8. `NULL` a pris fin. Les espaces de fin sont tronqués.	"abc" encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin. Les espaces de queue sont tronqués par défaut, sauf si le paramètre `GLOBALS` `NOTRIMSPACES` est spécifié.
`VARCHAR2` `"abc"`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	"abc" encodé en `ASCII` ou `EBCDIC`. `NULL` a pris fin. Aucune coupe.	"abc" encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin. Aucune coupe.
`NVARCHAR2` `0061 0062 0063 0020`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	"abc" (encodé en `UTF8`) ou tronqué au premier octet, selon que `NVARCHAR2` est traité comme `UTF-8`. `NULL` a pris fin. Aucune coupe.	"abc"encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin. Aucune coupe.
`CLOB`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	Semblable à `VARCHAR2`, mais ne génère que jusqu'à 4K octets. `NULL` Terminé. Aucune coupe.	Semblable à `VARCHAR2`, mais uniquement les données de sortie demandées dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin. Aucune coupe.
`NCLOB`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	Semblable à `NVARCHAR2`, mais ne génère que jusqu'à 4K octets. `NULL` a pris fin. Aucune coupe.	Semblable à `NVARCHAR2`, mais uniquement les données de sortie demandées dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin. Aucune coupe.
`NUMBER` `123.89`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	"123.89" encodé en `ASCII` ou `EBCDIC`. `NULL` a pris fin.	"123.89" encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin.
`DATE` `31-May-11`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	"2011-05-31" encodé en `ASCII` ou `EBCDIC`. `NULL` a pris fin.	"2011-05-31" encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin.
`TIMESTAMP` `31-May-11 12.00.00 AM`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	"2011-05-31 12.00.00 AM" encodé en `ASCII` ou `EBCDIC`. `NULL` a pris fin.	"2011-05-31 12.00.00 AM" encodé dans le jeu de caractères de session d'exit utilisateur. `NOT NULL` a pris fin.
`Interval Year to Month or Interval Day to Second`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	S/O	S/O
`RAW`	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne	Indicateur NULL de 2 octets + Informations sur la longueur de 2 octets + valeur de colonne

CHAR

"abc"

Indicateur NULL de 2 octets +

Informations sur la longueur sur 2 octets

+ valeur de colonne

0000 0004 61 62 63 20

"abc" encodé en ASCII ou EBCDIC.

NULL a pris fin.

Les espaces de queue sont découpés.

"abc" encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Les espaces de queue sont tronqués par défaut, sauf si le paramètre GLOBALS NOTRIMSPACES est spécifié.

NCHAR

0061 0062 0063 0020

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne.

0000 0008 00 61 0062 0063 0020

"abc" (encodé en UTF8) ou tronqué au premier octet, selon que NCHAR est traité comme UTF-8.

NULL a pris fin.

Les espaces de fin sont tronqués.

"abc" encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Les espaces de queue sont tronqués par défaut, sauf si le paramètre GLOBALS NOTRIMSPACES est spécifié.

VARCHAR2

"abc"

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

"abc" encodé en ASCII ou EBCDIC.

NULL a pris fin.

Aucune coupe.

"abc" encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Aucune coupe.

NVARCHAR2

0061 0062 0063 0020

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

"abc" (encodé en UTF8) ou tronqué au premier octet, selon que NVARCHAR2 est traité comme UTF-8.

NULL a pris fin.

Aucune coupe.

"abc"encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Aucune coupe.

CLOB

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

Semblable à VARCHAR2, mais ne génère que jusqu'à 4K octets.

NULL Terminé.

Aucune coupe.

Semblable à VARCHAR2, mais uniquement les données de sortie demandées dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Aucune coupe.

NCLOB

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

Semblable à NVARCHAR2, mais ne génère que jusqu'à 4K octets.

NULL a pris fin.

Aucune coupe.

Semblable à NVARCHAR2, mais uniquement les données de sortie demandées dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Aucune coupe.

NUMBER

123.89

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

"123.89" encodé en ASCII ou EBCDIC.

NULL a pris fin.

"123.89" encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

DATE

31-May-11

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

"2011-05-31" encodé en ASCII ou EBCDIC.

NULL a pris fin.

"2011-05-31" encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

TIMESTAMP

31-May-11 12.00.00 AM

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

"2011-05-31 12.00.00 AM" encodé en ASCII ou EBCDIC.

NULL a pris fin.

"2011-05-31 12.00.00 AM" encodé dans le jeu de caractères de session d'exit utilisateur.

NOT NULL a pris fin.

Interval Year to Month or Interval Day to Second

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

S/O

RAW

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

Indicateur NULL de 2 octets +

Informations sur la longueur de 2 octets +

valeur de colonne

Mise à niveau des user exits

La gestion des versions du fichier usrdecs.h permet une compatibilité ascendante avec les exits utilisateur existants lorsque des améliorations ou des mises à niveau, telles que de nouvelles fonctions ou des modifications structurelles, sont ajoutées à une nouvelle version d'Oracle GoldenGate. La version du fichier usrdecs.h est imprimée dans le fichier de rapport au démarrage du processus Replicat ou Extract.

Pour utiliser la nouvelle fonctionnalité d'exit utilisateur, vous devez recompiler vos routines pour inclure le nouveau fichier usrdecs. Les routines qui n'utilisent pas de nouvelles fonctionnalités n'ont pas besoin d'être recompilées.

Affichage d'exemples d'utilisation des fonctions d'exit utilisateur

Oracle GoldenGate installe les exemples de fichiers d'exit utilisateur suivants dans le répertoire UserExitExamples du répertoire d'installation d'Oracle GoldenGate :

exitdemo.c indique comment initialiser l'exit utilisateur, exécuter des rappels à des points d'exit donnés et modifier les données. Il montre également comment extraire le nom complet de la table ou une partie de métadonnées spécifique, telle que le nom du catalogue ou du conteneur, ou le schéma, ou simplement le nom de la table non qualifiée. En outre, cette démonstration explique comment traiter des données LDD. La démonstration n'est spécifique à aucun type de base de données.
exitdemo_utf16.c indique comment utiliser les données codées en UTF16 (à la fois les métadonnées et les données de colonne) dans les structures de rappel pour les informations échangées entre l'exit utilisateur et le processus appelant.
exitdemo_more_recs.c montre un exemple d'utilisation du même enregistrement d'entrée plusieurs fois pour générer plusieurs enregistrements cible.
exitdemo_lob.c illustre un exemple d'accès en lecture aux données LOB.
exitdemo_pk_befores.c indique comment accéder aux parties d'image avant et après d'un enregistrement de mise à jour de clé primaire, ainsi qu'aux images avant des mises à jour régulières (mises à jour sans clé). Il montre également comment obtenir les valeurs de ligne cible avec SQLEXEC dans le fichier de paramètres de réplication comme moyen de détection des conflits. Les valeurs extraites résultantes de la cible sont mises en correspondance en tant qu'enregistrement cible lorsqu'il entre dans l'exit utilisateur.

Chaque répertoire contient les fichiers *.c, ainsi que les fichiers make et un fichier readme.txt.