Utilizzo delle uscite utente per estendere le funzionalità di Oracle GoldenGate

Le uscite utente sono routine personalizzate scritte nel codice di programmazione C e chiamate durante l'elaborazione Extract o Replicat. Le uscite utente estendono e personalizzano le funzionalità dei processi Extract e Replicat con complessità e rischi minimi. Con le uscite utente, è possibile rispondere agli eventi del database quando si verificano, senza modificare i programmi di produzione.

Nota: se si utilizza CUSEREXITS, la variabile di ambiente LD_LIBRARY_PATH deve essere estesa. Per impostazione predefinita, la directory $OGG_HOME/lib fa parte della directory home del software Oracle GoldenGate. È separato dalla directory di distribuzione per progettazione. Se è necessario aggiungere ulteriori oggetti condivisi per le funzioni Uscita utente, si consiglia di non utilizzare la directory $OGG_HOME/lib e di scegliere una posizione diversa. Per CUSEREXITS, è necessario estendere la variabile di ambiente LD_LIBRARY_PATH a una posizione diversa.

Quando implementare le uscite utente

È possibile utilizzare le uscite utente come alternativa o insieme alle funzioni di conversione delle colonne disponibili in Oracle GoldenGate. Le uscite utente possono essere un'alternativa migliore alle funzioni integrate poiché un'uscita utente elabora i dati solo una volta (quando i dati vengono estratti) anziché due volte (una volta estratti i dati e una volta per eseguire la trasformazione).

Di seguito sono riportati alcuni modi in cui è possibile implementare le uscite utente.

• Eseguire operazioni aritmetiche, conversioni di date o ricerche di tabelle durante il mapping da una tabella all'altra.

• Implementare le funzioni di archiviazione dei record offline.

• Rispondi a eventi insoliti del database in modi personalizzati, ad esempio inviando un messaggio di posta elettronica o una pagina basata su un valore di output.

• Accumula totali e raccoglie statistiche.

• Manipolare un record.

• Riparare dati non validi.

• Calcolare la differenza netta in un record prima e dopo un aggiornamento.

• Accettare o rifiutare i record per l'estrazione o la replica in base a criteri complessi.

• Normalizzare un database durante la conversione.

Impostazione delle informazioni sui record Oracle GoldenGate disponibili per la routine

La base per l'elaborazione della maggior parte delle uscite utente è la funzione EXIT_CALL_PROCESS_RECORD. Per Extract, questa funzione viene richiamata poco prima dell'output di un buffer di record sul trail. Per Replicat, viene chiamato poco prima dell'applicazione di un record alla destinazione. Se nel file dei parametri viene specificato il mapping origine-destinazione, l'evento EXIT_CALL_PROCESS_RECORD viene eseguito dopo l'esecuzione del mapping.

Quando si chiama EXIT_CALL_PROCESS_RECORD, il buffer dei record e altre informazioni sui record sono disponibili tramite routine di callback. L'uscita utente può mappare, trasformare, pulire o eseguire qualsiasi altra operazione con il record di dati. Al termine, l'uscita utente può restituire uno stato che indica se il record deve essere elaborato o ignorato da Extract o Replicat.

Creazione delle uscite utente

Le istruzioni seguenti consentono di creare uscite utente su sistemi Windows e UNIX. Per ulteriori informazioni sui parametri e sulle funzioni descritti in queste istruzioni, vedere Riferimento per Oracle GoldenGate per Windows e UNIX.

Nota: per i nomi degli oggetti di database viene fatta distinzione tra maiuscole e minuscole. I nomi vengono restituiti esattamente come sono definiti nel database di hosting. I nomi oggetto devono essere completamente qualificati.

Per creare le uscite utente

