8
Replication Management API Reference

All installations of Oracle advanced replication include the replication management application programming interface (API). A server's replication management API is a set of PL/SQL packages that encapsulates procedures and functions that administrators can use to configure Oracle's advanced replication features. Oracle Replication Manager also uses the procedures and functions of each site's replication management API to perform work. This chapter describes that packages that constitute Oracle replication API, including:

The procedures and functions in each package.
The parameters for each packaged procedure or function.
Exceptions that each procedure or function can raise.

Packages

Oracle's replication management API includes the following packages:

Examples of Using Oracle's Replication Management API

To use Oracle's replication management API, you issue procedure or function calls using an ad-hoc query tool such as an Enterprise Manager SQL Worksheet, Server Manager's command prompt, or SQL*Plus. For example, the following call to the DBMS_REPCAT.CREATE_MASTER_REPOBJECT procedure creates a new replicated table SALES.EMP in the ACCT replication group.

DBMS_REPCAT.CREATE_MASTER_REPOBJECT(
     sname                => 'sales', 
     oname                => 'emp', 
     type                 => 'table', 
     use_existing_object  => TRUE, 
     ddl_text             => 'CREATE TABLE acct_rec.emp AS . . .', 
     comment              => 'created by . . .',
     retry                => FALSE,
     copy_rows            => TRUE,
     gname                => 'acct');

To call a replication management API function, you must provide an environment to receive the return value of the function. For example, the following anonymous PL/SQL block calls the DBMS_DEFER_SYS.DISABLED function in an IF statement.

BEGIN
 IF DBMS_DEFER_SYS.DISABLED('inst2') THEN
  DBMS_OUTPUT.PUT_LINE('Propagation to INST2 is disabled.');
 ELSE
  DBMS_OUTPUT.PUT_LINE('Propagation to INST2 is enabled.');
 END IF;
END;

Prerequisites to Consider

For many procedures and functions in the replication management API, there are important prerequisites to consider. For example:

Some procedures or functions are appropriate to call only from the master definition site in a multimaster configuration.
To perform certain administrative operations for master groups, you must first suspend replication activity for the group before calling replication management API procedures and functions.
The order in which you call different procedures and functions in Oracle's replication management API is extremely important. See the next section for more information about learning how to correctly issue replication management calls.

Replication Manager and Oracle Replication Management API

Oracle's Replication Manager uses the replication management API to perform most of its functions. Using Replication Manager is much more convenient than issuing replication management API calls individually because the utility:

Provides a GUI interface to type in and adjust API call parameters.
Automatically orders numerous, related API calls in the proper sequence.
Displays output returned from API calls in message boxes and error files.

An easy way to learn how to use Oracle's replication management API is to use Replication Manager scripting feature. When you start an administrative session with Replication Manager, turn scripting on. When you are finished, turn scripting off and then review the script file. The script file contains all replication management API calls that were made during the session. See the Replication Manager help documentation for more information about its scripting feature.

DBMS_DEFER Package

Summary of Subprograms

Table 8-1

Subprogram	Description
CALL procedure	Builds a deferred call to a remote procedure
COMMIT_WORK procedure	Performs a transaction commit after checking for well-formed deferred remote procedure calls
datatype_ARG procedure	Provides the data that is to be passed to a deferred remote procedure call
TRANSACTION procedure	Indicates the start of a new deferred transaction

CALL procedure

This procedure builds a deferred call to a remote procedure.

Syntax

DBMS_DEFER.CALL (
   schema_name       IN   VARCHAR2,
   package_name      IN   VARCHAR2,
   proc_name         IN   VARCHAR2,
   arg_count         IN   NATURAL,
   { nodes           IN   node_list_t 
   | group_name      IN   VARCHAR2 :=''});

Parameters

Table 8-2 CALL Procedure Parameters

Parameter	Description
schema_name	Name of the schema in which the stored procedure is located.
package_name	Name of the package containing the stored procedure. The stored procedure must be part of a package. Deferred calls to standalone procedures are not supported.
proc_name	Name of the remote procedure to which you want to defer a call.
arg_count	Number of parameters for the procedure. You must have one call to `DBMS_DEFER`.`datatype_ARG` for each of these parameters.
nodes	A PL/SQL table of fully qualified database names to which you want to propagate the deferred call. The table is indexed starting at position 1 and ending when a `NULL` entry is found, or the `NO_DATA_FOUND` exception is raised. The data in the table is case insensitive. This argument is optional.
group_name	Reserved for internal use.

