Uso de salidas de usuario para ampliar las capacidades de Oracle GoldenGate

Las salidas de usuario son rutinas personalizadas que se escriben en el código de programación C y se llaman durante el procesamiento de Extract o Replicat. Las salidas de usuario amplían y personalizan la funcionalidad de los procesos de Extract y Replicat con una complejidad y un riesgo mínimos. Con las salidas de usuario, puede responder a los eventos de la base de datos cuando se producen, sin alterar los programas de producción.

Nota: Si utiliza CUSEREXITS, se debe ampliar la variable de entorno LD_LIBRARY_PATH. Por defecto, el directorio $OGG_HOME/lib forma parte del directorio raíz del software de Oracle GoldenGate. Está separada del directorio Deployment por diseño. Si es necesario agregar objetos compartidos adicionales para las funciones de salida de usuario, se recomienda que no utilice el directorio $OGG_HOME/lib y elija una ubicación diferente. Para CUSEREXITS, debe ampliar la variable de entorno LD_LIBRARY_PATH a una ubicación diferente.

Cuándo Implantar Salidas de Usuario

Puede emplear salidas de usuario como alternativa a las funciones de conversión de columnas disponibles en Oracle GoldenGate o junto con ellas. Las salidas de usuario pueden ser una mejor alternativa a las funciones incorporadas porque una salida de usuario procesa los datos solo una vez (cuando se extraen los datos) en lugar de dos veces (una vez que se extraen los datos y una vez para realizar la transformación).

A continuación, se muestran algunas formas de implantar las salidas de usuario:

• Realizar operaciones aritméticas, conversiones de fecha o consultas de tabla al asignar de una tabla a otra.

• Implantación de funciones de archivación de registros fuera de línea.

• Responda a eventos inusuales de la base de datos de forma personalizada, por ejemplo, enviando un mensaje de correo electrónico o una página basada en un valor de salida.

• Acumular totales y recopilar estadísticas.

• Manipular un registro.

• Reparar datos no válidos.

• Calcular la diferencia neta en un registro antes y después de una actualización.

• Aceptar o rechazar registros para extracción o replicación en función de criterios complejos.

• Normalizar una base de datos durante la conversión.

Cómo poner la información del registro de Oracle GoldenGate a disposición de la rutina

La base para la mayoría del procesamiento de salida de usuario es la función EXIT_CALL_PROCESS_RECORD. Para Extract, esta función se llama justo antes de que se genere un buffer de registro en la pista. Para Replicat, se llama justo antes de que se aplique un registro al destino. Si la asignación origen-destino se especifica en el archivo de parámetros, el evento EXIT_CALL_PROCESS_RECORD se produce después de realizar la asignación.

Cuando se llama a EXIT_CALL_PROCESS_RECORD, el buffer de registro y otra información de registro están disponibles a través de rutinas de devolución de llamada. La salida de usuario puede asignar, transformar, limpiar o realizar cualquier otra operación con el registro de datos. Cuando haya finalizado, la salida de usuario puede devolver un estado que indique si Extract o Replicat deben procesar o ignorar el registro.

Creación de salidas de usuario

Las siguientes instrucciones le ayudan a crear salidas de usuario en sistemas Windows y UNIX. Para obtener más información sobre los parámetros y las funciones que se describen en estas instrucciones, consulte Reference for Oracle GoldenGate for Windows and UNIX.

Nota: Las salidas de usuario son sensibles a mayúsculas/minúsculas para los nombres de objetos de base de datos. Los nombres se devuelven exactamente como se definen en la base de datos de alojamiento. Los nombres de objeto deben estar completos.

Para crear salidas de usuario