1. Nel codice C, creare un oggetto condiviso (sistemi UNIX) o una DLL (Windows) e creare o esportare una routine da chiamare da Replicat. Questa routine è il punto di comunicazione tra Oracle GoldenGate e le routine. Chiamate la routine come volete. La routine deve accettare i parametri di uscita utente Oracle GoldenGate riportati di seguito.

   • EXIT_CALL_TYPE: indica quando, durante l'elaborazione, viene chiamata la routine.

   • EXIT_CALL_RESULT: fornisce una risposta alla routine.

   • EXIT_PARAMS: fornisce informazioni alla routine. Questa funzione consente di utilizzare l'opzione EXITPARAM dell'istruzione TABLE o MAP per passare un parametro che è una stringa letterale all'uscita utente. Valido solo durante la chiamata di uscita per elaborare un record specifico. Questa funzione consente inoltre di passare i parametri specificati con l'opzione PARAMS del parametro CUSEREXIT all'avvio della chiamata di uscita.

2. Nel codice sorgente includere il file usrdecs.h. Il file usrdecs.h è il file include per l'API user exit. Contiene definizioni di tipo, valori di stato restituito, codici funzione di callback e una serie di altre definizioni. Il file usrdecs.h viene installato nella directory Oracle GoldenGate. Non modificare il file.

3. Includere le routine di callback Oracle GoldenGate nell'uscita utente, se applicabile. Le routine di callback recuperano le informazioni sul contesto di record e applicazione e modificano il contenuto dei record di dati. Per implementare una routine di callback, utilizzare la funzione ERCALLBACK nell'oggetto condiviso. La routine di callback dell'utente si comporta in modo diverso in base al codice della funzione passato alla routine di callback.

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. Includere il parametro CUSEREXIT nel file dei parametri Replicat. Questo parametro accetta il nome dell'oggetto condiviso o della DLL e il nome della routine esportata che deve essere chiamata da Replicat. È possibile specificare il percorso completo dell'oggetto condiviso o della DLL oppure lasciare che la strategia di ricerca standard del sistema operativo individui l'oggetto condiviso.

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.

Esempio 9-41 Esempio di sintassi base, UNIX

CUSEREXIT eruserexit.so MyUserExit

Esempio 9-42 Sintassi di base, Windows

CUSEREXIT eruserexit.dll MyUserExit

Conversione del set di caratteri di supporto nelle uscite utente

Per mantenere l'integrità dei dati, un'uscita utente deve comprendere il set di caratteri dei dati di tipo carattere scambiati con un processo Oracle GoldenGate. La logica di uscita utente di Oracle GoldenGate fornisce il supporto della globalizzazione per:

• metadati del database basati su caratteri, ad esempio i nomi di cataloghi, schemi, tabelle e colonne

• i valori delle colonne di tipo carattere, ad esempio CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2 e NCLOB, nonché i numeri basati su stringhe, la data e l'ora e gli intervalli.

La conversione corretta tra set di caratteri consente di confrontare, manipolare, convertire e mappare correttamente i dati delle colonne da un tipo di database e set di caratteri a un altro. La maggior parte di questa elaborazione viene eseguita quando viene chiamato il tipo di chiamata EXIT_CALL_PROCESS_RECORD e il buffer dei record e altre informazioni sui record vengono resi disponibili tramite routine di callback.

L'uscita utente dispone di un proprio set di caratteri di sessione. Questo è definito dalle funzioni di callback GET_SESSION_CHARSET e SET_SESSION_CHARSET. Il processo chiamante fornisce la conversione tra set di caratteri se il set di caratteri dell'uscita utente è diverso dal contesto di hosting del processo.

Per abilitare questo supporto nelle uscite utente, è disponibile il codice della funzione di callback GET_DATABASE_METADATA. Questa funzione consente all'uscita utente di ottenere i metadati del database, ad esempio le impostazioni nazionali e il set di caratteri dei dati di tipo carattere scambiati con il processo che lo chiama (Extract, Data Pump, Replicat). Restituisce inoltre il modo in cui il database tratta la distinzione tra maiuscole e minuscole dei nomi degli oggetti, il modo in cui tratta i nomi tra virgolette e senza virgolette e il modo in cui memorizza i nomi degli oggetti.

Per ulteriori informazioni su questi componenti, vedere Riferimento per Oracle GoldenGate per Windows e UNIX.

Utilizzo delle macro per controllare i metadati dei nomi

Il nome oggetto passato dall'API user exit è il nome esatto codificato nel set di caratteri della sessione user-exit ed esattamente lo stesso nome che viene recuperato dal database. Se l'uscita utente confronta il nome dell'oggetto con una stringa letterale, l'uscita utente deve recuperare le impostazioni nazionali del database e quindi normalizzare la stringa in modo che venga confrontata con il nome dell'oggetto nella stessa codifica.