Note:
The CALL procedure is overloaded. The nodes and group_name parameters are mutually exclusive.

Exceptions

Table 8-3 CALL Procedure Exceptions

Exception	Description
ORA-23304 (malformedcall)	Previous call was not correctly formed.
ORA-23319	Parameter value is not appropriate.
ORA-23352	Destination list (specified by `nodes` or by a previous `DBMS_DEFER`.`TRANSACTION` call) contains duplicates.

COMMIT_WORK procedure

This procedure performs a transaction commit after checking for well-formed deferred remote procedure calls.

Syntax

DBMS_DEFER.COMMIT_WORK (
   commit_work_comment IN VARCHAR2);

Parameters

Table 8-4 COMMIT_WORK Procedure Parameters

Parameter	Description
commit_work_ comment	Equivalent to SQL "COMMIT COMMENT" statement.

Exceptions

Table 8-5 COMMIT_WORK Procedure Exceptions

Exception	Description
ORA-23304 (malformedcall)	Transaction was not correctly formed or terminated.

datatype_ARG procedure

This procedure provides the data that is to be passed to a deferred remote procedure call. Depending upon the type of the data that you need to pass to a procedure, you must call one of the following procedures for each argument to the procedure.

Syntax

DBMS_DEFER.NUMBER_ARG       (arg  IN NUMBER);
DBMS_DEFER.DATE_ARG         (arg  IN DATE);
DBMS_DEFER.VARCHAR2_ARG     (arg  IN VARCHAR2);
DBMS_DEFER.CHAR_ARG         (arg  IN CHAR);
DBMS_DEFER.ROWID_ARG        (arg  IN ROWID);
DBMS_DEFER.RAW_ARG          (arg  IN RAW);
DBMS_DEFER.BLOB_ARG         (arg  IN BLOB);
DBMS_DEFER.CLOB_ARG         (arg  IN CLOB);
DBMS_DEFER.NCLOB_ARG        (arg  IN NCLOB);
DBMS_DEFER.NCHAR_ARG        (arg  IN NCHAR);
DBMS_DEFER.NVARCHAR2_ARG    (arg  IN NVARCHAR2);
DBMS_DEFER.ANY_CLOB_ARG     (arg  IN CLOB);
DBMS_DEFER.ANY_VARCHAR2_ARG (arg  IN VARCHAR2);
DBMS_DEFER.ANY_CHAR_ARG     (arg  IN CHAR);

Parameters

***Table 8-6 datatype_ARG Procedure Parameters***

Parameter	Description
arg	Value of the parameter that you want to pass to the remote procedure to which you previously deferred a call.

Exceptions

***Table 8-7 datatype_ARG Procedure Exceptions***

Exception	Description
ORA-23323	Argument value is too long.

TRANSACTION procedure

This procedure indicates the start of a new deferred transaction. If you omit this call, then Oracle considers your first call to DBMS_DEFER.CALL to be the start of a new transaction.

Syntax

DBMS_DEFER.TRANSACTION (
   nodes  IN   node_list_t);

Parameters

Table 8-8 TRANSACTION Procedure Parameters

Parameter	Description
nodes	A PL/SQL table of fully qualified database names to which you want to propagate the deferred calls of the transaction. The table is indexed starting at position 1 until a `NULL` entry is found, or the `NO_DATA_FOUND` exception is raised. The data in the table is case insensitive.

Exceptions

Table 8-9 TRANSACTION Procedure Exceptions

Exception	Description
ORA-23304 (malformedcall)	Previous transaction was not correctly formed or terminated.
ORA-23319	Parameter value is not appropriate.
ORA-23352	Raised by `DBMS_DEFER`.`CALL` if the node list contains duplicates.

Usage Notes

The TRANSACTION procedure is overloaded. The behavior of the version without an input parameter is similar to that of the version with an input parameter, except that the former uses the nodes in the DEFDEFAULTDEST view instead of using the nodes in the nodes parameter.

DBMS_DEFER_QUERY Package

Summary of Subprograms

Table 8-10 DBMS_DEFER_QUERY Package Subprograms

