8 User Exit Functions

This chapter describes the Oracle GoldenGate user exit functions and their syntax and includes the following topics:

For more information about using Oracle GoldenGate user exits, see Administering Oracle GoldenGate.

Topics:

8.1 Using EXIT_CALL_TYPE

Use EXIT_CALL_TYPE to indicate when, during processing, the Extract or Replicat process (the caller) calls a user exit routine. A process can call a routine with the following calls.

Table 8-1 User Exit Calls

Call type	Processing point
`EXIT_CALL_ABORT_TRANS`	Valid when the `RECOVERYOPTIONS` mode is `APPEND` (the default). Called when a data pump or Replicat reads a `RESTART ABEND` record from the trail, placed there by a writer process that abended. (The writer process can be the primary Extract writing to a local trail read by a data pump, or a data pump writing to a remote trail read by Replicat.) This call type enables the user exit to abort or discard the transaction that was left incomplete when the writer process stopped, and then to recover and resume processing at the start of the previous completed transaction.
`EXIT_CALL_BEGIN_TRANS`	Called just before either of the following: a `BEGIN` record of a transaction that is read by a data pump the start of a Replicat transaction
`EXIT_CALL_CHECKPOINT`	Called just before an Extract or Replicat checkpoint is written.
`EXIT_CALL_DISCARD_ASCII_RECORD`	Called during Extract processing before an ASCII input record is written to the discard file. The associated ASCII buffer can be retrieved and manipulated by the user exit using callback routines. This call type is not applicable for use with the Replicat process.
`EXIT_CALL_DISCARD_RECORD`	Called during Replicat processing before a record is written to the discard file. Records can be discarded for several reasons, such as when a value in the Oracle GoldenGate change record is different from the current version in the target table.The associated discard buffer can be retrieved and manipulated by the user exit using callback routines. This call type is not applicable for use with the Extract process.
`EXIT_CALL_END_TRANS`	Called just after either of the following: an `END` record of a transaction that is read by a data pump the last record in a Replicat transaction
`EXIT_CALL_FATAL_ERROR`	Called during Extract or Replicat processing just before Oracle GoldenGate terminates after a fatal error.
`EXIT_CALL_PROCESS_MARKER`	Called during Replicat processing when a marker from a NonStop server is read from the trail, and before writing to the marker history file.
`EXIT_CALL_PROCESS_RECORD`	For Extract, called before a record buffer is output to the trail. For Replicat, called just before a replicated operation is performed. This call is the basis of most user exit processing. When `EXIT_CALL_PROCESS_RECORD` is called, the record buffer and other record information are available to the user exit through callback routines. If source-target mapping is specified in the parameter file, the mapping is performed before the `EXIT_CALL_PROCESS_RECORD` event takes place. The user exit can map, transform, clean, or perform virtually any other operation with the record. The user exit can return a status indicating whether the caller should process or ignore the record.
`EXIT_CALL_START`	Called at the start of processing. The user exit can perform initialization work, such as opening files and initializing variables.
`EXIT_CALL_STOP`	Called before the process stops gracefully or ends abnormally. The user exit can perform completion work, such as closing files or outputting totals.
`EXIT_CALL_RESULT`	Set by the user exit routines to instruct the caller how to respond when each exit call completes.

8.2 SET_SESSION_CHARSET

Valid For

Extract and Replicat

Description

Use the SET_SESSION_CHARSET function to set the character set of the user exit. The character set of the user exit session indicates the encoding of any character-based callback structure members that are used between the user exit and the caller process (Extract, data pump, Replicat), including metadata such as (but not limited to):

database names and locales
table and column names
DDL text
error messages
character-type columns such as CHAR and NCHAR
date-time and numeric columns that are represented in string form

This function can be called at any time that the user exit has control. When the user exit sets the session character set, it takes effect immediately, and all character values start being converted to the specified set. The recommended place to call this function is with call type EXIT_CALL_START.

Note:

SET_SESSION_CHARSET is not thread-safe.

If SET_SESSION_CHARSET is not called, the session gets set to the default character set of the operating system, which is a predefined enumerated type value in ULIB_CS_DEFAULT in the ucharset.h file. When the session character set is a default from ULIB_CS_DEFAULT, no conversion is performed by Oracle GoldenGate for character-type values that are exchanged between the user exit and the caller process. In addition, the object-name metadata of the database are considered to be the default character set of the operating system. Keep in mind that the default may not be correct.

The character set of the user exit is printed to the report file when the user exit is loaded and when SET_SESSION_CHARSET is called. If the session character set is ULIB_CS_DEFAULT, there is a message stating that no column data character-set conversion is being performed.

For more information about globalization support, see Administering Oracle GoldenGate.

Syntax

#include usrdecs.h
short result_code;
session_def session_charset_def;
ERCALLBACK (SET_SESSION_CHARSET, &session_charset_def, &result_code);

Buffer

typedef struct
{
ULibCharSet  session_charset;
} session_def;

Input

session_charset: The valid values of the session character set are defined in the header file ucharset.h.

Output

None

Return Values

EXIT_FN_RET_OK