1. En el código C, cree un objeto compartido (sistemas UNIX) o una DLL (Windows) y cree o exporte una rutina que se llamará desde Replicat. Esta rutina es el punto de comunicación entre Oracle GoldenGate y sus rutinas. Nombra la rutina lo que quieras. La rutina debe aceptar los siguientes parámetros de salida de usuario de Oracle GoldenGate:

   • EXIT_CALL_TYPE: indica cuándo se llama a la rutina durante el procesamiento.

   • EXIT_CALL_RESULT: proporciona una respuesta a la rutina.

   • EXIT_PARAMS: proporciona información a la rutina. Esta función permite utilizar la opción EXITPARAM de la sentencia TABLE o MAP para transferir un parámetro que es una cadena literal a la salida de usuario. Esto solo es válido durante la llamada de salida para procesar un registro específico. Esta función también permite transferir los parámetros especificados con la opción PARAMS del parámetro CUSEREXIT en el inicio de la llamada de salida.

2. En el código fuente, incluya el archivo usrdecs.h. El archivo usrdecs.h es el archivo de inclusión para la API de salida de usuario. Contiene definiciones de tipo, valores de estado de devolución, códigos de función de devolución de llamada y otras definiciones. El archivo usrdecs.h se instala en el directorio de Oracle GoldenGate. No modifique este archivo.

3. Incluya las rutinas de devolución de llamada de Oracle GoldenGate en la salida de usuario cuando corresponda. Las rutinas de devolución de llamada recuperan información de contexto de aplicación y registro y modifican el contenido de los registros de datos. Para implementar una rutina de devolución de llamada, utilice la función ERCALLBACK en el objeto compartido. La rutina de devolución de llamada del usuario se comporta de manera diferente según el código de función que se transfiere a la rutina de devolución de llamada.

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. Incluya el parámetro CUSEREXIT en el archivo de parámetros de Replicat. Este parámetro acepta el nombre del objeto compartido o DLL y el nombre de la rutina exportada que se va a llamar desde Replicat. Puede especificar la ruta de acceso completa del objeto compartido o DLL o permitir que la estrategia de búsqueda estándar del sistema operativo localice el objeto compartido.

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.

Ejemplo 9-41 Ejemplo de Sintaxis Básica, UNIX

CUSEREXIT eruserexit.so MyUserExit

Ejemplo 9-42 Sintaxis básica de ejemplo, Windows

CUSEREXIT eruserexit.dll MyUserExit

Soporte de Conversión de Juego de Caracteres en Salidas de Usuario

Para mantener la integridad de los datos, una salida de usuario debe comprender el juego de caracteres de los datos de tipo de caracteres que intercambia con un proceso de Oracle GoldenGate. La lógica de salida de usuario de Oracle GoldenGate proporciona soporte de globalización para:

• metadatos de base de datos basados en caracteres, como los nombres de catálogos, esquemas, tablas y columnas

• Los valores de las columnas de tipo de carácter, como CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2 y NCLOB, así como los números basados en cadenas, la fecha y hora y los intervalos.

La conversión adecuada entre juegos de caracteres permite comparar, manipular, convertir y asignar correctamente los datos de las columnas de un tipo de base de datos y juego de caracteres a otro. La mayor parte de este procesamiento se realiza cuando se llama al tipo de llamada EXIT_CALL_PROCESS_RECORD y el buffer de registro y otra información de registro están disponibles a través de rutinas de devolución de llamada.

La salida de usuario tiene su propio juego de caracteres de sesión. Esto se define mediante las funciones de devolución de llamada GET_SESSION_CHARSET y SET_SESSION_CHARSET. El proceso de emisor de llamada proporciona conversión entre juegos de caracteres si el juego de caracteres de la salida de usuario es diferente del contexto de alojamiento del proceso.

Para activar este soporte en las salidas de usuario, existe el código de función de devolución de llamada GET_DATABASE_METADATA. Esta función permite a la salida de usuario obtener metadatos de la base de datos, como la configuración regional y el juego de caracteres de los datos de tipo de carácter que intercambia con el proceso que lo llama (Extracción, pump de datos, Replicat). También devuelve cómo trata la base de datos la sensibilidad a mayúsculas/minúsculas de los nombres de objeto, cómo trata los nombres entre comillas y sin comillas y cómo almacena los nombres de objeto.

Para obtener más información sobre estos componentes, consulte Reference for Oracle GoldenGate for Windows and UNIX.