Subprogram	Description
GET_ARG_FORM function	Determines the form of an argument in a deferred call.
GET_ARG_TYPE function	Determines the type of an argument in a deferred call.
GET_CALL_ARGS procedure	Returns the text version of the various arguments for the given call.
GET_datatype_ARG function	Determines the value of an argument in a deferred call.

GET_ARG_FORM function

This function determines the form of an argument in a deferred call. This function will return the character set ID of a deferred call parameter.

For more about displaying deferred transactions, see "Displaying Deferred Transactions" in the Oracle8i Replication manual. For more information about displaying error transactions, see "Displaying Error Transactions" in the Oracle8i Replication manual.

Syntax

DBMS_DEFER_QUERY.GET_ARG_FORM (
   callno                IN   NUMBER,
   arg_no                IN   NUMBER,
   deferred_tran_id      IN   VARCHAR2)
  RETURN NUMBER;

Parameters

Table 8-11 GET_ARG_FORM Function Parameters

Parameter	Description
callno	Call identifier from the `DEFCALL` view.
arg_no	Position of desired parameter in calls argument list. Parameter positions are 1..number of parameters in call.
deferred_tran_id	Deferred transaction ID.

Exceptions

Table 8-12 GET_ARG_FORM Function Exceptions

Exception	Description
NO_DATA_FOUND	Input parameters do not correspond to a parameter of a deferred call.

Returns

Table 8-13 GET_ARG_Form Function Returns

Return Value	Corresponding Datatype
1	CHAR, VARCHAR2, CLOB
2	NCHAR, NVARCHAR2, NCLOB

GET_ARG_TYPE function

This function determines the type of an argument in a deferred call. The type of the deferred RPC parameter will be returned.

Syntax

DBMS_DEFER_QUERY.GET_ARG_TYPE (
   callno            IN   NUMBER,
   arg_no            IN   NUMBER,
   deferred_tran_id  IN   VARCHAR2)
  RETURN NUMBER;

Parameters

Table 8-14 GET_ARG_TYPE Function Parameters

Parameter	Description
callno	ID number from the `DEFCALL` view of the deferred remote procedure call.
arg_no	Numerical position of the argument to the call whose type you want to determine. The first argument to a procedure is in position 1.
deferred_tran_id	Identifier of the deferred transaction.

Exceptions

Table 8-15 GET_ARG_TYPE Function Exceptions

Exception	Description
NO_DATA_FOUND	Input parameters do not correspond to a parameter of a deferred call.

Returns

Table 8-16 GET_ARG_TYPE Function Returns

Return Value	Corresponding Datatype
1	VARCHAR2
2	NUMBER
11	ROWID
12	DATE
23	RAW
96	CHAR
112	CLOB
113	BLOB

GET_CALL_ARGS procedure

This procedure returns the text version of the various arguments for the given call. The text version is limited to the first 2000 bytes.

Syntax

DBMS_DEFER_QUERY.GET_CALL_ARGS (
   callno    IN  NUMBER,
   startarg  IN  NUMBER := 1,
   argcnt    IN  NUMBER,       
   argsize   IN  NUMBER,     
   tran_id   IN  VARCHAR2, 
   date_fmt  IN  VARCHAR2, 
   types     OUT TYPE_ARY,  
   forms     OUT TYPE_ARY,
   vals      OUT VAL_ARY);

Parameters

Table 8-17 GET_CALL_ARGS Procedure Parameters

Parameter	Description
callno	ID number from the `DEFCALL` view of the deferred RPC.
startarg	Numerical position of the first argument you want described.
argcnt	Number of arguments in the call.
argsize	Maximum size of returned argument.
tran_id	Identifier of the deferred transaction.
date_fmt	Format in which the date should be returned.
types	Array containing the types of arguments.
forms	Array containing the character set forms of arguments.
vals	Array containing the values of the arguments in a textual form.

Exceptions

Table 8-18 GET_CALL_ARGS Procedure Exceptions

Exception	Description
NO_DATA_FOUND	Input parameters do not correspond to a parameter of a deferred call.

GET_datatype_ARG function

This function determines the value of an argument in a deferred call.

Syntax

Depending upon the type of the argument value that you want to retrieve, the syntax for the appropriate function is as follows. Each of these functions returns the value of the specified argument.