Oracle GoldenGate fornisce le macro seguenti che possono essere richiamate dall'uscita utente per controllare i metadati dei nomi degli oggetti di database. Ad esempio, è possibile utilizzare una macro per verificare se un nome di tabella tra virgolette fa distinzione tra maiuscole e minuscole e se viene memorizzato come maiuscole e minuscole nel database server. Queste macro sono definite nel file usrdecs.h.

Macro tabella 20 per il controllo dei metadati

Macro	Cosa verifica
supportsMixedCaseIdentifiers( nameMeta, DbObjType )	Indica se il database considera un nome senza virgolette misto di un tipo di dati specificato come con distinzione tra maiuscole e minuscole e memorizza il nome in lettere maiuscole e minuscole.
supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )	Indica se il database considera il nome racchiuso tra maiuscole e minuscole di un tipo di dati specificato come con distinzione tra maiuscole e minuscole e memorizza il nome in lettere maiuscole e minuscole.
storesLowerCaseIdentifiers( nameMeta, DbObjType )	Indica se il database considera il nome senza virgolette di un tipo di dati specificato come senza distinzione tra maiuscole e minuscole e memorizza il nome in minuscole.
storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )	Indica se il database considera il nome racchiuso tra maiuscole e minuscole di un tipo di dati specificato come senza distinzione tra maiuscole e minuscole e memorizza il nome in minuscole.
storesMixedCaseIdentifiers( nameMeta, DbObjType )	Indica se il database considera il nome senza virgolette di un tipo di dati specificato come senza distinzione tra maiuscole e minuscole e memorizza il nome in lettere maiuscole e minuscole.
storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )	Indica se il database considera il nome racchiuso tra maiuscole e minuscole di un tipo di dati specificato come senza distinzione tra maiuscole e minuscole e memorizza il nome in lettere maiuscole e minuscole.
storesUpperCaseIdentifiers( nameMeta, DbObjType )	Indica se il database considera il nome senza virgolette di un tipo di dati specificato come senza distinzione tra maiuscole e minuscole e memorizza il nome in maiuscolo.
storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )	Indica se il database considera il nome racchiuso tra maiuscole e minuscole di un tipo di dati specificato come senza distinzione tra maiuscole e minuscole e memorizza il nome in lettere maiuscole.

Descrizione del formato di carattere

Il parametro di input column_value_mode descrive il formato dei caratteri dei dati in fase di elaborazione e viene utilizzato in diversi codici funzione. Nella tabella seguente viene descritto il significato dei codici formato EXIT_FN_RAW_FORMAT, EXIT_FN_CHAR_FORMAT e EXIT_FN_CNVTED_SESS_FORMAT, per tipo di dati.

Significati della Tabella 21 column_value_mode_matrix

