Uso de Saídas do Usuário para Estender os Recursos do Oracle GoldenGate

As saídas do usuário são rotinas personalizadas que você grava no código de programação C e chama durante o processamento Extract ou Replicat. As saídas do usuário estendem e personalizam a funcionalidade dos processos Extract e Replicat com complexidade e risco mínimos. Com as saídas do usuário, você pode responder aos eventos do banco de dados quando eles ocorrerem, sem alterar os programas de produção.

Observação: Se você usar o CUSEREXITS, a variável de ambiente LD_LIBRARY_PATH precisará ser estendida. Por padrão, o diretório $OGG_HOME/lib faz parte do diretório Home do software Oracle GoldenGate. Ele é separado do diretório de Implantação por design. Se outros objetos compartilhados precisarem ser adicionados para funções de Saída do Usuário, recomenda-se que você não use o diretório $OGG_HOME/lib e escolha outro local. Para CUSEREXITS, você deve estender a variável de ambiente LD_LIBRARY_PATH para outro local.

Quando Implementar Saídas do Usuário

Você pode empregar saídas de usuário como uma alternativa ou em conjunto com as funções de conversão de coluna disponíveis no Oracle GoldenGate. As saídas de usuário podem ser uma alternativa melhor às funções incorporadas porque uma saída de usuário processa dados apenas uma vez (quando os dados são extraídos) em vez de duas vezes (uma vez quando os dados são extraídos e uma vez para realizar a transformação).

Veja a seguir algumas maneiras de implementar saídas do usuário:

• Executar operações aritméticas, conversões de data ou pesquisas de tabela durante o mapeamento de uma tabela para outra.

• Implementar funções de arquivamento de registro off-line.

• Responda a eventos incomuns do banco de dados de maneiras personalizadas, por exemplo, enviando uma mensagem de e-mail ou uma página com base em um valor de saída.

• Acumular totais e reunir estatísticas.

• Manipular um registro.

• Reparar dados inválidos.

• Calcular a diferença líquida em um registro antes e depois de uma atualização.

• Aceite ou rejeite registros para extração ou replicação com base em critérios complexos.

• Normalizar um banco de dados durante a conversão.

Disponibilizando Informações de Registro do Oracle GoldenGate para a Rotina

A base para a maioria do processamento de saída do usuário é a função EXIT_CALL_PROCESS_RECORD. Para Extract, essa função é chamada pouco antes de um buffer de registro ser enviado para a trilha. Para Replicat, ele é chamado pouco antes de um registro ser aplicado ao destino. Se o mapeamento de origem-destino for especificado no arquivo de parâmetros, o evento EXIT_CALL_PROCESS_RECORD ocorrerá após a execução do mapeamento.

Quando o EXIT_CALL_PROCESS_RECORD é chamado, o buffer de registro e outras informações de registro ficam disponíveis para ele por meio de rotinas de callback. A saída do usuário pode mapear, transformar, limpar ou executar qualquer outra operação com o registro de dados. Quando terminar, a saída do usuário poderá retornar um status indicando se o registro deve ser processado ou ignorado pelo processo Extract ou Replicat.

Criando Saídas do Usuário

As instruções a seguir ajudam a criar saídas de usuário em sistemas Windows e UNIX. Para obter mais informações sobre os parâmetros e funções descritos nestas instruções, consulte Reference for Oracle GoldenGate for Windows and UNIX.

Observação: As saídas do usuário fazem distinção entre maiúsculas e minúsculas para nomes de objetos de banco de dados. Os nomes são retornados exatamente como são definidos no banco de dados de hospedagem. Os nomes de objeto devem ser totalmente qualificados.

Para Criar Saídas do Usuário