DBMS_DEFER_QUERY.GET_datatype_ARG (
   callno             IN   NUMBER,
   arg_no             IN   NUMBER,
   deferred_tran_id   IN   VARCHAR2 DEFAULT NULL)
  RETURN datatype;

where datatype:

{ NUMBER
| VARCHAR2
| CHAR
| DATE
| RAW
| ROWID
| BLOB
| CLOB
| NCLOB
| NCHAR
| NVARCHAR2 }

Parameters

Table 8-19 GET_datatype_ARG Function Parameters

Parameter	Description
callno	ID number from the `DEFCALL` view of the deferred remote procedure call.
arg_no	Numerical position of the argument to the call whose value you want to determine. The first argument to a procedure is in position one.
deferred_tran_id	Identifier of the deferred transaction. Defaults to the last transaction identifier passed to `GET_ARG_TYPE`. The default is `NULL`.

Exceptions

Table 8-20 GET_datatype_ARG Function Exceptions

Exception	Description
NO_DATA_FOUND	Input parameters do not correspond to a parameter of a deferred call.
ORA-26564	Argument in this position is not of the specified type.

DBMS_DEFER_SYS Package

Summary of Subprograms

Table 8-21 DBMS_DEFER_SYS Package Subprograms

Subprogram	Description
ADD_DEFAULT_DEST procedure	Adds a destination database to the `DEFDEFAULTDEST` view.
DELETE_DEFAULT_DEST procedure	Removes a destination database from the `DEFDEFAULTDEST` view.
DELETE_DEF_DESTINATION procedure	Removes a destination database from the `DEFSCHEDULE` view.
DELETE_ERROR	Deletes a transaction from the `DEFERROR` view.
DELETE_TRAN	Deletes a transaction from the `DEFTRANDEST` view.
DISABLED	Determines whether propagation of the deferred transaction queue from the current site to a given site is enabled.
EXCLUDE_PUSH	Acquires an exclusive lock that prevents deferred transaction `PUSH`.
EXECUTE_ERROR	Re-executes a deferred transaction that did not initially complete successfully.
EXECUTE_ERROR_AS_USER	Re-executes a deferred transaction that did not initially complete successfully.
PURGE	Purges pushed transactions from the deferred transaction queue at your current master or snapshot site.
PUSH function	Forces a deferred remote procedure call queue at your current master or snapshot site to be pushed to another master site.
REGISTER_PROPAGATOR procedure	Registers the given user as the propagator for the local database.
SCHEDULE_PURGE procedure	Schedules a job to purge pushed transactions from the deferred transaction queue at your current master or snapshot site.
SCHEDULE_PUSH procedure	Schedules a job to push the deferred transaction queue to a remote master destination.
SET_DISABLED procedure	Disables or enables propagation of the deferred transaction queue from the current site to a given destination site.
UNREGISTER_PROPAGATOR procedure	Unregister a user as the propagator from the local database.
UNSCHEDULE_PURGE procedure	Stops automatic purges of pushed transactions from the deferred transaction queue at a snapshot or master site.
UNSCHEDULE_PUSH procedure	Stops automatic pushes of the deferred transaction queue from a snapshot or master site to another master site.

ADD_DEFAULT_DEST procedure

This procedure adds a destination database to the DEFDEFAULTDEST view.

Syntax

DBMS_DEFER_SYS.ADD_DEFAULT_DEST (
   dblink   IN   VARCHAR2);

Parameters

Table 8-22 ADD_DEFAULT_DEST Procedure Parameters

Parameter	Description
dblink	The fully qualified database name of the node that you want to add to the `DEFDEFAULTDEST` view.

Exceptions

Table 8-23 ADD_DEFAULT_DEST Procedure Exceptions

Exception	Description
ORA-23352	The `dblink` that you specified is already in the default list.

DELETE_DEFAULT_DEST procedure

This procedure removes a destination database from the DEFDEFAULTDEST view.

Syntax

DBMS_DEFER_SYS.DELETE_DEFAULT_DEST (
   dblink   IN   VARCHAR2);

Parameters

Table 8-24 DELETE_DEFAULT_DEST Procedure Parameters

Parameter	Description
dblink	The fully qualified database name of the node that you want to delete from the `DEFDEFAULTDEST` view. If Oracle does not find this dblink in the view, then no action is taken.

