GET_COLUMN_VALUE_FROM_INDEX

有效对象

提取和复制

说明

使用 GET_COLUMN_VALUE_FROM_INDEX 函数可使用指定的列索引从数据记录中检索列值。列值是用户出口内大多数逻辑的基础。可以基于数据记录中单个列的值来构建复杂逻辑。可以指定返回值的字符格式。

如果使用 SET_SESSION_CHARSET 将用户出口的字符会话设置为 ucharset.h 文件的 ULIB_CS_DEFAULT 中定义的操作系统默认字符集以外的值，则将在会话字符集中解释用户出口和进程之间交换的字符数据。

仅当满足以下条件时，才会将列值设置为会话字符集：

列值为 SQL 字符类型（CHAR/VARCHAR2/CLOB、NCHAR/NVARCHAR2/NCLOB）、SQL 日期/时间戳/间隔/数字类型 )
column_value_mode 指示器设置为 EXIT_FN_CNVTED_SESS_CHAR_FORMAT。

语法

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

缓冲区

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;

输入

<column_value>

指向缓冲区的指针，用于接受返回的列值。

<max_value_length>

返回的列值的最大长度。通常，最大长度是列值缓冲区的长度。如果使用 column_value_mode 指定了 ASCII 格式，则列值将以 null 结尾，并且最大长度应等于列值的最大长度。

<column_index>

要返回的列值的列索引。

<column_value_mode>

指明列值的格式。

EXIT_FN_CHAR_FORMAT

ASCII 格式：该值是以 null 结尾的 ASCII（或 EBCDIC）字符串（子数据类型 UTF16_BE 已有例外，该类型转换为 UTF 8。）注意：当向用户出口显示列值时，列值可能会被截断，因为该值被解释为 ASCII 字符串，并且应该以 null 结尾。0 的第一个值将成为字符串终止符。

日期的格式为 CCYY-MM-DD HH:MI:SS.FFFFFF，其中小数时间与数据库相关。
数字值采用其字符串格式。例如，123.45 表示为 "123.45"。
不可打印的字符或二进制值将转换为十六进制表示法。
浮点类型以空结尾的字符串形式输出到前 14 个有效数字。

EXIT_FN_RAW_FORMAT

内部 Oracle GoldenGate 规范格式：此格式包括双字节 NULL 指示符和双字节变量数据长度（如果适用）。对于任何字符数据类型，Oracle GoldenGate 不会为此格式执行字符集转换。

EXIT_FN_CNVTED_SESS_CHAR_FORMAT

用户出口字符集：仅当列数据类型为：

基于字符的类型，单字节或多字节
具有字符串表示形式的数字类型

此格式未以 NULL 结尾。

<source_or_target>

以下项之一，用于指示是使用源数据记录还是目标数据记录检索列值。

EXIT_FN_SOURCE_VAL
EXIT_FN_TARGET_VAL

<requesting_before_after_ind>

在处理后图像记录时设置，并且您希望更新或主键更新的前图像列值。

要在处理主键更新或常规（非键）更新记录的“之后映像”时获取列的“之前”值，请将 requesting_before_after_ind 标志设置为 BEFORE_IMAGE_VAL。

要访问主键更新的键列的先前映像，无需执行任何其他操作。
要访问主键更新的非键列或常规更新的任何列，必须提供之前的映像。

未指定 requesting_before_after_ind 的显式输入时，默认设置为 AFTER_IMAGE_VAL（获取列的后图像）。

要使之前的映像可用，可以使用 GETUPDATEBEFORES 参数，也可以使用 CUSEREXIT 参数语句中的 INCLUDEUPDATEBEFORES 选项。

请注意：

GETUPDATEBEFORES 会导致提取进程将图像前记录写入线索，还会使用之前的图像对用户出口进行 EXIT_CALL_PROCESS_RECORD 调用。
INCLUDEUPDATEBEFORES 不会导致对用户出口的 EXIT_CALL_PROCESS_RECORD 调用，也不会导致进程将之前的映像写入线索。

<requesting_before_after_ind>

要获取列的之前图像，请将 char requesting_before_after_ind 标志设置为 BEFORE_IMAGE_VAL。要获取后面的映像，请将其设置为 AFTER_IMAGE_VAL。缺省情况下，始终使用后置映像，除非指定了前置映像。

要使之前的映像可用，可以对包含该表的 TABLE 语句使用 GETUPDATEBEFORES 参数，也可以使用 CUSEREXIT 参数语句中的 INCLUDEUPDATEBEFORES 选项。两者都会对 process_record 的用户出口产生相同的调用。

输出

<column_value>

指向返回列值的指针。如果将 column_value_mode 指定为 EXIT_FN_CHAR_FORMAT，则列值将作为以 Null 结尾的 ASCII 字符串返回；否则，列值将以 Oracle GoldenGate 内部规范格式返回。以 ASCII 格式返回日期，格式如下：

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

包含小数时间与数据库相关。

<actual_value_length>

返回的列名的字符串长度（以字节为单位）。当 column_value_mode 指定为 EXIT_FN_CHAR_FORMAT 时，实际长度不包含空终止符。

<null_value>

指示列值是否为空值的标志（0 或 1）。如果 null_value 标志为 1，则列值缓冲区将填充空字节。

<value_truncated>

指示值是否被截断的标志（0 或 1）。如果列值的长度超过最大缓冲区长度，则会发生截断。如果将 column_value_mode 指定为 EXIT_FN_CHAR_FORMAT，则 Null 终结符将包括在列的长度中。

char more_lob_data

指示初始 4K 以外是否存在更多可存储在基本记录中的 LOB 数据的标志。当 LOB 大于 4K 限制时，它存储在 LOB 片段中。

您必须分配适当的内存量以包含返回的值。Oracle GoldenGate 将始终访问 LOB 列（最多可访问 8K 个数据），将缓冲区填充到用户出口已分配的数量。If the LOB is larger than that which was allocated, subsequent callbacks are required to obtain the total column data, until all data has been sent to the user exit.

要确定数据的结尾，请评估 more_lob_data。在访问新列之前，用户出口会将此标志设置为 CHAR_NO_VAL 或 CHAR_YES_VAL。如果此标志在第一次回调后仍处于初始化状态且未设置为 CHAR_YES_VAL 或 CAR_NO_VAL，则以下情况之一为真：

分配了足够的内存来处理 LOB。
它不是 LOB。
它未超过基本线索记录大小的 4K 限制。

建议您获取源表元数据以确定列是否为 LOB。

返回值

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