6 User Exit Functions

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

Section 6.1, "Calling a User Exit"
Section 6.2, "Summary of User Exit Functions"
Section 6.3, "Using EXIT_CALL_TYPE"
Section 6.4, "Using EXIT_CALL_RESULT"
Section 6.5, "Using EXIT_PARAMS"
Section 6.6, "Using ERCALLBACK"
Section 6.7, "Function Codes"

For more information about using Oracle GoldenGate user exits, see Administering Oracle GoldenGate for Windows and UNIX.

6.1 Calling a User Exit

Write the user exit routine in C programming code. Use the CUSEREXIT parameter to call the user exit from a Windows DLL or UNIX shared object at a defined exit point within Oracle GoldenGate processing. Your user exit routine must be able to accept different events and information from the Extract and Replicat processes, process the information as desired, and return a response and information to the caller (the Oracle GoldenGate process that called it). For more information and syntax for the CUSEREXIT parameter, see "CUSEREXIT".

6.2 Summary of User Exit Functions

Parameter	Description
`EXIT_CALL_TYPE`	Indicates when, during processing, the routine is called.
`EXIT_CALL_RESULT`	Provides a response to the routine.
`EXIT_PARAMS`	Supplies information to the routine.
`ERCALLBACK`	Implements a callback routine. Callback routines retrieve record and Oracle GoldenGate context information, and they modify the contents of data records.