DELETE_DEF_DESTINATION procedure

This procedure removes a destination database from the DEFSCHEDULE view.

Syntax

DBMS_DEFER_SYS.DELETE_DEF_DESTINATION (
   destination   IN   VARCHAR2,
   force         IN   BOOLEAN := FALSE);

Parameters

Table 8-25 DELETE_DEF_DESTINATION Procedure Parameters

Parameter	Description
destination	The fully qualified database name of the destination that you want to delete from the `DefSchedule` view. If Oracle does not find this destination in the view, then no action is taken.
force	When set to `TRUE`, Oracle ignores all safety checks and deletes the destination.

DELETE_ERROR

To delete a transaction from the DEFERROR view.

Syntax

DBMS_DEFER_SYS.DELETE_ERROR(
   deferred_tran_id     IN   VARCHAR2,
   destination          IN   VARCHAR2);

Parameters

Table 8-26 Parameters for DELETE_ERROR

Parameter	Description
deferred_tran_id	ID number from the `DEFERROR` view of the deferred transaction that you want to remove from the `DEFERROR` view. If this parameter is `NULL`, then all transactions meeting the requirements of the other parameter are removed.
destination	The fully qualified database name from the `DEFERROR` view of the database to which the transaction was originally queued. If this parameter is `NULL`, then all transactions meeting the requirements of the other parameter are removed from the `DEFERROR` view.

DELETE_TRAN

To delete a transaction from the DEFTRANDEST view. If there are no other DEFTRANDEST or DEFERROR entries for the transaction, then the transaction is deleted from the DEFTRAN and DEFCALL views as well.

Syntax

DBMS_DEFER_SYS.DELETE_TRAN (
   deferred_tran_id     IN   VARCHAR2,
   destination          IN   VARCHAR2);

Parameters

Table 8-27 Parameters for DELETE_TRAN

Parameter	Description
deferred_tran_id	ID number from the `DEFTRAN` view of the deferred transaction that you want to delete. If this is `NULL`, then all transactions meeting the requirements of the other parameter are deleted.
destination	The fully qualified database name from the `DEFTRANDEST` view of the database to which the transaction was originally queued. If this is `NULL`, then all transactions meeting the requirements of the other parameter are deleted.

DISABLED

To determine whether propagation of the deferred transaction queue from the current site to a given site is enabled. The DISABLED function returns TRUE if the deferred remote procedure call (RPC) queue is disabled for the given destination.

Syntax

DBMS_DEFER_SYS.DISABLED (
   destination  IN   VARCHAR2)
  RETURN BOOLEAN;

Parameters

Table 8-28 Parameter for DISABLED

Parameter	Description
destination	The fully qualified database name of the node whose propagation status you want to check.

Returns

Table 8-29 Return Values for DISABLED

Value	Description
TRUE	Propagation to this site from the current site is disabled.
FALSE	Propagation to this site from the current site is enabled.

Exceptions

Table 8-30 Exception for DISABLED

Exception	Description
NO_DATA_FOUND	`DESTINATION` does not appear in the `DEFSCHEDULE` view.

EXCLUDE_PUSH

To acquire an exclusive lock that prevents deferred transaction PUSH (either serial or parallel). This function does a commit when acquiring the lock. The lock is acquired with RELEASE_ON_COMMIT => TRUE, so that pushing of the deferred transaction queue can resume after the next commit.

Syntax

DBMS_DEFER_SYS.EXCLUDE_PUSH (
   timeout   IN   INTEGER)
  RETURN INTEGER;

Parameters

Table 8-31 Parameter for EXCLUDE_PUSH

Parameter	Description
timeout	Timeout in seconds. If the lock cannot be acquired within this time period (either because of an error or because a `PUSH` is currently under way), then the call returns a value of 1. A timeout value of `DBMS_LOCK`.`MAXWAIT` waits indefinitely.

Returns

E_PUSH

Table 8-32 Return Values for EXCLUDE_PUSH

Value	Description
0	Success, lock acquired.
1	Timeout, no lock acquired.
2	Deadlock, no lock acquired.
4	Already own lock.

EXECUTE_ERROR

To reexecute a deferred transaction that did not initially complete successfully. This procedure raises an ORA-24275 error when illegal combinations of NULL and non-NULL parameters are used.

Syntax

