GET_COLUMN_VALUE_FROM_NAME

Válido Para

Extract e Replicat

Descrição

Use a função GET_COLUMN_VALUE_FROM_NAME para recuperar o valor da coluna do registro de dados usando o nome da coluna especificado. Os valores de coluna são a base para a maioria da lógica dentro da saída do usuário. Você pode basear a lógica complexa nos valores de colunas individuais no registro de dados.

Se a sessão de caracteres da saída do usuário for definida com SET_SESSION_CHARSET para um valor diferente do conjunto de caracteres padrão do sistema operacional, conforme definido em ULIB_CS_DEFAULT no arquivo ucharset.h, os dados de caracteres que são trocados entre a saída do usuário e o processo serão interpretados no conjunto de caracteres da sessão.

Um valor de coluna será definido como o conjunto de caracteres da sessão somente se o seguinte for verdadeiro:

• O valor da coluna é um tipo de caractere SQL (CHAR/VARCHAR2/CLOB, NCHAR/NVARCHAR2/NCLOB), um tipo de data/timestamp/intervalo/número SQL

• O indicador column_value_mode é definido como EXIT_FN_CNVTED_SESS_CHAR_FORMAT.

Se o banco de dados fizer distinção entre maiúsculas e minúsculas, os nomes de objetos devem ser especificados na mesma letra que são definidos no banco de dados de hospedagem; caso contrário, a letra não importa.

Sintaxe

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

Buffer

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;

Entrada

<column_value>

Um ponteiro para um buffer a fim de aceitar o valor da coluna retornado.

<max_value_length>

O tamanho máximo do valor da coluna retornado. Normalmente, o tamanho máximo é o tamanho do buffer de valor da coluna. Se o formato ASCII for especificado (consulte column_value_mode), o valor da coluna será encerrado como nulo e o tamanho máximo deverá ser igual ao tamanho máximo do valor da coluna.

<column_name>

O nome da coluna para o valor da coluna a ser retornado.

<column_value_mode>

Indica o conjunto de caracteres do valor da coluna.

EXIT_FN_CHAR_FORMAT

Formato ASCII: O valor é uma string ASCII (ou EBCDIC) terminada com nulo (com uma exceção conhecida para o tipo de subdados UTF16_BE, que é convertido em UTF 8.) Observação: Um valor de coluna pode ser truncado quando apresentado a uma saída de usuário, porque o valor é interpretado como uma string ASCII e deve ser encerrado como nulo. O primeiro valor de 0 se torna o terminador de string.

• As datas estão no formato CCYY-MM-DD HH:MI:SS.FFFFFF, no qual o tempo fracionário depende do banco de dados.

• Os valores numéricos estão no formato de string. Por exemplo, 123.45 é representado como "123.45".

• Caracteres não imprimíveis ou valores binários são convertidos em notação hexadecimal.

• Os tipos de ponto flutuante são gerados como strings terminadas como nulas, com os primeiros 14 dígitos significativos.

EXIT_FN_RAW_FORMAT

Formato canônico interno do Oracle GoldenGate: Este formato inclui um indicador nulo de dois bytes e um tamanho de dados variável de dois bytes, quando aplicável. O Oracle GoldenGate não faz nenhuma conversão de conjuntos de caracteres para esse formato em nenhum tipo de dados de caracteres.

EXIT_FN_CNVTED_SESS_CHAR_FORMAT

Conjunto de caracteres de saída do usuário: Isso só se aplica se o tipo de dados da coluna for:

• um tipo baseado em caracteres, único ou multibytes

• um tipo numérico com uma representação de string

Este formato não é encerrado como nulo.

<source_or_target>

Uma das opções a seguir indica se o registro de dados de origem ou de destino deve ser usado para recuperar o valor da coluna.

EXIT_FN_SOURCE_VAL
EXIT_FN_TARGET_VAL

<requesting_before_after_ind>

