GET_COLUMN_VALUE_FROM_NAME

Durée de validité

Extraction et réplication

Description

Utilisez la fonction GET_COLUMN_VALUE_FROM_NAME pour extraire la valeur de colonne de l'enregistrement de données à l'aide du nom de colonne indiqué. Les valeurs de colonne constituent la base de la plupart des logiques au sein de l'exit utilisateur. Vous pouvez baser une logique complexe sur les valeurs de colonnes individuelles de l'enregistrement de données.

Si la session de caractères de l'exit utilisateur est définie avec SET_SESSION_CHARSET sur une valeur autre que le jeu de caractères par défaut du système d'exploitation, tel que défini dans ULIB_CS_DEFAULT dans le fichier ucharset.h, les données de caractères échangées entre l'exit utilisateur et le processus sont interprétées dans le jeu de caractères de session.

Une valeur de colonne est définie sur le jeu de caractères de session uniquement si la condition suivante est remplie :

La valeur de colonne est un type de caractère SQL (CHAR/VARCHAR2/CLOB, NCHAR/NVARCHAR2/NCLOB), un type de date/horodatage/intervalle/nombre SQL.
L'indicateur column_value_mode est défini sur EXIT_FN_CNVTED_SESS_CHAR_FORMAT.

Si la base de données fait la distinction entre les majuscules et les minuscules, les noms d'objet doivent être indiqués dans la même lettre que ceux définis dans la base de données d'hébergement. Sinon, la casse n'a pas d'importance.

Syntaxe

#include "usrdecs.h"
short result_code;
column_def column;
ERCALLBACK (GET_COLUMN_VALUE_FROM_NAME, &column, &result_code);

Tampon

typedef struct
{
char *column_value;
unsigned short max_value_length;
unsigned short actual_value_length;
short null_value;
short remove_column;
short value_truncated;
short column_index;
char *column_name;
/* Version 3 CALLBACK_STRUCT_VERSION */
short column_value_mode;
short source_or_target;
/* Version 2 CALLBACK_STRUCT_VERSION */
char requesting_before_after_ind;
char more_lob_data;
/* Version 3 CALLBACK_STRUCT_VERSION  */
ULibCharSet column_charset;
} column_def;

Entrée

<column_value>

Pointeur vers un tampon pour accepter la valeur de colonne renvoyée.

<max_value_length>

Longueur maximale de la valeur de colonne renvoyée. En général, la longueur maximale est la longueur du tampon de valeurs de colonne. Si le format ASCII est indiqué (voir column_value_mode), la valeur de la colonne est terminée avec la valeur NULL et la longueur maximale doit être égale à la longueur maximale de la valeur de la colonne.

<column_name>

Nom de la colonne pour la valeur de colonne à renvoyer.

<column_value_mode>

Indique le jeu de caractères de la valeur de colonne.

EXIT_FN_CHAR_FORMAT

Format ASCII : la valeur est une chaîne ASCII (ou EBCDIC) à terminaison NULL (avec une exception connue pour le type de sous-données UTF16_BE, qui est converti en UTF 8). Remarque : Une valeur de colonne peut être tronquée lorsqu'elle est présentée à un user exit, car elle est interprétée comme une chaîne ASCII et est censée être terminée par une valeur NULL. La première valeur de 0 devient le caractère de fin de chaîne.

Les dates sont au format CCYY-MM-DD HH:MI:SS.FFFFFF, dans lequel le temps fractionnaire dépend de la base de données.
Les valeurs numériques sont au format chaîne. Par exemple, 123.45 est représenté par "123.45".
Les caractères non imprimables ou les valeurs binaires sont convertis en notation hexadécimale.
Les types à virgule flottante sont générés sous forme de chaînes à terminaison NULL, avec les 14 premiers chiffres significatifs.

EXIT_FN_RAW_FORMAT

Format canonique Oracle GoldenGate interne : ce format inclut un indicateur NULL de deux octets et une longueur de données variable de deux octets, le cas échéant. Oracle GoldenGate n'effectue aucune conversion de jeu de caractères pour ce format, quel que soit le type de données.

EXIT_FN_CNVTED_SESS_CHAR_FORMAT

Jeu de caractères de sortie utilisateur : s'applique uniquement si le type de données de colonne est :

un type basé sur des caractères, sur un ou plusieurs octets
un type numérique avec une représentation de type chaîne

Ce format ne prend pas fin avec la valeur NULL.

<source_or_target>

L'un des éléments suivants indique si l'enregistrement de données source ou cible doit être utilisé pour extraire la valeur de colonne.

EXIT_FN_SOURCE_VAL
EXIT_FN_TARGET_VAL

<requesting_before_after_ind>

Défini lors du traitement d'un enregistrement d'image après et que vous souhaitez utiliser les colonnes avant d'une mise à jour ou d'une mise à jour de clé primaire.

Pour obtenir la valeur "avant" de la colonne lors du traitement d'une image "après" d'une mise à jour de clé primaire ou d'un enregistrement de mise à jour standard (sans clé), définissez l'indicateur requesting_before_after_ind sur BEFORE_IMAGE_VAL.