DBMS_DEFER_SYS.EXECUTE_ERROR ( 
   deferred_tran_id IN   VARCHAR2,
   destination      IN   VARCHAR2);

Parameters

Table 8-33 Parameters for EXECUTE_ERROR

Parameter	Description
deferred_tran_id	ID number from the `DEFERROR` view of the deferred transaction that you want to re-execute. If this is `NULL`, then all transactions queued for `destination` are re-executed.
destination	The fully qualified database name from the `DEFERROR` view of the database to which the transaction was originally queued. This must not be `NULL`.

Exceptions

Table 8-34 Exceptions for EXECUTE_ERROR

Exception	Description
badparam	Parameter value missing or invalid (for example, if `destination` is `NULL`).
missinguser	Invalid user.

EXECUTE_ERROR_AS_USER

To reexecute a deferred transaction that did not initially complete successfully. Each transaction is executed in the security context of the connected user. This procedure raises an ORA-24275 error when illegal combinations of NULL and non-NULL parameters are used.

Syntax

DBMS_DEFER_SYS.EXECUTE_ERROR_AS_USER ( 
   deferred_tran_id IN   VARCHAR2,
   destination      IN   VARCHAR2);

Parameters

Table 8-35 Parameters for EXECUTE_ERROR_AS_USER

Parameter	Description
deferred_tran_id	ID number from the `DEFERROR` view of the deferred transaction that you want to re-execute. If this is `NULL`, then all transactions queued for `destination` are re-executed.
destination	The fully qualified database name from the `DEFERROR` view of the database to which the transaction was originally queued. This must not be `NULL`.

Exceptions

Table 8-36 Exceptions for EXECUTE_ERROR_AS_USER

Exception	Description
badparam	Parameter value missing or invalid (for example, if destination is `NULL`).
missinguser	Invalid user.

PURGE

To purge pushed transactions from the deferred transaction queue at your current master or snapshot site.

Syntax

DBMS_DEFER_SYS.PURGE (
   purge_method         IN  BINARY_INTEGER := purge_method_quick,
   rollback_segment     IN  VARCHAR2       := NULL,
   startup_seconds      IN  BINARY_INTEGER := 0,
   execution_seconds    IN  BINARY_INTEGER := seconds_infinity,
   delay_seconds        IN  BINARY_INTEGER := 0,
   transaction_count    IN  BINARY_INTEGER := transactions_infinity,
   write_trace          IN  BOOLEAN        := NULL);
  RETURN BINARY_INTEGER;

Parameters

Table 8-37 Parameters for PURGE

Parameter	Description
purge_method	Controls how to purge the deferred transaction queue; `purge_method_quick` costs less, while `purge_method_precise` offers better precision.
rollback_segment	Name of rollback segment to use for the purge, or `NULL` for default.
startup_seconds	Maximum number of seconds to wait for a previous purge of the same deferred transaction queue.
execution_seconds	If >0, then stop purge cleanly after the specified number of seconds of real time.
delay_seconds	Stop purge cleanly after the deferred transaction queue has no transactions to purge for `delay_seconds`.
transaction_count	If > 0, then shutdown cleanly after purging `transaction_count` number of transactions.
write_trace	When set to `TRUE`, Oracle records the result value returned by the PURGE function in the server's trace file.

Returns

Table 8-38 Return Values for Purge

Value	Description
0	OK, terminated after `delay_seconds` expired.
1	Terminated by lock timeout while starting.
2	Terminated by exceeding `execution_seconds`.
3	Terminated by exceeding `transaction_count`.
5	Terminated after errors.

Exceptions

Table 8-39 Exceptions for PURGE

Exception	Description
argoutofrange	Parameter value is out of a valid range.
executiondisabled	Execution of purging is disabled.
defererror	Internal error.

PUSH function

This function forces a deferred remote procedure call queue at your current master or snapshot site to be pushed (executed, propagated) to another master site using either serial or parallel propagation.

Syntax

DBMS_DEFER_SYS.PUSH (
   destination          IN  VARCHAR2,
   parallelism          IN  BINARY_INTEGER := 0,
   heap_size            IN  BINARY_INTEGER := 0)
   stop_on_error        IN  BOOLEAN        := FALSE,
   write_trace          IN  BOOLEAN        := FALSE,
   startup_seconds      IN  BINARY_INTEGER := 0,
   execution_seconds    IN  BINARY_INTEGER := seconds_infinity,
   delay_seconds        IN  BINARY_INTEGER := 0,
   transaction_count    IN  BINARY_INTEGER := transactions_infinity,
   delivery_order_limit IN  NUMBER         := delivery_order_infinity)
  RETURN BINARY_INTEGER;

