1. Reference for Oracle GoldenGate
  2. Oracle GoldenGate Common Components
  3. User Exit Functions
  4. SET_COLUMN_VALUE_BY_INDEX

SET_COLUMN_VALUE_BY_INDEX

Valid For

Extract and Replicat

Description

Use the SET_COLUMN_VALUE_BY_INDEX or SET_COLUMN_VALUE_BY_NAME function to modify a single column value without manipulating the entire data record. If the character session of the user exit is set with SET_SESSION_CHARSET to a value other than the default character set of the operating system, as defined in ULIB_CS_DEFAULT in the ucharset.h file, the character data that is exchanged between the user exit and the process is interpreted in the session character set.

A column value is set to the session character set only if the following is true:

  • The column value is a SQL character type (CHAR/VARCHAR2/CLOB, NCHAR/NVARCHAR2/NCLOB), a SQL date/timestamp/interval/number type)

  • The column_value_mode indicator is set to EXIT_FN_CNVTED_SESS_CHAR_FORMAT.

Syntax

#include "usrdecs.h"
short result_code;
column_def column;
ERCALLBACK (SET_COLUMN_VALUE_BY_INDEX, &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;

Input

column_value

A pointer to a buffer representing the new column value.

actual_value_length

The length of the new column value, in bytes. The actual length should not include the null terminator if the new column value is in ASCII format.

null_value

A flag (0 or 1) indicating whether the new column value is null. If the null_value flag is set to 1, the column value in the data record is set to null.

remove_column

A flag (0 or 1) indicating whether to remove the column from a compressed update if it exists. A compressed update is one in which only the changed column values are logged, not all of the column values. This flag should only be set if the operation type for the record is UPDATE_COMP_SQL_VAL or PK_UPDATE_SQL_VAL.

column_index

The column index of the new column value to be copied into the data record buffer. Column indexes start at zero.

column_value_mode

Indicates the format of the column value.

EXIT_FN_CHAR_FORMAT

ASCII format: The value is a null-terminated ASCII (or EBCDIC) string (with a known exception for the sub-data type UTF16_BE, which is converted to UTF8.)

Note:

A column value might be truncated when presented to a user exit, because the value is interpreted as an ASCII string and is supposed to be null-terminated. The first value of 0 becomes the string terminator.

  • Dates are in the format CCYY-MM-DD HH:MI:SS.FFFFFF, in which the fractional time is database-dependent.

  • Numeric values are in their string format. For example, 123.45 is represented as '123.45'.

  • Non-printable characters or binary values are converted to hexadecimal notation.

  • Floating point types are output as null-terminated strings, to the first 14 significant digits.

EXIT_FN_RAW_FORMAT

Internal Oracle GoldenGate canonical format: This format includes a two-byte null indicator and a two-byte variable data length when applicable. No character-set conversion is performed by Oracle GoldenGate for this format for any character data type.

EXIT_FN_CNVTED_SESS_CHAR_FORMAT

User exit character set: This only applies if the column data type is:

  • a character-based type, single or multi-byte

  • a numeric type with a string representation

This format is not null-terminated.

source_or_target

One of the following indicating whether the source or target record is being modified.

EXIT_FN_SOURCE_VAL
EXIT_FN_TARGET_VAL
requesting_before_after_ind

Set when setting a column value on a record io_type of UPDATE_COMP_PK_SQL_VAL (primary key update). Use one of the following to indicate which portion of the primary key update is to be accessed. The default is AFTER_IMAGE_VAL.

  • BEFORE_IMAGE_VAL

  • AFTER_IMAGE_VAL

Output

None

Return Values

EXIT_FN_RET_BAD_COLUMN_DATA
EXIT_FN_RET_INVALID_COLUMN
EXIT_FN_RET_INVALID_CONTEXT
EXIT_FN_RET_INVALID_PARAM
EXIT_FN_RET_OK
EXIT_FN_RET_NOT_SUPPORTED
EXIT_FN_RET_INVALID_COLUMN_TYPE