Oracle8i Replication API Reference
Release 8.1.5

A67793-01

Library

Product

Contents

Index

Prev Next

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:

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:

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:

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.

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_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.

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

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