Parameters

Table 8-40 PUSH Function Parameters

Parameter	Description
destination	The fully qualified database name of the master to which you are forwarding changes.
parallelism	0 = serial propagation; n > 0 = parallel propagation with n parallel server processes; 1 = parallel propagation using only one parallel server process.
heap_size	Maximum number of transactions to be examined simultaneously for parallel propagation scheduling. Oracle automatically calculates the default setting for optimal performance. Do not set the parameter unless so directed by Oracle Worldwide Support.
stop_on_error	The default, `FALSE`, indicates that the executor should continue even if errors, such as conflicts, are encountered. If `TRUE`, then shutdown (cleanly if possible) at the first indication that a transaction encountered an error at the destination site.
write_trace	When set to `TRUE`, Oracle records the result value returned by the function in the server's trace file.
startup_seconds	Maximum number of seconds to wait for a previous push to the same destination.
execution_seconds	If >0, then stop push cleanly after the specified number of seconds of real time. If `transaction_count` and `execution_seconds` are zero (the default), then transactions are executed until there are no more in the queue.
delay_seconds	Do not return before the specified number of seconds have elapsed, even if the queue is empty. Useful for reducing execution overhead if `PUSH` is called from a tight loop.
transaction_count	If > 0, then the maximum number of transactions to be pushed before stopping. If `transaction_count` and `execution_seconds` are zero (the default), then transactions are executed until there are no more in the queue that need to be pushed.
delivery_order_ limit	Stop execution cleanly before pushing a transaction where `delivery_order` >= `delivery_order_limit`

Returns

Table 8-41 PUSH Function Returns

Value	Description
0	OK, terminated after `delay_seconds` expired.
1	Terminated by lock timeout while starting.
2	Terminated by exceeding `execution_seconds`.
3	Terminated by exceeding `transaction_count`.
4	Terminated by exceeding `delivery_order_limit`.
5	Terminated after errors.

PUSH

Exceptions

Table 8-42 Exceptions for PUSH

Exception	Description
deferror incompleteparallelpush	Serial propagation requires that parallel propagation shuts down cleanly.
executiondisabled	Execution of deferred RPCs is disabled at the destination.
crt_err_err	Error while creating entry in `DEFERROR`.
deferred_rpc_qiesce	Replication activity for object group is suspended.
commfailure	Communication failure during deferred RPC.
missingpropator	A propagator does not exist.

REGISTER_PROPAGATOR procedure

This procedure registers the given user as the propagator for the local database. It also grants to the given user CREATE SESSION, CREATE PROCEDURE, CREATE DATABASE LINK, and EXECUTE ANY PROCEDURE privileges (so that the user can create wrappers).

Syntax

DBMS_DEFER_SYS.REGISTER_PROPAGATOR (
   username  IN  VARCHAR2);

Parameters

Table 8-43 REGISTER_PROPAGATOR Procedure Parameters

Parameter	Description
username	Name of the user.

Exceptions

Table 8-44 REGISTER_PROPAGATOR Procedure Exceptions

Exception	Description
missinguser	Given user does not exist.
alreadypropagator	Given user is already the propagator.
duplicatepropagator	There is already a different propagator.

SCHEDULE_PURGE procedure

This procedure schedules a job to purge pushed transactions from the deferred transaction queue at your current master or snapshot site. You should schedule one purge job.

Syntax

DBMS_DEFER_SYS.SCHEDULE_PURGE (
   interval             IN  VARCHAR2,
   next_date            IN  DATE,
   reset                IN  BOOLEAN        := NULL,
   purge_method         IN  BINARY_INTEGER := NULL,
   rollback_segment     IN  VARCHAR2       := NULL,
   startup_seconds      IN  BINARY_INTEGER := NULL,
   execution_seconds    IN  BINARY_INTEGER := NULL,
   delay_seconds        IN  BINARY_INTEGER := NULL,
   transaction_count    IN  BINARY_INTEGER := NULL,
   write_trace          IN  BOOLEAN        := NULL);