1. No código C, crie um objeto compartilhado (sistemas UNIX) ou uma DLL (Windows) e crie ou exporte uma rotina a ser chamada a partir do Replicat. Essa rotina é o ponto de comunicação entre o Oracle GoldenGate e suas rotinas. Nomeie a rotina como quiser. A rotina deve aceitar os seguintes parâmetros de saída de usuário do Oracle GoldenGate:

   • EXIT_CALL_TYPE: Indica quando, durante o processamento, a rotina é chamada.

   • EXIT_CALL_RESULT: Fornece uma resposta à rotina.

   • EXIT_PARAMS: Fornece informações à rotina. Essa função permite que você use a opção EXITPARAM da instrução TABLE ou MAP para passar um parâmetro que seja uma string literal para a saída do usuário. Isso só é válido durante a chamada de saída para processar um registro específico. Essa função também permite que você informe parâmetros especificados com a opção PARAMS do parâmetro CUSEREXIT na inicialização da chamada de saída.

2. No código-fonte, inclua o arquivo usrdecs.h. O arquivo usrdecs.h é o arquivo de inclusão da API de saída do usuário. Ele contém definições de tipo, valores de status de retorno, códigos de função de callback e várias outras definições. O arquivo usrdecs.h é instalado no diretório do Oracle GoldenGate. Não modifique este arquivo.

3. Incluir rotinas de callback do Oracle GoldenGate na saída do usuário quando aplicável. As rotinas de callback recuperam informações de contexto de registro e aplicativo e modificam o conteúdo dos registros de dados. Para implementar uma rotina de callback, use a função ERCALLBACK no objeto compartilhado. A rotina de callback do usuário se comporta de forma diferente com base no código de função que é passado para a rotina de 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. Inclua o parâmetro CUSEREXIT no arquivo de parâmetros Replicat. Este parâmetro aceita o nome do objeto compartilhado ou DLL e o nome da rotina exportada a ser chamada do Replicat. Você pode especificar o caminho completo do objeto compartilhado ou DLL ou permitir que a estratégia de pesquisa padrão do sistema operacional localize o objeto compartilhado.

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.

Exemplo 9-41 Exemplo de sintaxe básica, UNIX

CUSEREXIT eruserexit.so MyUserExit

Exemplo 9-42 Exemplo de Sintaxe Básica, Windows

CUSEREXIT eruserexit.dll MyUserExit

Suportando Conversão de Conjunto de Caracteres nas Saídas do Usuário

Para manter a integridade dos dados, uma saída de usuário precisa entender o conjunto de caracteres dos dados do tipo caractere que ele troca com um processo do Oracle GoldenGate. A lógica de saída de usuário do Oracle GoldenGate fornece suporte à globalização para:

• metadados de banco de dados baseados em caracteres, como nomes de catálogos, esquemas, tabelas e colunas

• os valores de colunas de tipo de caractere, como CHAR, VARCHAR2, CLOB, NCHAR, NVARCHAR2 e NCLOB, bem como números baseados em string, data-hora e intervalos.

A conversão adequada entre conjuntos de caracteres permite comparar, manipular, converter e mapear adequadamente os dados da coluna de um tipo de banco de dados e conjunto de caracteres para outro. A maior parte desse processamento é executada quando o tipo de chamada EXIT_CALL_PROCESS_RECORD é chamado e o buffer de registro e outras informações de registro são disponibilizados por meio de rotinas de callback.

A saída do usuário tem seu próprio conjunto de caracteres de sessão. Isso é definido pelas funções de callback GET_SESSION_CHARSET e SET_SESSION_CHARSET. O processo do chamador fornece conversão entre conjuntos de caracteres se o conjunto de caracteres da saída do usuário for diferente do contexto de hospedagem do processo.

Para ativar esse suporte em saídas de usuário, há o código de função de callback GET_DATABASE_METADATA. Essa função permite que a saída do usuário obtenha metadados do banco de dados, como a configuração regional e o conjunto de caracteres dos dados do tipo de caractere que ele troca com o processo que o chama (Extract, data pump, Replicat). Ele também retorna como o banco de dados trata a distinção entre maiúsculas e minúsculas de nomes de objetos, como trata nomes com aspas e sem aspas e como armazena nomes de objetos.

Para obter mais informações sobre esses componentes, consulte Reference for Oracle GoldenGate for Windows and UNIX.