Defina ao processar um registro de imagem posterior e você deseja as colunas anteriores de uma atualização ou de uma atualização de chave primária.

Para obter o valor "before" da coluna ao processar uma "after image" de uma atualização de chave primária ou um registro de atualização regular (não chave), defina o flag requesting_before_after_ind como BEFORE_IMAGE_VAL.

• Para acessar a imagem anterior das colunas de chave de uma atualização de chave primária, nada mais é necessário.

• Para acessar colunas que não sejam de chave de uma atualização de chave primária ou de qualquer coluna de uma atualização regular, a imagem anterior deve estar disponível.

A definição padrão é AFTER_IMAGE_VAL (obtenha a imagem posterior da coluna) quando uma entrada explícita para requesting_before_after_ind não for especificada.

Para disponibilizar uma imagem anterior, você pode usar o parâmetro GETUPDATEBEFORES ou pode usar a opção INCLUDEUPDATEBEFORES na instrução de parâmetro CUSEREXIT.

Observe que:

• GETUPDATEBEFORES faz com que um processo Extract grave registros de imagem anterior na trilha e também faça uma chamada EXIT_CALL_PROCESS_RECORD para a saída do usuário com as imagens anteriores.

• INCLUDEUPDATEBEFORES não causa uma chamada EXIT_CALL_PROCESS_RECORD para a saída do usuário nem, no caso do processo Extract, faz com que o processo grave a imagem anterior na trilha.

Saída

<column_value>

Um ponteiro para o valor da coluna retornada. Se column_value_mode for especificado como EXIT_FN_CHAR_FORMAT, o valor da coluna será retornado como uma string ASCII terminada com nulo; caso contrário, o valor da coluna será retornado no formato canônico interno do Oracle GoldenGate. No formato ASCII, as datas são retornadas no seguinte formato:

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

A inclusão do tempo fracionário é dependente do banco de dados.

tamanho real

O tamanho da string do nome da coluna retornada. O tamanho real não inclui um terminador nulo quando column_value_mode é especificado como EXIT_FN_CHAR_FORMAT.

<null_value>

Um flag (0 ou 1) que indica se o valor da coluna é ou não nulo. Se o flag null_value for 1, o buffer de valor da coluna será preenchido com bytes nulos.

<value_truncated>

Um flag (0 ou 1) indicando se o valor foi truncado ou não. Truncação ocorre se o tamanho do valor da coluna exceder o tamanho máximo do buffer. Se column_value_mode tiver sido especificado como EXIT_FN_CHAR_FORMAT, o terminador nulo será incluído no tamanho da coluna.

char more_lob_data

Um flag que indica se mais dados do LOB estão presentes além do 4K inicial que pode ser armazenado no registro base. Quando um LOB é maior que o limite do 4K, ele é armazenado em fragmentos do LOB.

Você deve alocar a quantidade apropriada de memória para conter os valores retornados. O Oracle GoldenGate acessará as colunas LOB até 8K de dados o tempo todo, preenchendo o buffer com a quantidade alocada pela saída do usuário. Se o LOB for maior que o que foi alocado, os callbacks subsequentes serão necessários para obter o total de dados da coluna, até que todos os dados tenham sido enviados para a saída do usuário.

Para determinar o fim dos dados, avalie more_lob_data. A saída do usuário define esse flag como CAR_NO_VAL ou CHAR_YES_VAL antes de acessar uma nova coluna. Se esse flag ainda for inicializado após o primeiro callback e não for definido como CHAR_YES_VAL ou CAR_NO_VAL, uma das seguintes afirmações será verdadeira:

• Memória suficiente alocada para tratar o LOB.

• Não é um LOB.

• Ele não estava acima do limite 4K do tamanho do registro de trilha base.

É recomendável obter os metadados da tabela de origem para determinar se uma coluna pode ser uma LOB.

Valores de Retorno

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

Exemplo

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);