Parameters

Table 8-45 SCHEDULE_PURGE Procedure Parameters

Parameter	Description
interval	Allows you to provide a function to calculate the next time to purge. This value is stored in the `interval` field of the `DEFSCHEDULE` view and calculates the `next_date` field of this view. If you use the default value for this parameter, `NULL`, then the value of this field remains unchanged. If the field had no previous value, it is created with a value of `NULL`. If you do not supply a value for this field, you must supply a value for `next_date`.
next_date	Allows you to specify a given time to purge pushed transactions from the site's queue. This value is stored in the `next_date` field of the `DEFSCHEDULE` view. If you use the default value for this parameter, `NULL`, then the value of this field remains unchanged. If this field had no previous value, it is created with a value of `NULL`. If you do not supply a value for this field, then you must supply a value for `interval`.
reset	Set to `TRUE` to reset `LAST_TXN_COUNT`, `LAST_ERROR`, and `LAST_MSG` to `NULL`.
purge_method	Controls how to purge the deferred transaction queue; `purge_method_quick` costs less, while `purge_method_precise` offers better precision.
rollback_segment	Name of rollback segment to use for the purge, or `NULL` for default.
startup_seconds	Maximum number of seconds to wait for a previous purge of the same deferred transaction queue.
execution_seconds	If >0, then stop purge cleanly after the specified number of seconds of real time.
delay_seconds	Stop purge cleanly after the deferred transaction queue has no

8 Replication Management API Reference

Packages

Examples of Using Oracle's Replication Management API

Prerequisites to Consider

Replication Manager and Oracle Replication Management API

DBMS_DEFER Package

Summary of Subprograms

Table 8-1

CALL procedure

Syntax

Parameters

Table 8-2 CALL Procedure Parameters

Exceptions

Table 8-3 CALL Procedure Exceptions

COMMIT_WORK procedure

Syntax

Parameters

Table 8-4 COMMIT_WORK Procedure Parameters

Exceptions

Table 8-5 COMMIT_WORK Procedure Exceptions

datatype_ARG procedure

Syntax

Parameters

Table 8-6 datatype_ARG Procedure Parameters

Exceptions

Table 8-7 datatype_ARG Procedure Exceptions

TRANSACTION procedure

Syntax

Parameters

Table 8-8 TRANSACTION Procedure Parameters

Exceptions

Table 8-9 TRANSACTION Procedure Exceptions

Usage Notes

DBMS_DEFER_QUERY Package

Summary of Subprograms

Table 8-10 DBMS_DEFER_QUERY Package Subprograms

GET_ARG_FORM function

Syntax

Parameters

Table 8-11 GET_ARG_FORM Function Parameters

Exceptions

Table 8-12 GET_ARG_FORM Function Exceptions

Returns

Table 8-13 GET_ARG_Form Function Returns

GET_ARG_TYPE function

Syntax

Parameters

Table 8-14 GET_ARG_TYPE Function Parameters

Exceptions

Table 8-15 GET_ARG_TYPE Function Exceptions

Returns

Table 8-16 GET_ARG_TYPE Function Returns

GET_CALL_ARGS procedure

Syntax

Parameters

Table 8-17 GET_CALL_ARGS Procedure Parameters

Exceptions

Table 8-18 GET_CALL_ARGS Procedure Exceptions

GET_datatype_ARG function

Syntax

Parameters

Table 8-19 GET_datatype_ARG Function Parameters

Exceptions

Table 8-20 GET_datatype_ARG Function Exceptions

DBMS_DEFER_SYS Package

Summary of Subprograms

Table 8-21 DBMS_DEFER_SYS Package Subprograms

ADD_DEFAULT_DEST procedure

Syntax

Parameters

Table 8-22 ADD_DEFAULT_DEST Procedure Parameters

Exceptions

Table 8-23 ADD_DEFAULT_DEST Procedure Exceptions

DELETE_DEFAULT_DEST procedure

Syntax

Parameters

Table 8-24 DELETE_DEFAULT_DEST Procedure Parameters

DELETE_DEF_DESTINATION procedure

Syntax

Parameters

8
Replication Management API Reference

***Table 8-6 datatype_ARG Procedure Parameters***

***Table 8-7 datatype_ARG Procedure Exceptions***