6.3 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 6-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. When a user exit is used for a data-pump Extract that is configured in `PASSTHRU` mode, the user exit does not receive an `EXIT_CALL_PROCESS_RECORD` call. As a result, the user exit has no access to the DDL and DML operations. DDL operations are always processed by a data-pump Extract in `PASSTHRU` mode and cannot process DDL at all. If the data pump is configured in `NOPASSTHRU` mode (the default for DML), the user exit receives the `EXIT_CALL_PROCESS_RECORD` call only for DML operations. For more information, see PASSTHRU \| NOPASSTHRU.
`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.

6.4 Using EXIT_CALL_RESULT

Use EXIT_CALL_RESULT to provide a response to the routine.

Table 6-2 User Exit Responses

Call result	Description
`EXIT_ABEND_VAL`	Instructs the caller to terminate immediately.
`EXIT_IGNORE_VAL`	Rejects records for further processing. `EXIT_IGNORE_VAL` is appropriate when the user exit performs all the required processing for a record and there is no need to output or replicate the data record.
`EXIT_OK_VAL`	If the routine does nothing to respond to an event, `EXIT_OK_VAL` is assumed. If the exit call type is any of the following... `EXIT_CALL_PROCESS_RECORD` `EXIT_CALL_DISCARD_RECORD` `EXIT_CALL_DISCARD_ASCII_RECORD` ... and `EXIT_OK_VAL` is returned, then Oracle GoldenGate processes the record buffer that was returned by the user exit.
`EXIT_PROCESSED_REC_VAL`	Instructs Extract or Replicat to skip the record, but update the statistics that are printed to the report file for that table and for that operation type.
`EXIT_STOP_VAL`	Instructs the caller to stop processing gracefully. `EXIT_STOP_VAL` or `EXIT_ABEND_VAL` may be appropriate when an error condition occurs in the user exit.

6.5 Using EXIT_PARAMS

Use EXIT_PARAMS to supply information to the user exit routine, such as the program name and user-defined parameters. You can process a single data record multiple times.

Table 6-3 User Exit Input

Exit parameter	Description
`PROGRAM_NAME`	Specifies the full path and name of the calling process, for example `\ggs\extract` or `\ggs\replicat`. Use this parameter when loading an Oracle GoldenGate callback routine using the Windows API or to identify the calling program when user exits are used with both Extract and Replicat processing.
`FUNCTION_PARAM`	Allows you to pass a parameter that is a literal string to the user exit. Specify the parameter with the `EXITPARAM` option of the `TABLE` or `MAP` statement from which the parameter will be passed. See "`EXITPARAM 'parameter'`". This is only valid during the exit call to process a specific record. `FUNCTION_PARAM` can also be used at the exit call startup event to pass the parameters that are specified in the `PARAMS` option of the `CUSEREXIT` parameter. (See "CUSEREXIT".) This is only valid to supply a global parameter at exit startup.
`MORE_RECS_IND`	Set on return from an exit. For database records, determines whether Extract or Replicat processes the record again. This allows the user exit to output many records per record processed by Extract, a common function when converting Enscribe to SQL (data normalization). To request the same record again, set `MORE_RECS_IND` to `CHAR_NO_VAL` or `CHAR_YES_VAL`.

6.6 Using ERCALLBACK

Use ERCALLBACK to execute a callback routine. A user callback routine retrieves context information from the Extract or Replicat process and sets context values, including the record itself, when the call type is one of the following:

EXIT_CALL_PROCESS_RECORD
EXIT_CALL_DISCARD_RECORD
EXIT_CALL_DISCARD_ASCII_RECORD

Syntax

ERCALLBACK (function_code, buffer, result_code );

function_code: The function to be executed by the callback routine. The user callback routine behaves differently based on the function code passed to the callback routine. While some functions can be used for both Extract and Replicat, the validity of the function in one process or the other is dependent on the input parameters that are set for that function during the callback routine. See Section 6.7, "Function Codes" for a full description of available function codes.
buffer: A void pointer to a buffer containing a predefined structure associated with the specified function code.
result_code: The status of the function executed by the callback routine. The result code returned by the callback routine indicates whether or not the callback function was successful. A result code can be one of the values in Table 6-4.

Table 6-4 Result Codes

Code	Description
`EXIT_FN_RET_BAD_COLUMN_DATA`	Invalid data was encountered when retrieving or setting column data.
`EXIT_FN_RET_BAD_DATE_TIME`	A date, timestamp, or interval type `of` column contains an invalid date or time value.
`EXIT_FN_RET_BAD_NUMERIC_VALUE`	A numeric type of column contains an invalid numeric value.
`EXIT_FN_RET_COLUMN_NOT_FOUND`	The column was not found in a compressed update record (update by a database that only logs the values that were changed).
`EXIT_FN_RET_ENV_NOT_FOUND`	The specified environment value could not be found in the record.
`EXIT_FN_RET_EXCEEDED_MAX_LENGTH`	The metadata could not be retrieved because the name of the table or column did not fit in the allocated buffer.
`EXIT_FN_RET_FETCH_ERROR`	The record could not be fetched. View the error message to see the reason.
`EXIT_FN_RET_INCOMPLETE_DDL_REC`	An internal error occurred when processing the DDL record. The record is probably incomplete.
`EXIT_FN_RET_INVALID_CALLBACK_FNC_CD`	An invalid callback function code was passed to the callback routine.
`EXIT_FN_RET_INVALID_COLUMN`	A non-existent column was referred to in the function call.
`EXIT_FN_RET_INVALID_COLUMN_TYPE`	The routine is trying to manipulate a data type that is not supported by Oracle GoldenGate for that purpose.
`EXIT_FN_RET_INVALID_CONTEXT`	The callback function was called at an improper time.
`EXIT_FN_RET_INVALID_PARAM`	An invalid parameter was passed to the callback function.
`EXIT_FN_RET_NO_SRCDB_INSTANCE`	The source database instance could not be found.
`EXIT_FN_RET_NO_TGTDB_INSTANCE`	The target database instance could not be found.
`EXIT_FN_RET_NOT_SUPPORTED`	This function is not supported for this process.
`EXIT_FN_RET_OK`	The callback function succeeded.
`EXIT_FN_RET_SESSION_CS_CNV_ERR`	A `ULIB_ERR_INVALID_CHAR_FOUND` error was returned to the character-set conversion routine. The conversion failed.
`EXIT_FN_RET_TABLE_NOT_FOUND`	An invalid table name was specified.
`EXIT_FN_RET_TOKEN_NOT_FOUND`	The specified user token could not be found in the record.

6.7 Function Codes

Function codes determine the output of the callback routine. The callback routine expects the contents of the data buffer to match the structure of the specified function code. The callback routine function codes and their data buffers are described in the following sections. The following is a summary of available functions.

Table 6-5 Summary of Oracle GoldenGate Function Codes

Function code	Description
`COMPRESS_RECORD`	Use the `COMPRESS_RECORD` function when some, but not all, of a target table's columns are present after mapping and the entire record must be manipulated, rather than individual column values.
`DECOMPRESS_RECORD`	Use the `DECOMPRESS_RECORD` function when some, but not all, of a target table's columns are present after mapping and the entire record must be manipulated, rather than individual column values.
`GET_BASE_OBJECT_NAME`	Use the `GET_BASE_OBJECT_NAME` function to retrieve the fully qualified name of the base object of an object in a record.
`GET_BASE_OBJECT_NAME_ONLY`	Use the `GET_BASE_OBJECT_NAME_ONLY` function to retrieve only the name of the base object of an object in a record.
`GET_BASE_SCHEMA_NAME_ONLY`	Use the `GET_BASE_SCHEMA_NAME_ONLY` function to retrieve only the name of the schema of the base object of an object in a record.
`GET_BEFORE_AFTER_IND`	Use the `GET_BEFORE_AFTER_IND` function to determine whether a record is a before image or an after image of the database operation.
`GET_CATALOG_NAME_ONLY`	Use the `GET_CATALOG_NAME_ONLY` function to return the name of the database catalog.
`GET_COL_METADATA_FROM_INDEX`	Use the `GET_COL_METADATA_FROM_INDEX` function to determine the column metadata that is associated with a specified column index.
`GET_COL_METADATA_FROM_NAME`	Use the `GET_COL_METADATA_FROM_NAME` function to determine the column metadata that is associated with a specified column name.
`GET_COLUMN_INDEX_FROM_NAME`	Use the `GET_COLUMN_INDEX_FROM_NAME` function to determine the column index associated with a specified column name.
`GET_COLUMN_NAME_FROM_INDEX`	Use the `GET_COLUMN_NAME_FROM_INDEX` function to determine the column name associated with a specified column index.
`GET_COLUMN_VALUE_FROM_INDEX`	Use the `GET_COLUMN_VALUE_FROM_INDEX` function to return the column value from the data record using the specified column index.
`GET_COLUMN_VALUE_FROM_NAME`	Use the `GET_COLUMN_VALUE_FROM_NAME` function to return the column value from the data record by using the specified column name.
`GET_DATABASE_METADATA`	Use the `GET_DATABASE_METADATA` function to return database metadata.
`GET_DDL_RECORD_PROPERTIES`	Use the `GET_DDL_RECORD_PROPERTIES` function to return information about a DDL operation.
`GET_ENV_VALUE`	Use the `GET_ENV_VALUE` function to return information about the Oracle GoldenGate environment.
`GET_ERROR_INFO`	Use the `GET_ERROR_INFO` function to return error information associated with a discard record.
`GET_GMT_TIMESTAMP`	Use the `GET_GMT_TIMESTAMP` function to return the operation commit timestamp in GMT format.
`GET_MARKER_INFO`	Use the `GET_MARKER_INFO` function to return marker information when posting data. Use markers to trigger custom processing within a user exit.
`GET_OBJECT_NAME`	Returns the fully qualified two- or three-part name of a table or other object that is associated with the record that is being processed.
`GET_OBJECT_NAME_ONLY`	Returns the unqualified name of a table or other object that is associated with the record that is being processed.
`GET_OPERATION_TYPE`	Use the `GET_OPERATION_TYPE` function to determine the operation type associated with a record.
`GET_POSITION`	Use the `GET_POSITION` function is obtain a read position of an Extract data pump or Replicat in the Oracle GoldenGate trail.
`GET_RECORD_BUFFER`	Use the `GET_RECORD_BUFFER` function to obtain information for custom column conversions.
`GET_RECORD_LENGTH`	Use the `GET_RECORD_LENGTH` function to return the length of the data record.
`GET_RECORD_TYPE`	Use the `GET_RECORD_TYPE` function to return the type of record being processed
`GET_SCHEMA_NAME_ONLY`	Use the `GET_SCHEMA_NAME_ONLY` function to return only the schema name of a table.
`GET_SESSION_CHARSET`	Use the `GET_SESSION_CHARSET` function to return the character set of the user exit session.
`GET_STATISTICS`	Use the `GET_STATISTICS` function to return the current processing statistics for the Extract or Replicat process.
`GET_TABLE_COLUMN_COUNT`	Use the `GET_TABLE_COLUMN_COUNT` function to return the total number of columns in a table.
`GET_TABLE_METADATA`	Use the `GET_TABLE_METADATA` function to return metadata for the table that associated with the record that is being processed.
`GET_TABLE_NAME`	Use the `GET_TABLE_NAME` function to return the fully qualified two- or three-part name of the source or target table that is associated with the record that is being processed.
`GET_TABLE_NAME_ONLY`	Use the `GET_TABLE_NAME_ONLY` function to return only the unqualified name of the table that is associated with the record that is being processed.
`GET_TIMESTAMP`	Use the `GET_TIMESTAMP` function to return the I/O timestamp associated with a source data record.
`GET_TRANSACTION_IND`	Use the `GET_TRANSACTION_IND` function to determine whether a data record is the first, last or middle operation in a transaction,
`GET_USER_TOKEN_VALUE`	Use the `GET_USER_TOKEN_VALUE` function to obtain the value of a user token from a trail record.
`OUTPUT_MESSAGE_TO_REPORT`	Use the `OUTPUT_MESSAGE_TO_REPORT` function to output a message to the report file.
`RESET_USEREXIT_STATS`	Use the `RESET_USEREXIT_STATS` function to reset the statistics for the Oracle GoldenGate process.
`SET_COLUMN_VALUE_BY_INDEX`	Use the `SET_COLUMN_VALUE_BY_INDEX` function to modify a single column value without manipulating the entire data record.
`STRNCMP`	Use the `SET_COLUMN_VALUE_BY_NAME` function to modify a single column value without manipulating the entire data record.
`SET_OPERATION_TYPE`	Use the `SET_OPERATION_TYPE` function to change the operation type associated with a data record.
`SET_RECORD_BUFFER`	Use the `SET_RECORD_BUFFER` function for compatibility with HP NonStop user exits, and for complex data record manipulation.
`SET_SESSION_CHARSET`	Use the `SET_SESSION_CHARSET` function to set the character set of the user exit session.
`SET_TABLE_NAME`	Use the `SET_TABLE_NAME` function to change the table name associated with a data record.