Tipo di dati	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
CHAR "abc"	Indicatore nullo a 2 byte + Informazioni sulla lunghezza di 2 byte + valore colonna 0000 0004 61 62 63 20	"abc" codificato in ASCII o EBCDIC. NULL terminato. Gli spazi di adattamento sono tagliati.	"abc" codificato nel set di caratteri della sessione user exit. NOT NULL terminato. Gli spazi di adattamento vengono tagliati per impostazione predefinita a meno che non venga specificato il parametro GLOBALS NOTRIMSPACES.
NCHAR 0061 0062 0063 0020	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore della colonna. 0000 0008 00 61 0062 0063 0020	"abc" (codificato in UTF8) o troncato al primo byte, a seconda che NCHAR sia trattato come UTF-8. NULL terminato. Gli spazi finali sono tagliati.	"abc" codificato nel set di caratteri della sessione user exit. NOT NULL terminato. Gli spazi di adattamento vengono tagliati per impostazione predefinita a meno che non venga specificato il parametro GLOBALS NOTRIMSPACES.
VARCHAR2 "abc"	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	"abc" codificato in ASCII o EBCDIC. NULL terminato. Nessuna troncatura.	"abc" codificato nel set di caratteri della sessione user exit. NOT NULL terminato. Nessuna troncatura.
NVARCHAR2 0061 0062 0063 0020	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	"abc" (codificato in UTF8) o troncato al primo byte, a seconda che NVARCHAR2 sia trattato come UTF-8. NULL terminato. Nessuna troncatura.	"abc"codificato nel set di caratteri della sessione di uscita utente. NOT NULL terminato. Nessuna troncatura.
CLOB	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	Simile a VARCHAR2, ma solo output fino a 4K byte. NULL Terminato. Nessuna troncatura.	Simile a VARCHAR2, ma solo i dati di output richiesti nel set di caratteri della sessione di uscita utente. NOT NULL terminato. Nessuna troncatura.
NCLOB	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	Simile a NVARCHAR2, ma solo output fino a 4K byte. NULL terminato. Nessuna troncatura.	Simile a NVARCHAR2, ma solo i dati di output richiesti nel set di caratteri della sessione di uscita utente. NOT NULL terminato. Nessuna troncatura.
NUMBER 123.89	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	"123.89" codificato in ASCII o EBCDIC. NULL terminato.	"123.89" codificato nel set di caratteri della sessione di uscita utente. NOT NULL terminato.
DATE 31-May-11	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	"2011-05-31" codificato in ASCII o EBCDIC. NULL terminato.	"2011-05-31" codificato nel set di caratteri della sessione user exit. NOT NULL terminato.
TIMESTAMP 31-May-11 12.00.00 AM	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	"2011-05-31 12.00.00 AM" codificato in ASCII o EBCDIC. NULL terminato.	"2011-05-31 12.00.00 AM" codificato nel set di caratteri della sessione user exit. NOT NULL terminato.
Interval Year to Month or Interval Day to Second	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	ND	ND
RAW	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna	Indicatore nullo a 2 byte + info lunghezza 2 byte + valore colonna

Aggiornamento delle uscite utente

Il file usrdecs.h dispone di un controllo delle versioni per consentire la compatibilità con le versioni precedenti con le uscite utente esistenti quando miglioramenti o aggiornamenti, ad esempio nuove funzioni o modifiche strutturali, vengono aggiunti a una nuova release di Oracle GoldenGate. La versione del file usrdecs.h viene stampata nel file di report all'avvio di Replicat o Extract.

Per utilizzare la nuova funzionalità di user exit, è necessario ricompilare le routine per includere il nuovo file usrdecs. Non è necessario ricompilare le routine che non utilizzano nuove funzioni.

Visualizzazione di esempi di utilizzo delle funzioni di uscita utente

Oracle GoldenGate installa i seguenti file di uscita utente di esempio nella directory UserExitExamples della directory di installazione di Oracle GoldenGate:

• exitdemo.c mostra come inizializzare l'uscita utente, emettere callback in determinati punti di uscita e modificare i dati. Viene inoltre illustrato come recuperare il nome della tabella completamente qualificato o una parte di metadati specifica, ad esempio il nome del catalogo o del contenitore, lo schema o solo il nome della tabella non qualificato. Inoltre, questa demo mostra come elaborare i dati DDL. La demo non è specifica per alcun tipo di database.

• exitdemo_utf16.c mostra come utilizzare i dati con codifica UTF16 (sia metadati che dati di colonna) nelle strutture di callback per le informazioni scambiate tra l'uscita utente e il processo chiamante.

• In exitdemo_more_recs.c viene illustrato un esempio di come utilizzare più volte lo stesso record di input per generare diversi record di destinazione.

• exitdemo_lob.c mostra un esempio di come ottenere l'accesso in lettura ai dati LOB.

• exitdemo_pk_befores.c mostra come accedere alle parti di immagine precedenti e successive di un record di aggiornamento della chiave primaria, nonché alle immagini precedenti di aggiornamenti regolari (aggiornamenti non chiave). Mostra inoltre come ottenere i valori delle righe di destinazione con SQLEXEC nel file dei parametri Replicat come mezzo per il rilevamento dei conflitti. I valori recuperati risultanti dalla destinazione vengono mappati come record di destinazione quando entra nell'uscita utente.

Ogni directory contiene i file *.c, makefiles e readme.txt.