Uso de macros para comprobar metadatos de nombre

El nombre de objeto que transfiere la API de salida de usuario es el nombre exacto que se codifica en el juego de caracteres de sesión de salida de usuario y exactamente el mismo nombre que se recupera de la base de datos. Si la salida de usuario compara el nombre del objeto con una cadena literal, la salida de usuario debe recuperar la configuración regional de la base de datos y, a continuación, normalizar la cadena para que se compare con el nombre del objeto en la misma codificación.

Oracle GoldenGate proporciona las siguientes macros a las que puede llamar la salida de usuario para comprobar los metadatos de los nombres de objetos de base de datos. Por ejemplo, se puede utilizar una macro para comprobar si un nombre de tabla entre comillas distingue entre mayúsculas y minúsculas y si se almacena como mayúsculas y minúsculas en el servidor de la base de datos. Estas macros se definen en el archivo usrdecs.h.

Tabla 20 Macros para la comprobación de metadatos

Macro	Lo que verifica
supportsMixedCaseIdentifiers( nameMeta, DbObjType )	Si la base de datos trata un nombre entre comillas de un tipo de dato especificado como sensible a mayúsculas/minúsculas y almacena el nombre en mayúsculas y minúsculas.
supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )	Si la base de datos trata el nombre entre comillas en mayúsculas y minúsculas de un tipo de dato especificado como sensible a mayúsculas y minúsculas y almacena el nombre en mayúsculas y minúsculas.
storesLowerCaseIdentifiers( nameMeta, DbObjType )	Si la base de datos trata el nombre entre comillas de un tipo de dato especificado como no sensible a mayúsculas/minúsculas y almacena el nombre en minúsculas.
storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )	Si la base de datos trata el nombre entre comillas en mayúsculas y minúsculas de un tipo de dato especificado como no sensible a mayúsculas/minúsculas y almacena el nombre en minúsculas.
storesMixedCaseIdentifiers( nameMeta, DbObjType )	Si la base de datos trata el nombre entre comillas de un tipo de dato especificado como no sensible a mayúsculas/minúsculas y almacena el nombre en mayúsculas y minúsculas.
storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )	Si la base de datos trata el nombre entre comillas en mayúsculas y minúsculas de un tipo de dato especificado como no sensible a mayúsculas y minúsculas y almacena el nombre en mayúsculas y minúsculas.
storesUpperCaseIdentifiers( nameMeta, DbObjType )	Si la base de datos trata el nombre entre comillas de un tipo de dato especificado como no sensible a mayúsculas/minúsculas y almacena el nombre en mayúsculas.
storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )	Si la base de datos trata el nombre entre comillas en mayúsculas de un tipo de dato especificado como no sensible a mayúsculas/minúsculas y almacena el nombre en mayúsculas.

Descripción del Formato de Caracteres

El parámetro de entrada column_value_mode describe el formato de caracteres de los datos que se están procesando y se utiliza en varios de los códigos de función. En la siguiente tabla se describe el significado de los códigos de formato EXIT_FN_RAW_FORMAT, EXIT_FN_CHAR_FORMAT y EXIT_FN_CNVTED_SESS_FORMAT, por tipo de dato.

Cuadro 21 column_value_mode_matrix Significados