Usando Macros para Verificar Metadados de Nome

O nome do objeto que é passado pela API de saída do usuário é o nome exato que é codificado no conjunto de caracteres da sessão de saída do usuário e exatamente o mesmo nome que é recuperado do banco de dados. Se a saída do usuário comparar o nome do objeto com uma string literal, a saída do usuário deverá recuperar a configuração regional do banco de dados e, em seguida, normalizar a string para que ela seja comparada com o nome do objeto na mesma codificação.

O Oracle GoldenGate fornece as macros a seguir que podem ser chamadas pela saída do usuário para verificar os metadados dos nomes de objetos do banco de dados. Por exemplo, uma macro pode ser usada para verificar se um nome de tabela entre aspas faz distinção entre maiúsculas e minúsculas e se ele é armazenado como maiúsculas e minúsculas no servidor de banco de dados. Essas macros são definidas no arquivo usrdecs.h.

Tabela 20 Macros para verificação de metadados

Macro	O que ele verifica
supportsMixedCaseIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata um nome sem aspas em letras maiúsculas e minúsculas de um tipo de dados especificado como distinção entre maiúsculas e minúsculas e armazena o nome em letras maiúsculas e minúsculas.
supportsMixedCaseQuotedIdentifiers( nameMeta, DBObjType )	Se o banco de dados trata o nome com aspas mistas de um tipo de dados especificado como fazendo distinção entre maiúsculas e minúsculas e armazena o nome em letras mistas.
storesLowerCaseIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata o nome sem aspas com maiúsculas e minúsculas de um tipo de dados especificado como sem distinção entre maiúsculas e minúsculas e armazena o nome em letras minúsculas.
storesLowerCaseQuotedIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata o nome entre aspas de um tipo de dados especificado como sem distinção entre maiúsculas e minúsculas e armazena o nome em letras minúsculas.
storesMixedCaseIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata o nome sem aspas com maiúsculas/minúsculas de um tipo de dados especificado como sem distinção entre maiúsculas e minúsculas e armazena o nome em letras mistas.
storesMixedCaseQuotedIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata o nome entre aspas de um tipo de dados especificado como sem distinção entre maiúsculas e minúsculas e armazena o nome em letras mistas.
storesUpperCaseIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata o nome sem aspas em letras maiúsculas de um tipo de dados especificado como sem distinção entre maiúsculas e minúsculas e armazena o nome em letras maiúsculas.
storesUpperCaseQuotedIdentifiers( nameMeta, DbObjType )	Se o banco de dados trata o nome entre aspas de um tipo de dados especificado como sem distinção entre maiúsculas e minúsculas e armazena o nome em letras maiúsculas.

Descrevendo o Formato de Caractere

O parâmetro de entrada column_value_mode descreve o formato de caractere dos dados que estão sendo processados e é usado em vários dos códigos de função. A tabela a seguir descreve o significado dos códigos de formato EXIT_FN_RAW_FORMAT, EXIT_FN_CHAR_FORMAT e EXIT_FN_CNVTED_SESS_FORMAT, por tipo de dados.

Tabela 21 column_value_mode_matrix Significados