Pour accéder à l'image "avant" des colonnes de clé d'une mise à jour de clé primaire, rien d'autre n'est nécessaire.
Pour accéder aux colonnes non-clé d'une mise à jour de clé primaire ou à toute colonne d'une mise à jour standard, l'image "avant" doit être disponible.

Le paramètre par défaut est AFTER_IMAGE_VAL (obtenir l'image après de la colonne) lorsqu'aucune entrée explicite pour requesting_before_after_ind n'est indiquée.

Pour rendre une image before disponible, vous pouvez utiliser le paramètre GETUPDATEBEFORES ou l'option INCLUDEUPDATEBEFORES dans l'instruction de paramètre CUSEREXIT.

Tenez compte des points suivants :

GETUPDATEBEFORES amène un processus d'extraction à écrire des enregistrements d'image avant dans la trace, ainsi qu'à effectuer un appel EXIT_CALL_PROCESS_RECORD vers l'exit utilisateur avec les images avant.
INCLUDEUPDATEBEFORES n'entraîne pas d'appel EXIT_CALL_PROCESS_RECORD vers l'exit utilisateur et, dans le cas de l'extraction, n'entraîne pas l'écriture de l'image "avant" dans la trace.

Sortie

<column_value>

Pointeur vers la valeur de colonne renvoyée. Si column_value_mode est spécifié en tant que EXIT_FN_CHAR_FORMAT, la valeur de colonne est renvoyée sous la forme d'une chaîne ASCII à terminaison NULL ; sinon, la valeur de colonne est renvoyée au format canonique interne d'Oracle GoldenGate. Au format ASCII, les dates sont renvoyées au format suivant :

CCYY-MM-DD HH:MI:SS.FFFFFF

L'inclusion du temps fractionné dépend de la base de données.

longueur réelle

Longueur de chaîne du nom de colonne renvoyé. La longueur réelle n'inclut pas de terminaison NULL lorsque column_value_mode est indiqué en tant que EXIT_FN_CHAR_FORMAT.

<null_value>

Indicateur (0 ou 1) indiquant si la valeur de colonne est NULL. Si l'indicateur null_value est 1, le tampon de valeur de colonne est rempli avec des octets NULL.

<value_truncated>

Indicateur (0 ou 1) indiquant si la valeur a été tronquée ou non. La troncature se produit si la longueur de la valeur de colonne dépasse la longueur maximale du tampon. Si column_value_mode a été indiqué en tant que EXIT_FN_CHAR_FORMAT, le terminaison NULL est inclus dans la longueur de la colonne.

caractère more_lob_data

Indicateur signalant si plus de données LOB sont présentes au-delà de la valeur 4K initiale qui peut être stockée dans l'enregistrement de base. Lorsqu'une valeur LOB est supérieure à la limite 4K, elle est stockée dans des fragments LOB.

Vous devez allouer la quantité de mémoire appropriée pour contenir les valeurs renvoyées. Oracle GoldenGate accédera à tout moment aux colonnes LOB jusqu'à 8K de données, en remplissant la mémoire tampon jusqu'à la quantité allouée par l'exit utilisateur. Si la valeur LOB est supérieure à celle qui a été allouée, les rappels suivants sont requis pour obtenir le total des données de colonne, jusqu'à ce que toutes les données aient été envoyées à l'exit utilisateur.

Pour déterminer la fin des données, évaluez more_lob_data. L'exit utilisateur définit cet indicateur sur CAR_NO_VAL ou CHAR_YES_VAL avant d'accéder à une nouvelle colonne. Si cet indicateur est toujours initialisé après le premier rappel et n'est pas défini sur CHAR_YES_VAL ou CAR_NO_VAL, l'une des conditions suivantes est remplie :

Une quantité suffisante de mémoire a été allouée pour gérer le fichier LOB.
Il ne s'agit pas d'un LOB.
La taille de l'enregistrement de trace de base n'a pas dépassé la limite 4K.

Il est recommandé d'obtenir les métadonnées de la table source pour déterminer si une colonne peut être une colonne LOB.

Valeurs retournées

EXIT_FN_RET_BAD_COLUMN_DATA
EXIT_FN_RET_COLUMN_NOT_FOUND
EXIT_FN_RET_INVALID_COLUMN
EXIT_FN_RET_INVALID_CONTEXT
EXIT_FN_RET_INVALID_PARAM
EXIT_FN_RET_OK

Exemple

memset (&col_meta, 0, sizeof(col_meta));
if (record.mapped)
col_meta.source_or_target = EXIT_FN_TARGET_VAL;
else
col_meta.source_or_target = EXIT_FN_SOURCE_VAL;
col_meta.source_or_target = EXIT_FN_SOURCE_VAL;
col_meta.column_name = (char *)malloc(100);
col_meta.max_name_length = 100;
col_meta.column_index = 1;

call_callback (GET_COL_METADATA_FROM_NAME, &col_meta, &result_code);