Tipo de dato	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
CHAR "abc"	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna 0000 0004 61 62 63 20	"abc" codificado en ASCII o EBCDIC. NULL terminado. Los espacios de revestimiento se recortan.	"abc" codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado. Los espacios de entrada se recortan por defecto a menos que se especifique el parámetro GLOBALS NOTRIMSPACES.
NCHAR 0061 0062 0063 0020	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna. 0000 0008 00 61 0062 0063 0020	"abc" (codificado en UTF8) o truncado en el primer byte, según si NCHAR se trata como UTF-8. NULL terminado. Se recortan los espacios finales.	"abc" codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado. Los espacios de entrada se recortan por defecto a menos que se especifique el parámetro GLOBALS NOTRIMSPACES.
VARCHAR2 "abc"	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	"abc" codificado en ASCII o EBCDIC. NULL terminado. Sin recortes.	"abc" codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado. Sin recortes.
NVARCHAR2 0061 0062 0063 0020	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	"abc" (codificado en UTF8) o truncado en el primer byte, según si NVARCHAR2 se trata como UTF-8. NULL terminado. Sin recortes.	"abc"codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado. Sin recortes.
CLOB	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	Similar a VARCHAR2, pero solo genera una salida de hasta 4K bytes. NULL Terminado. Sin recortes.	Similar a VARCHAR2, pero solo se solicitan datos de salida en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado. Sin recortes.
NCLOB	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	Similar a NVARCHAR2, pero solo genera una salida de hasta 4K bytes. NULL terminado. Sin recortes.	Similar a NVARCHAR2, pero solo se solicitan datos de salida en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado. Sin recortes.
NUMBER 123.89	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	"123.89" codificado en ASCII o EBCDIC. NULL terminado.	"123.89" codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado.
DATE 31-May-11	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	"2011-05-31" codificado en ASCII o EBCDIC. NULL terminado.	"2011-05-31" codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado.
TIMESTAMP 31-May-11 12.00.00 AM	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	"2011-05-31 12.00.00 AM" codificado en ASCII o EBCDIC. NULL terminado.	"2011-05-31 12.00.00 AM" codificado en el juego de caracteres de la sesión de salida de usuario. NOT NULL terminado.
Interval Year to Month or Interval Day to Second	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	N/D	N/D
RAW	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna	Indicador nulo de 2 bytes + Información de longitud de 2 bytes + valor de columna

Actualización de salidas de usuario

El archivo usrdecs.h tiene versiones para permitir la compatibilidad con versiones anteriores con salidas de usuario existentes cuando se agregan mejoras o actualizaciones, como nuevas funciones o cambios estructurales, a una nueva versión de Oracle GoldenGate. La versión del archivo usrdecs.h se imprime en el archivo de informe al iniciar Replicat o Extract.

Para utilizar la nueva funcionalidad de salida de usuario, debe recompilar las rutinas para incluir el nuevo archivo usrdecs. No es necesario volver a compilar las rutinas que no utilizan nuevas funciones.

Visualización de ejemplos de cómo utilizar las funciones de salida de usuario

Oracle GoldenGate instala los siguientes archivos de salida de usuario de ejemplo en el directorio UserExitExamples del directorio de instalación de Oracle GoldenGate:

• exitdemo.c muestra cómo inicializar la salida de usuario, emitir devoluciones de llamada en determinados puntos de salida y modificar datos. También muestra cómo recuperar el nombre de tabla totalmente cualificado o una parte de metadatos específica, como el nombre del catálogo o contenedor, o el esquema, o simplemente el nombre de tabla no cualificado. Además, en esta demostración se muestra cómo procesar los datos DDL. La demostración no es específica de ningún tipo de base de datos.

• exitdemo_utf16.c muestra cómo utilizar los datos codificados con UTF16 (tanto los metadatos como los datos de columna) en las estructuras de devolución de llamada para la información intercambiada entre la salida de usuario y el proceso de emisor de llamada.

• exitdemo_more_recs.c muestra un ejemplo de cómo utilizar el mismo registro de entrada varias veces para generar varios registros de destino.

• exitdemo_lob.c muestra un ejemplo de cómo obtener acceso de lectura a los datos de LOB.

• exitdemo_pk_befores.c muestra cómo acceder a las partes de imagen antes y después de un registro de actualización de clave primaria, así como a las imágenes anteriores de actualizaciones regulares (actualizaciones no de clave). También muestra cómo obtener valores de fila de destino con SQLEXEC en el archivo de parámetros Replicat como medio para la detección de conflictos. Los valores recuperados resultantes del destino se asignan como registro de destino cuando entra en la salida de usuario.

Cada directorio contiene los archivos *.c, así como archivos make y un archivo readme.txt.