GET_COLUMN_VALUE_FROM_NAME

有效對象

擷取與 Replicat

說明

使用 GET_COLUMN_VALUE_FROM_NAME 函數，使用指定的資料欄名稱從資料記錄擷取資料欄值。資料欄值是使用者結束程式內大多數邏輯的基礎。您可以根據資料記錄內個別資料欄的值來建立複雜邏輯。

如果使用者結束程式的字元階段作業使用 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_NAME, &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>

傳回的資料欄值長度上限。通常，長度上限是資料欄值緩衝區的長度。如果指定 ASCII 格式 (請參閱 column_value_mode)，則資料欄值為空值終止，且長度上限應等於資料欄值的長度上限。

<column_name>

要傳回之資料欄值的資料欄名稱。

<column_value_mode>

表示資料欄值的字元集。

EXIT_FN_CHAR_FORMAT

ASCII 格式：此值為空值終止的 ASCII (或 EBCDIC) 字串 (子資料類型 UTF16_BE 的已知異常狀況，會轉換成 UTF 8)。注意：呈現給使用者結束程式時，可能會截斷資料欄值，因為該值會解譯為 ASCII 字串，且應為空值終止。0 的第一個值會成為字串終止字元。

• 日期的格式為 CCYY-MM-DD HH:MI:SS.FFFFFF，其中分數時間與資料庫有關。

• 數值為其字串格式。例如，123.45 表示為 "123.45"。

• 不可列印的字元或二進位值會轉換成十六進位表示法。

• 浮點數類型會以空值終止字串輸出至前 14 個有效數字。

EXIT_FN_RAW_FORMAT

內部 Oracle GoldenGate 正規格式：此格式包括兩個位元組的空值指標，以及兩個位元組的變數資料長度 (如果適用)。Oracle GoldenGate 不會針對任何字元資料類型執行此格式的字元集轉換。

EXIT_FN_CNVTED_SESS_CHAR_FORMAT

使用者結束字元集：只有在資料欄資料類型為：

• 以字元為基礎的類型，單一或多重位元組

• 以字串表示的數值類型

此格式不是空值終止格式。

<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 會讓 Extract 處理作業將影像前記錄寫入歷程檔，並同時對結束前影像的使用者進行 EXIT_CALL_PROCESS_RECORD 呼叫。

• INCLUDEUPDATEBEFORES 不會對使用者結束程式進行 EXIT_CALL_PROCESS_RECORD 呼叫，也不會在 Extract 的情況下，讓處理作業將先前的影像寫入歷程檔。

輸出

<column_value>

傳回資料欄值的指標。如果 column_value_mode 指定為 EXIT_FN_CHAR_FORMAT，就會以空值終止的 ASCII 字串傳回資料欄值；否則，會以 Oracle GoldenGate 內部正規格式傳回資料欄值。在 ASCII 格式中，日期會以下列格式傳回：

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

包含的分數時間取決於資料庫。

實際長

傳回之資料欄名稱的字串長度。當 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，則資料欄的長度中會包含空值終止字元。

字元 more_lob_data

指示在可儲存在基礎記錄中的初始 4K 之外，是否有更多 LOB 資料的旗標。當 LOB 大於 4K 限制時，它會儲存在 LOB 片段中。

您必須配置適當的記憶體大小，以包含傳回的值。Oracle GoldenGate 會隨時存取最多 8K 個資料的 LOB 資料欄，並填入緩衝區至使用者結束程式配置的數量。如果 LOB 大於配置的資料，則後續回呼必須取得資料欄資料總計，直到所有資料都傳送到使用者結束程式為止。

若要決定資料的結尾，請評估 more_lob_data。使用者結束程式會先將此旗標設為 CAR_NO_VAL 或 CHAR_YES_VAL，再存取新資料欄。如果此旗標在第一次回呼後仍初始化且未設為 CHAR_YES_VAL 或 CAR_NO_VAL，則下列其中一個為 true：

• 配置了足夠的記憶體來處理 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

範例

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