Tipo de Dados	EXIT_FN_RAW_FORMAT	EXIT_FN_CHAR_FORMAT	EXIT_FN_CNVTED_SESS_FORMAT
CHAR "abc"	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes Valor da coluna + 0000 0004 61 62 63 20	"abc" codificado em ASCII ou EBCDIC. NULL encerrado. Os espaços de rejeito são aparados.	"abc" codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado. Os espaços de personalização são reduzidos por padrão, a menos que o parâmetro NOTRIMSPACES do GLOBALS seja especificado.
NCHAR 0061 0062 0063 0020	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna. 0000 0008 00 61 0062 0063 0020	"abc" (codificado em UTF8) ou truncado no primeiro byte, dependendo de NCHAR ser tratado como UTF-8. NULL encerrado. Os espaços à direita são aparados.	"abc" codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado. Os espaços de personalização são reduzidos por padrão, a menos que o parâmetro NOTRIMSPACES do GLOBALS seja especificado.
VARCHAR2 "abc"	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	"abc" codificado em ASCII ou EBCDIC. NULL encerrado. Sem redução.	"abc" codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado. Sem redução.
NVARCHAR2 0061 0062 0063 0020	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	"abc" (codificado em UTF8) ou truncado no primeiro byte, dependendo de NVARCHAR2 ser tratado como UTF-8. NULL encerrado. Sem redução.	"abc"codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado. Sem redução.
CLOB	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	Semelhante ao VARCHAR2, mas só gera até 4K bytes. NULL Rescindido. Sem redução.	Semelhante a VARCHAR2, mas somente dados de saída solicitados no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado. Sem redução.
NCLOB	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	Semelhante ao NVARCHAR2, mas só gera até 4K bytes. NULL encerrado. Sem redução.	Semelhante a NVARCHAR2, mas somente dados de saída solicitados no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado. Sem redução.
NUMBER 123.89	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	"123.89" codificado em ASCII ou EBCDIC. NULL encerrado.	"123.89" codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado.
DATE 31-May-11	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	"2011-05-31" codificado em ASCII ou EBCDIC. NULL encerrado.	"2011-05-31" codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado.
TIMESTAMP 31-May-11 12.00.00 AM	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	"2011-05-31 12.00.00 AM" codificado em ASCII ou EBCDIC. NULL encerrado.	"2011-05-31 12.00.00 AM" codificado no conjunto de caracteres da sessão de saída do usuário. NOT NULL encerrado.
Interval Year to Month or Interval Day to Second	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	NA	NA
RAW	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna	Indicador nulo de 2 bytes + Informações de comprimento de 2 bytes + valor da coluna

Fazendo Upgrade de Saídas do Usuário

O arquivo usrdecs.h tem controle de versão para permitir a compatibilidade retroativa com saídas de usuário existentes quando aprimoramentos ou upgrades, como novas funções ou alterações estruturais, são adicionados a uma nova release do Oracle GoldenGate. A versão do arquivo usrdecs.h é impressa no arquivo de relatório na inicialização do Replicat ou do Extract.

Para usar a nova funcionalidade de saída de usuário, recompile suas rotinas para incluir o novo arquivo usrdecs. Rotinas que não usam novos recursos não precisam ser recompiladas.

Exibindo Exemplos de Uso das Funções de Saída do Usuário

O Oracle GoldenGate instala os seguintes arquivos de saída de usuário de amostra no diretório UserExitExamples do diretório de instalação do Oracle GoldenGate:

• exitdemo.c mostra como inicializar a saída do usuário, emitir callbacks em determinados pontos de saída e modificar dados. Ele também demonstra como recuperar o nome de tabela totalmente qualificado ou uma parte de metadados específica, como o nome do catálogo ou contêiner, ou o esquema, ou apenas o nome de tabela não qualificado. Além disso, esta demonstração mostra como processar dados DDL. A demonstração não é específica de nenhum tipo de banco de dados.

• exitdemo_utf16.c mostra como usar dados codificados por UTF16 (dados de metadados e de coluna) nas estruturas de callback para obter informações trocadas entre a saída do usuário e o processo do chamador.

• O exitdemo_more_recs.c mostra um exemplo de como usar o mesmo registro de entrada várias vezes para gerar vários registros de destino.

• exitdemo_lob.c mostra um exemplo de como obter acesso de leitura aos dados do LOB.

• exitdemo_pk_befores.c mostra como acessar as partes de imagem antes e depois de um registro de atualização de chave primária, bem como as imagens antes de atualizações regulares (atualizações não relacionadas à chave). Ela também mostra como obter valores de linha de destino com SQLEXEC no arquivo de parâmetros Replicat como meio de detecção de conflito. Os valores extraídos resultantes do destino são mapeados como o registro de destino quando ele entra na saída do usuário.

Cada diretório contém os arquivos *.c, bem como arquivos makefiles e um arquivo readme.txt.