9
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:

• DBMS_DEFER
• DBMS_DEFER_QUERY
• DBMS_DEFER_SYS
• DBMS_OFFLINE_OG
• DBMS_OFFLINE_SNAPSHOT
• DBMS_RECTIFIER_DIFF
• DBMS_REFRESH
• DBMS_REPCAT
• DBMS_REPCAT_ADMIN
• DBMS_REPCAT_AUTH
• DBMS_REPUTIL
• DBMS_SNAPSHOT

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

The DBMS_DEFER package contains the following procedures:

• DBMS_DEFER.CALL
• DBMS_DEFER.COMMIT_WORK
• DBMS_DEFER.datatype_ARG
• DBMS_DEFER.TRANSACTION

The following pages discuss each procedure.

DBMS_DEFER.CALL

Purpose

To build a deferred call to a remote procedure.

Syntax

The parameters for the CALL procedure are described in Table 9-1, and the exceptions are listed in Table 9-2. The syntax for this procedure is shown below:

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 :=''})

Note: The CALL procedure is overloaded. The NODES and GROUP_NAME parameters are mutually exclusive.

Table 9-1 Parameters for CALL

Parameter	Description
schema_name	The name of the schema in which the stored procedure is located.
package_name	The 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	The name of the remote procedure to which you want to defer a call.
arg_count	The 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.

Table 9-2 Exceptions for CALL

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

DBMS_DEFER.COMMIT_WORK

Purpose

To perform a transaction commit after checking for well-formed deferred remote procedure calls.

Syntax

The parameter for the COMMIT_WORK procedure is described in Table 9-3, and the exception is listed in Table 9-4. The syntax for this procedure is shown below:

DBMS_DEFER.COMMIT_WORK(commit_work_comment IN VARCHAR2)

Table 9-3 Parameter for COMMIT_WORK

Parameter	Description
commit_work_ comment	Up to 50 bytes to describe the transaction in the DEF$_CALL table.

Table 9-4 Exception for COMMIT_WORK

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

DBMS_DEFER.datatype_ARG

Purpose

To provide 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 need to call one of the following procedures in the DBMS_DEFER package for each argument to the procedure:

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)
DBMS_DEFER.BFILE_ARG        (arg  IN BFILE)
DBMS_DEFER.CFILE_ARG        (arg  IN CFILE)

Table 9-5 Parameter for datatype_ARG

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

Table 9-6 Exception for datatype_ARG

Exception	Description
ORA-23323	The argument value is too long.

DBMS_DEFER.TRANSACTION

Purpose

To indicate the start of a new deferred transaction. If you omit this call, Oracle considers your first call to DBMS_DEFER.CALL to be the start of a new transaction.

Syntax

The parameter for the TRANSACTION procedure is described in Table 9-7, and the exceptions are listed in Table 9-8. The syntax for this procedure is as follows:

DBMS_DEFER.TRANSACTION
DBMS_DEFER.TRANSACTION(nodes  IN   node_list_t)

Note: 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.

Table 9-7 Parameter for TRANSACTION

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.

Table 9-8 Exceptions for TRANSACTION

Exception	Description
ORA-23304 (malformedcall)	The 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.

DBMS_DEFER_QUERY Package

The DBMS_DEFER_QUERY package contains the following procedures and functions:

• DBMS_DEFER_QUERY.GET_ARG_FORM
• DBMS_DEFER_QUERY.GET_ARG_TYPE
• DBMS_DEFER_QUERY.GET_CALL_ARGS
• DBMS_DEFER_QUERY.GET_datatype_ARG

The following pages discuss each procedure and function.

DBMS_DEFER_QUERY.GET_ARG_FORM

Purpose

To determine the form of an argument in a deferred call. For more about displaying deferred transactions, see "Displaying Deferred Transactions" on page 6-9. For more information about displaying error transactions, see "Displaying Error Transactions" on page 6-11.

Syntax

The parameters for the GET_ARG_FORM function are described in Table 9-9, the exception is listed in Table 9-10. The syntax for this procedure is shown below:

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

Table 9-9 Parameters for GET_ARG_FORM

Parameter	Description
callno	The call identifier from the DEFCALL view.
arg_no	The position of desired parameter in calls argument list. Parameter positions are 1..number of parameters in call.
deferred_tran_id	The deferred transaction id.

Table 9-10 Exception for GET_ARG_FORM

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

DBMS_DEFER_QUERY.GET_ARG_TYPE

Purpose

To determine the type of an argument in a deferred call. For more about displaying deferred transactions, see "Displaying Deferred Transactions" on page 6-9. For more information about displaying error transactions, see "Displaying Error Transactions" on page 6-11.

Syntax

The parameters for the GET_ARG_TYPE function are described in Table 9-11, the exception is listed in Table 9-12, and the possible return values are described in Table 9-13. The syntax for this procedure is shown below:

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

Table 9-11 Parameters for GET_ARG_TYPE

Parameter	Description
callno	The ID number from the DEFCALL view of the deferred remote procedure call.
arg_no	The 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	The identifier of the deferred transaction.

Table 9-12 Exception for GET_ARG_TYPE

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

Table 9-13 Return Values for GET_ARG_TYPE

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

DBMS_DEFER_QUERY.GET_CALL_ARGS

Purpose

This procedure returns the text version of the various arguments for the given call.

Syntax

The parameters for the GET_CALL_ARGS procedure are described in Table 9-14 and the exception is listed in Table 9-15. The syntax for this procedure is as follows:

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)

Table 9-14 Parameters for GET_CALL_ARGS

Parameter	Description
callno	The ID number from the DEFCALL view of the deferred RPC.
startarg	The numerical position of the first argument you want described.
argcnt	The number of arguments in the call.
argsize	The maximum size of returned argument.
tran_id	Identifier of the deferred transaction.
date_fmt	The format in which the date should be returned.
types	An array containing the types of arguments.
forms	An array containing the character set forms of arguments.
vals	An array containing the values of the arguments in a textual form.

Table 9-15 Exception for GET_CALL_ARGS

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

DBMS_DEFER_QUERY.GET_datatype_ARG

Purpose

To determine the value of an argument in a deferred call. For more about displaying deferred transactions, see "Displaying Deferred Transactions" on page 6-9. For more information about displaying error transactions, see "Displaying Error Transactions" on page 6-11.

Syntax

Depending upon the type of the argument value that you want to retrieve, the syntax for the appropriate function is as follows. The parameters for these functions are described in Table 9-16, and the exceptions are listed in Table 9-17. 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 }

Table 9-16 Parameters for GET_datatype_ARG

Parameter	Description
callno	The ID number from the DEFCALL view of the deferred remote procedure call.
arg_no	The 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	Default NULL. The identifier of the deferred transaction. Defaults to the last transaction identifier passed to GET_ARG_TYPE.

Table 9-17 Exceptions for GET_datatype_ARG

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

DBMS_DEFER_SYS Package

The DBMS_DEFER_SYS package contains the following procedures and functions:

• DBMS_DEFER_SYS.ADD_DEFAULT_DEST
• DBMS_DEFER_SYS.DELETE_DEFAULT_DEST
• DBMS_DEFER_SYS.DELETE_DEF_DESTINATION
• DBMS_DEFER_SYS.DELETE_ERROR
• DBMS_DEFER_SYS.DELETE_TRAN
• DBMS_DEFER_SYS.DISABLED
• DBMS_DEFER_SYS.EXCLUDE_PUSH
• DBMS_DEFER_SYS.EXECUTE_ERROR
• DBMS_DEFER_SYS.EXECUTE_ERROR_AS_USER
• DBMS_DEFER_SYS.PURGE
• DBMS_DEFER_SYS.PUSH
• DBMS_DEFER_SYS.REGISTER_PROPAGATOR
• DBMS_DEFER_SYS.SCHEDULE_PURGE
• DBMS_DEFER_SYS.SCHEDULE_PUSH
• DBMS_DEFER_SYS.SET_DISABLED
• DBMS_DEFER_SYS.UNREGISTER_PROPAGATOR
• DBMS_DEFER_SYS.UNSCHEDULE_PURGE
• DBMS_DEFER_SYS.UNSCHEDULE_PUSH

The following pages discuss each procedure and function.

DBMS_DEFER_SYS.ADD_DEFAULT_DEST

Purpose

To add a destination database to the DEFDEFAULTDEST view.

Syntax

The parameter for the ADD_DEFAULT_DEST procedure is described in Table 9-18, and the exception is listed in Table 9-19. The syntax for this procedure is shown below:

DBMS_DEFER_SYS.ADD_DEFAULT_DEST(dblink   IN   VARCHAR2)

Table 9-18 Parameter for ADD_DEFAULT_DEST

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

Table 9-19 Exception for ADD_DEFAULT_DEST

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

DBMS_DEFER_SYS.DELETE_DEFAULT_DEST

Purpose

To remove a destination database from the DEFDEFAULTDEST view.

Syntax

The parameter for the DELETE_DEFAULT_DEST procedure is described in Table 9-20. The syntax for this procedure is shown below:

DBMS_DEFER_SYS.DELETE_DEFAULT_DEST(dblink   IN   VARCHAR2)

Table 9-20 Parameter for DELETE_DEFAULT_DEST

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, no action is taken.

DBMS_DEFER_SYS.DELETE_DEF_DESTINATION

Purpose

To remove a destination database from the DEFSCHEDULE view.

Syntax

The parameters for the DELETE_DEF_DESTINATION procedure is described in Table 9-21. The syntax for this procedure is shown below:

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

Table 9-21 Parameters for DELETE_DEF_DESTINATION

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, no action is taken.
force	When set to TRUE, Oracle ignores all safety checks and deletes the destination.

DBMS_DEFER_SYS.DELETE_ERROR

Purpose

To delete a transaction from the DEFERROR view.

Syntax

The parameters for the DELETE_ERROR procedure are described in Table 9-22. The syntax for this procedure is shown below:

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

Table 9-22 Parameters for DELETE_ERROR

Parameter	Description
deferred_tran_id	The ID number from the DEFERROR view of the deferred transaction that you want to remove from the DEFERROR view. If this parameter is null, all transactions meeting the requirements of the other parameters 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, all transactions meeting the requirements of the other parameters are removed from the DEFERROR view.

DBMS_DEFER_SYS.DELETE_TRAN

Purpose

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

Syntax

The parameters for the DELETE_TRAN procedure are described in Table 9-23. The syntax for this procedure is shown below:

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

Table 9-23 Parameters for DELETE_TRAN

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

DBMS_DEFER_SYS.DISABLED

Purpose

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

The parameter for the DISABLED function is described in Table 9-24, the return values are described in Table 9-25, and the exception is described in Table 9-26. The syntax for this function is shown below:

DBMS_DEFER_SYS.DISABLED(
      destination  IN   VARCHAR2)
  RETURN BOOLEAN

Table 9-24 Parameter for DISABLED

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

Table 9-25 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.

Table 9-26 Exception for DISABLED

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

DBMS_DEFER_SYS.EXCLUDE_PUSH

Purpose

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

Syntax

The parameters and return values are shown below.

DBMS_DEFER_SYS.EXCLUDE_PUSH(
      timeout   IN   INTEGER)
  RETURN INTEGER

Table 9-27 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), the call returns a value of 1. A timeout value of DBMS_LOCK.MAXWAIT waits indefinitely.

Return Values for EXCLUDE_PUSH

Table 9-28 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.

DBMS_DEFER_SYS.EXECUTE_ERROR

Purpose

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

The parameters for the EXECUTE_ERROR procedure are described in Table 9-29. The syntax for this procedure is shown below:

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

Table 9-29 Parameters for EXECUTE_ERROR

Parameter	Description
deferred_tran_id	The ID number from the DEFERROR view of the deferred transaction that you want to re-execute. If this parameter is null, 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 parameter must not be null.

Table 9-30 Exceptions for EXECUTE_ERROR

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

DBMS_DEFER_SYS.EXECUTE_ERROR_AS_USER

Purpose

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

The parameters for the EXECUTE_ERROR_AS_USER procedure are described in Table 9-31. The syntax for this procedure is shown below:

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

Table 9-31 Parameters for EXECUTE_ERROR_AS_USER

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

Table 9-32 Exceptions for EXECUTE_ERROR_AS_USER

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

DBMS_DEFER_SYS.PURGE

Purpose

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

Syntax

The parameters for the PURGE function are shown in Table 9-33. The syntax for this function is shown below:

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

Table 9-33 Parameters for PURGE

Parameter	Description
purge_method	Controls how to purge the deferred transaction queue; purge_method_quick cost 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	The maximum number of seconds to wait for a previous purge of the same deferred transaction queue.
execution_seconds	If >0, stop push cleanly after the specified number of seconds of real time.
delay_seconds	Stop execution cleanly after the deferred transaction queue is empty for delay_seconds.
transaction_count	If > 0, shutdown cleanly after purging transaction_count number of transactions.
write_trace	When set to TRUE, Oracle records the result value returned by the function in the server's trace file.

Table 9-34 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.
4	Terminated by exceeding delivery_order_limit.
5	Terminated after errors.

Table 9-35 Exceptions for PURGE

Exception	Description
argoutofrange	A parameter value is out of a valid range.
executiondisabled	The execution of deferred RPCs is disabled at the destination.
defererror	Internal error.

DBMS_DEFER_SYS.PUSH

Purpose

To force 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

The parameters for the PUSH function are shown in Table 9-36. The syntax for this function is shown below:

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

Table 9-36 Parameters for PUSH

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, 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	The maximum number of seconds to wait for a previous push to the same destination.
execution_seconds	If >0, stop push cleanly after the specified number of seconds of real time. If transaction_count and execution_seconds are zero (the default), 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 DBMS_DEFER_SYS.PUSH is called from a tight loop.
transaction_count	If > 0, the maximum number of transactions to be pushed before stopping. If transaction_count and execution_seconds are zero (the default), transactions are executed until there are no more in the queue.
delivery_order_ limit	Stop execution cleanly before pushing a transaction where delivery_order >= delivery_order_limit

Table 9-37 Return Values for PUSH

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

Table 9-38 Exceptions for PUSH

Exception	Description
deferror incompleteparallelpush	Internal error.
executiondisabled	The execution of deferred RPCs is disabled at the destination.
cat_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.

DBMS_DEFER_SYS.REGISTER_PROPAGATOR

Purpose

Register 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

The parameter for the REGISTER_PROPAGATOR procedure is described in Table 9-39. The syntax for this procedure is shown below, and the exceptions are listed in Table 9-40:

DBMS_DEFER_SYS.REGISTER_PROPAGATOR(username  IN  VARCHAR2)

Table 9-39 Parameter for REGISTER_PROPAGATOR

Parameter	Description
username	The name of the user.

Exception

Table 9-40 Exceptions for REGISTER_PROPAGATOR

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

DBMS_DEFER_SYS.SCHEDULE_PURGE

Purpose

To schedule a job to purge pushed transactions from the deferred transaction queue at your current master or snapshot site. You can schedule only one purge job per site.

Syntax

The parameters for the SCHEDULE_PURGE procedure are shown in Table 9-41. The syntax for this procedure is shown below:

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)

Table 9-41 Parameters for SCHEDULE_PURGE

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, 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, 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, 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 cost 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	The maximum number of seconds to wait for a previous purge of the same deferred transaction queue.
execution_seconds	If >0, stop execution cleanly after the specified number of seconds of real time.
delay_seconds	Stop execution cleanly after the deferred transaction queue is empty for delay_seconds.
transaction_count	If > 0, shutdown cleanly after purging transaction_count number of transactions.
write_trace	When set to TRUE, Oracle records the result value returned by the function in the server's trace file.

DBMS_DEFER_SYS.SCHEDULE_PUSH

Purpose

To schedule a job to push the deferred transaction queue to a remote master destination. This procedure does a commit.

Syntax

The parameters for the SCHEDULE_PUSH procedure are described in Table 9-42. The syntax for this procedure is shown below:

DBMS_DEFER_SYS.SCHEDULE_PUSH(
 destination          IN  VARCHAR2,
 interval             IN  VARCHAR2,
 next_date            IN  DATE,
 reset                IN  BOOLEAN        := FALSE,
 parallelism          IN  BINARY_INTEGER := NULL,
 heap_size            IN  BINARY_INTEGER := NULL,
 stop_on_error        IN  BOOLEAN        := NULL,
 write_trace          IN  BOOLEAN        := 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)

Table 9-42 Parameters for SCHEDULE_PUSH

Parameter	Description
destination	The fully qualified database name of the master to which you are forwarding changes.
interval	Allows you to provide a function to calculate the next time to push. 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, 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 push deferred transactions to the master site destination. This value is stored in the NEXT_DATE field of the DEFSCHEDULE view. If you use the default value for this parameter, NULL, 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, you must supply a value for INTERVAL.
reset	Set to TRUE to reset LAST_TXN_COUNT, LST_ERROr, and LAST_MSG to NULL.
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, 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	The maximum number of seconds to wait for a previous push to the same destination.
execution_seconds	If >0, stop execution cleanly after the specified number of seconds of real time. If transaction_count and execution_seconds are zero (the default), 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 DBMS_DEFER_SYS.PUSH is called from a tight loop.
transaction_count	If > 0, the maximum number of transactions to be pushed before stopping. If transaction_count and execution_seconds are zero (the default), transactions are executed until there are no more in the queue.

DBMS_DEFER_SYS.SET_DISABLED

Purpose

To disable or enable propagation of the deferred transaction queue from the current site to a given destination site. If the disabled parameter is TRUE, the procedure disables propagation to the given destination and future invocations of DBMS_DEFER_SYS.EXECUTE do not push the deferred remote procedure call (RPC) queue. SET_DISABLED affects neither a session already pushing the queue to the given destination nor sessions appending to the queue with DBMS_DEFER. If the disabled parameter is FALSE, the procedure enables propagation to the given destination and, although this does not push the queue, it permits future invocations to DBMS_DEFER_SYS.EXECUTE to push the queue to the given destination. Whether the disabled parameter is TRUE or FALSE, a COMMIT is required for the setting to take effect in other sessions.

Syntax

The parameters for the SET_DISABLED procedure are described in Table 9-43 and the exception is listed in Table 9-44. The syntax for this procedure is shown below:

DBMS_DEFER_SYS.SET_DISABLED(
      destination   IN   VARCHAR2,
      disabled      IN   BOOLEAN := TRUE)

Table 9-43 Parameters for SET_DISABLED

Parameter	Description
destination	The fully qualified database name of the node whose propagation status you want to change.
disabled	By default, this parameter disables propagation of the deferred transaction queue from your current site to the given destination. Set this parameter to FALSE to enable propagation.

Table 9-44 Exception for SET_DISABLED

Exception	Description
NO_DATA_FOUND	No entry was found in the DEFSCHEDULE view for the given DESTINATION.

DBMS_DEFER_SYS.UNREGISTER_PROPAGATOR

Purpose

To unregister a user as the propagator from the local database. This procedure

• Deletes the given propagator from DEFPROPAGATOR.
• Revokes privileges granted by REGISTER_PROPAGATOR from the given user (including identical privileges granted independently).
• Drops any generated wrappers in the schema of the given propagator, and marks them as dropped in the replication catalog.

Syntax

The parameters for the UNREGISTER_PROPAGATOR procedure are described in Table 9-45. The syntax for this procedure is shown below, and the exceptions are listed in Table 9-46:

DBMS_DEFER_SYS.UNREGISTER_PROPAGATOR(
      username  IN  VARCHAR2
      timeout   IN  INTEGER DEFAULT DBMS_LOCK.MAXWAIT)

Table 9-45 Parameters for UNREGISTER_PROPAGATOR

Parameter	Description
username	The name of the propagator user.
timeout	Timeout in seconds. If the propagator is in use, the procedure waits until timeout. The default is DBMS_LOCK.MAXWAIT.

Exception

Table 9-46 Exceptions for UNREGISTER_PROPAGATOR

Parameter	Description
missingpropagator	The given user is not a propagator.
propagator_inuse	The propagator is in use, and thus cannot be unregistered. Try later.

DBMS_DEFER_SYS.UNSCHEDULE_PURGE

Purpose

To stop automatic purges of pushed transactions from the deferred transaction queue at a snapshot or master site.

Syntax

The syntax for this procedure is shown below:

DBMS_DEFER_SYS.UNSCHEDULE_PURGE

DBMS_DEFER_SYS.UNSCHEDULE_PUSH

Purpose

To stop automatic pushes of the deferred transaction queue from a snapshot or master site to another master site.

Syntax

The parameter for the UNSCHEDULE_PUSH procedure is described in Table 9-47, and the exception is described in Table 9-48. The syntax for this procedure is shown below:

DBMS_DEFER_SYS.UNSCHEDULE_PUSH(dblink   IN   VARCHAR2)

Table 9-47 Parameter for UNSCHEDULE_PUSH

Parameter	Description
dblink	Fully qualified pathname to master database site at which you want to unschedule periodic execution of deferred remote procedure calls.

Table 9-48 Exception for UNSCHEDULE_PUSH

Exception	Description
NO_DATA_FOUND	No entry was found in the DEFSCHEDULE view for the given DBLINK.

DBMS_OFFLINE_OG Package

The DBMS_OFFLINE_OG package contains the following procedures:

• DBMS_OFFLINE_OG.BEGIN_INSTANTIATION
• DBMS_OFFLINE_OG.BEGIN_LOAD
• DBMS_OFFLINE_OG.END_INSTANTIATION
• DBMS_OFFLINE_OG.END_LOAD
• DBMS_OFFLINE_OG.RESUME_SUBSET_OF_MASTERS

The following pages discuss each procedure.

DBMS_OFFLINE_OG.BEGIN_INSTANTIATION

Purpose

To start offline instantiation of a replicated object group. You must call this procedure from the master definition site.

Syntax

The parameters for the BEGIN_INSTANTIATION procedure are described in Table 9-49, and the exceptions are listed in Table 9-50. The syntax for this procedure is shown below.

DBMS_OFFLINE_OG.BEGIN_INSTANTIATION(
      gname     IN   VARCHAR2,
      new_site  IN   VARCHAR2)

Table 9-49 Parameters for BEGIN_INSTANTIATION

Parameter	Description
gname	The name of the object group that you want to replicate to the new site.
new_site	The fully qualified database name of the new site to which you want to replicate the object group.

Table 9-50 Exceptions for BEGIN_INSTANTIATION

Exception	Description
badargument	Null or empty string for object group or new master site name.
dbms_repcat.nonmasterdef	This procedure must be called from the master definition site.
sitealreadyexists	Given site is already a master site for this object group.
wrongstate	Status of master definition site must be QUIESCED.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.

DBMS_OFFLINE_OG.BEGIN_LOAD

Purpose

To disable triggers while data is imported to new master site as part of offline instantiation. You must call this procedure from the new master site. See "Snapshot Cloning and Offline Instantiation" on page 7-14.

Syntax

The parameters for the BEGIN_LOAD procedure are described in Table 9-51, and the exceptions are listed in Table 9-52. The syntax for this procedure is shown below.

DBMS_OFFLINE_OG.BEGIN_LOAD(
      gname     IN   VARCHAR2,
      new_site  IN   VARCHAR2)

Table 9-51 Parameters for BEGIN_LOAD

Parameter	Description
gname	The name of the object group whose members you are importing.
new_site	The fully qualified database name of the new site at which you will be importing the object group members.

Table 9-52 Exceptions for BEGIN_LOAD

Exception	Description
badargument	Null or empty string for object group or new master site name.
wrongsite	This procedure must be called from the new master site.
unknownsite	Given site is not recognized by object group.
wrongstate	Status of the new master site must be QUIESCED.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.

DBMS_OFFLINE_OG.END_INSTANTIATION

Purpose

To complete offline instantiation of a replicated object group. You must call this procedure from the master definition site. See "Snapshot Cloning and Offline Instantiation" on page 7-14.

Syntax

The parameters for the END_INSTANTIATION procedure are described in Table 9-53, and the exceptions are listed in Table 9-54. The syntax for this procedure is shown below.

DBMS_OFFLINE_OG.END_INSTANTIATION(
     gname     IN  VARCHAR2,
     new_site  IN  VARCHAR2)

Table 9-53 Parameters for END_INSTANTIATION

Parameter	Description
gname	The name of the object group that you are replicating to the new site.
new_site	The fully qualified database name of the new site to which you are replicating the object group.

Table 9-54 Exceptions for END_INSTANTIATION

Exception	Description
badargument	Null or empty string for object group or new master site name.
dbms_repcat.nonmasterdef	This procedure must be called from the master definition site.
unknownsite	Given site is not recognized by object group.
wrongstate	Status of master definition site must be QUIESCED.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.

DBMS_OFFLINE_OG.END_LOAD

Purpose

To reenable triggers after importing data to new master site as part of offline instantiation. You must call this procedure from the new master site. For additional information, see "Snapshot Cloning and Offline Instantiation" on page 7-14.

Syntax

The parameters for the END_LOAD procedure are described in Table 9-55, and the exceptions are listed in Table 9-56. The syntax for this procedure is shown below.

DBMS_OFFLINE_OG.END_LOAD(
     gname     IN   VARCHAR2,
     new_site  IN   VARCHAR2)

Table 9-55 Parameters for END_LOAD

Parameter	Description
gname	The name of the object group whose members you have finished importing.
new_site	The fully qualified database name of the new site at which you have imported the object group members.

Table 9-56 Exceptions for END_LOAD

Exception	Description
badargument	Null or empty string for object group or new master site name.
wrongsite	This procedure must be called from the new master site.
unknownsite	Given site is not recognized by object group.
wrongstate	Status of the new master site must be QUIESCED.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.

DBMS_OFFLINE_OG.RESUME_SUBSET_OF_MASTERS

Purpose

To resume replication activity at all existing sites except the new site during offline instantiation of a replicated object group. You must call this procedure from the master definition site. For additional information, see "Snapshot Cloning and Offline Instantiation" on page 7-14.

Syntax

The parameters for the RESUME_SUBSET_OF_MASTERS procedure are described in Table 9-57, and the exceptions are listed in Table 9-58. The syntax for this procedure is shown below.

DBMS_OFFLINE_OG.RESUME_SUBSET_OF_MASTERS(
     gname     IN  VARCHAR2,
     new_site  IN  VARCHAR2)

Table 9-57 Parameters for RESUME_SUBSET_OF_MASTERS

Parameter	Description
gname	The name of the object group that you are replicating to the new site.
new_site	The fully qualified database name of the new site to which you are replicating the object group.

Table 9-58 Exceptions for RESUME_SUBSET_OF_MASTERS

Exception	Description
badargument	Null or empty string for object group or new master site name.
dbms_repcat.nonmasterdef	This procedure must be called from the master definition site.
unknownsite	Given site is not recognized by object group.
wrongstate	Status of master definition site must be QUIESCED.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.

DBMS_OFFLINE_SNAPSHOT Package

The DBMS_OFFLINE_SNAPSHOT package contains the following procedures:

• DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD
• DBMS_OFFLINE_SNAPSHOT.END_LOAD

The following pages discuss each procedure.

DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD

Purpose

To prepare a snapshot site for import of a new snapshot as part of offline instantiation. You must call this procedure from the snapshot site for the new snapshot. For additional information, see "Snapshot Cloning and Offline Instantiation" on page 7-14.

Syntax

The parameters for the BEGIN_LOAD procedure are described in Table 9-59, and the exceptions are listed in Table 9-60. The syntax for this procedure is shown below.

DBMS_OFFLINE_SNAPSHOT.BEGIN_LOAD(
     gname               IN   VARCHAR2,
     sname               IN   VARCHAR2,
     master_site         IN   VARCHAR2,
     snapshot_oname      IN   VARCHAR2,
     storage_c           IN   VARCHAR2 := '',
     comment             IN   VARCHAR2 := '',
     min_communication   IN   BOOLEAN  := TRUE)

Table 9-59 Parameters for BEGIN_LOAD

Parameter	Description
gname	The name of the object group for the snapshot that you are creating using offline instantiation.
sname	The name of the schema for the new snapshot.
master_site	The fully qualified database name of the snapshot's master site.
snapshot_oname	The name of the temporary snapshot created at the master site.
storage_c	The storage options to use when creating the new snapshot at the snapshot site.
comment	User comment.
min_communication	If TRUE, the update trigger sends the new value of a column only if the update statement modifies the column. The update trigger sends the old value of the column only if it is a key column or a column in a modified column group.

Table 9-60 Exceptions for BEGIN_LOAD

Exception	Description
badargument	Null or empty string for object group, schema, master site, or snapshot name.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.
missingremotesnap	Could not locate given snapshot at given master site.
dbms_repcat.missingschema	The given schema does not exist.
snaptabmismatch	The base table name of the snapshot at the master and snapshot do not match.

DBMS_OFFLINE_SNAPSHOT.END_LOAD

Purpose

To complete offline instantiation of a snapshot. You must call this procedure from the snapshot site for the new snapshot. For additional information, see "Snapshot Cloning and Offline Instantiation" on page 7-14.

Syntax

The parameters for the END_LOAD procedure are described in Table 9-61, and the exceptions are listed in Table 9-62. The syntax for this procedure is shown below.

DBMS_OFFLINE_SNAPSHOT.END_LOAD(
      gname           IN  VARCHAR2,
      sname           IN  VARCHAR2,
      snapshot_oname  IN  VARCHAR2)

Table 9-61 Parameters for END_LOAD

Parameter	Description
gname	The name of the object group for the snapshot that you are creating using offline instantiation.
sname	The name of the schema for the new snapshot.
snapshot_oname	The name of the snapshot.

Table 9-62 Exceptions for END_LOAD

Exception	Description
badargument	Null or empty string for object group, schema, or snapshot name.
dbms_repcat.missingrepgroup	GNAME does not exist as a replicated object group.
dbms_repcat.nonsnapshot	This procedure must be called from the snapshot site.

DBMS_RECTIFIER_DIFF Package

The DBMS_RECTIFIER_DIFF package contains the following procedures:

• DBMS_RECTIFIER_DIFF.DIFFERENCES
• DBMS_RECTIFIER_DIFF.RECTIFY

The following pages discuss each procedure.

DBMS_RECTIFIER_DIFF.DIFFERENCES

Purpose

To determine the differences between two tables.

Syntax

The parameters for the DIFFERENCES procedure are described in Table 9-63, and the exceptions are listed in Table 9-64. The syntax for this procedure is shown below.

DBMS_RECTIFIER_DIFF.DIFFERENCES(
      sname1               IN  VARCHAR2,
      oname1               IN  VARCHAR2,
      reference_site       IN  VARCHAR2 := '',
      sname2               IN  VARCHAR2,
      oname2               IN  VARCHAR2,
      comparison_site      IN  VARCHAR2 := '',
      where_clause         IN  VARCHAR2 := '',
      { column_list        IN  VARCHAR2 := '', 
      | array_columns      IN  dbms_utility.name_array, }
      missing_rows_sname   IN  VARCHAR2,
      missing_rows_oname1  IN  VARCHAR2,
      missing_rows_oname2  IN  VARCHAR2,
      missing_rows_site    IN  VARCHAR2 := '',
      max_missing          IN  INTEGER,
      commit_rows          IN  INTEGER := 500)

Note: This procedure is overloaded. The COLUMN_LIST and ARRAY_COLUMNS parameters are mutually exclusive.

Table 9-63 Parameters for DIFFERENCES

Parameter	Description
sname1	The name of the schema at REFERENCE_SITE.
oname1	The name of the table at REFERENCE_SITE.
reference_site	The name of the reference database site. The default, NULL, indicates the current site.
sname2	The name of the schema at COMPARISON_SITE.
oname2	The name of the table at COMPARISON_SITE.
comparison_site	The name of the comparison database site. The default, NULL, indicates the current site.
where_clause	Only rows satisfying this restriction are selected for comparison. The default, NULL, indicates the current site.
column_list	A comma-separated list of one or more column names being compared for the two tables. You must not have any white space before or after the comma. The default, NULL, indicates that all columns be compared.
array_columns	A PL/SQL table of column names being compared for the two tables. Indexing begins at 1, and the final element of the array must be NULL. If position 1 is NULL, all columns are used.
missing_rows_sname	The name of the schema containing the tables with the missing rows.
missing_rows_oname1	The name of the table at MISSING_ROWS_SITE that stores information about the rows in the table at REFERENCE site missing from the table at COMPARISON site and the rows at COMPARISON site missing from the table at REFERENCE site.
missing_rows_oname2	The name of the table at MISSING_ROWS_SITE that stores about the missing rows. This table has three columns: the rowid of the row in the MISSING_ROWS_ONAME1 table, the name of the site at which the row is present, and the name of the site from which the row is absent.
missing_rows_site	The name of the site where the MISSING_ROWS_ONAME1 and MISSING_ROWS_ONAME2 tables are located. The default, NULL, indicates that the tables are located at the current site.
max_missing	An integer that refers to the maximum number of rows that should be inserted into the "missing_rows_oname" table. If more than "max_missing" number of rows is missing, that many rows will be inserted into "missing_rows_oname", and the routine then returns normally without determining whether more rows are missing; this argument is useful in the cases that the fragments are so different that the missing rows table will have too many entries and there's no point in continuing. Raises exception badnumber if "max_missing" is less than 1 or NULL.
commit_rows	The maximum number of rows to insert to or delete from the reference or comparison table before a COMMIT occurs. By default, a COMMIT occurs after 500 inserts or 500 deletes. An empty string (' ') or NULL indicates that a COMMIT should only be issued after all rows for a single table have been inserted or deleted.

Table 9-64 Exceptions for DIFFERENCES

Exception	Description
nosuchsite	Database site could not be found.
badnumber	COMMIT_ROWS parameter less than 1.
missingprimarykey	Column list must include primary key (or SET_COLUMNS equivalent).
badname	NULL or empty string for table or schema name.
cannotbenull	Parameter cannot be NULL.
notshapeequivalent	Tables being compared are not shape equivalent. Shape refers to the number of columns, their column names, and the column datatypes.
unknowncolumn	Column does not exist.
unsupportedtype	Type not supported.
dbms_repcat.commfailure	Remote site is inaccessible.
dbms_repcat.missingobject	Table does not exist.

Restrictions

The error ORA-00001 (Unique constraint violated) is issued when there are any unique or primary key constraints on the MISSING_ROWS_DATA table.

DBMS_RECTIFIER_DIFF.RECTIFY

Purpose

To resolve the differences between two tables.

Syntax

The parameters for the RECTIFY procedure are described in Table 9-65, and the exceptions are listed in Table 9-66. The syntax for this procedure is shown below.

DBMS_RECTIFIER_DIFF.RECTIFY(
      sname1               IN  VARCHAR2,
      oname1               IN  VARCHAR2,
      reference_site       IN  VARCHAR2 := '',
      sname2               IN  VARCHAR2,
      oname2               IN  VARCHAR2,
      comparison_site      IN  VARCHAR2 := '',
      { column_list        IN  VARCHAR2 := '', 
      | array_columns      IN  dbms_utility.name_array, }
      missing_rows_sname   IN  VARCHAR2,
      missing_rows_oname1  IN  VARCHAR2,
      missing_rows_oname2  IN  VARCHAR2,
      missing_rows_site    IN  VARCHAR2 := '',
      commit_rows          IN  INTEGER := 500)

Note: This procedure is overloaded. The COLUMN_LIST and ARRAY_COLUMNS parameters are mutually exclusive.

Table 9-65 Parameters for RECTIFY

Parameter	Description
sname1	The name of the schema at REFERENCE_SITE.
oname1	The name of the table at REFERENCE_SITE.
reference_site	The name of the reference database site. The default, NULL, indicates the current site.
sname2	The name of the schema at COMPARISON_SITE.
oname2	The name of the table at COMPARISON_SITE.
comparison_site	The name of the comparison database site. The default, NULL, indicates the current site.
column_list	A comma-separated list of one or more column names being compared for the two tables. You must not have any white space before or after the comma. The default, NULL, indicates that all columns be compared.
array_columns	A PL/SQL table of column names being compared for the two tables. Indexing begins at 1, and the final element of the array must be NULL. If position 1 is NULL, all columns are used.
missing_rows_sname	The name of the schema containing the tables with the missing rows.
missing_rows_oname1	The name of the table at MISSING_ROWS_SITE that stores information about the rows in the table at REFERENCE site missing from the table at COMPARISON site and the rows at COMPARISON site missing from the table at REFERENCE site.
missing_rows_oname2	The name of the table at MISSING_ROWS_SITE that stores about the missing rows. This table has three columns: the rowid of the row in the MISSING_ROWS_ONAME1 table, the name of the site at which the row is present, and the name of the site from which the row is absent.
missing_rows_site	The name of the site where the MISSING_ROWS_ONAME1 and MISSING_ROWS_ONAME2 tables are located. The default, NULL, indicates that the tables are located at the current site.
commit_rows	The maximum number of rows to insert to or delete from the reference or comparison table before a COMMIT occurs. By default, a COMMIT occurs after 500 inserts or 500 deletes. An empty string (' ') or NULL indicates that a COMMIT should only be issued after all rows for a single table have been inserted or deleted.

Table 9-66 Exceptions for RECTIFY

Exception	Description
nosuchsite	Database site could not be found.
badnumber	COMMIT_ROWS parameter less than 1.
badname	NULL or empty string for table or schema name.
dbms_repcat.commfailure	Remote site is inaccessible.
dbms_repcat.missingobject	Table does not exist.

DBMS_REFRESH Package

The DBMS_REFRESH package contains the following procedures:

• DBMS_REFRESH.ADD
• DBMS_REFRESH.CHANGE
• DBMS_REFRESH.DESTROY
• DBMS_REFRESH.MAKE
• DBMS_REFRESH.REFRESH
• DBMS_REFRESH.SUBTRACT

The following pages discuss each procedure.

DBMS_REFRESH.ADD

Purpose

To add snapshots to a refresh group. For additional information, see "Managing Snapshot Refreshes and Refresh Groups" on page 2-37.

Syntax

The parameters for the ADD procedure are described in Table 9-67. The syntax for this procedure is shown below.

DBMS_REFRESH.ADD(
      name     IN VARCHAR2,
      { list   IN VARCHAR2, 
      | tab    IN DBMS_UTILITY.UNCL_ARRAY, }
      lax      IN BOOLEAN := FALSE)

Note: This procedure is overloaded. The LIST and TAB parameters are mutually exclusive.

Table 9-67 Parameters for ADD

Parameter	Description
name	Name of the refresh group to which you want to add members.
list	Comma-separated list of snapshots that you want to add to the refresh group. (Synonyms are not supported.)
tab	Instead of a comma-separated list, you can supply a PL/SQL table of type DBMS_UTILITY.UNCL_ARRAY, where each element is the name of a snapshot. The first snapshot should be in position 1. The last position must be NULL.
lax	A snapshot can belong to only one refresh group at a time. If you are moving a snapshot from one group to another, you must set the LAX flag to TRUE to succeed. Oracle then automatically removes the snapshot from the other refresh group and updates its refresh interval to be that of its new group. Otherwise, the call to ADD generates an error message.

DBMS_REFRESH.CHANGE

Purpose

To change the refresh interval for a snapshot group. For additional information, see "Managing Snapshot Refreshes and Refresh Groups" on page 2-37.

Syntax

The parameters for the CHANGE procedure are described in Table 9-68. The syntax for this procedure is shown below:

DBMS_REFRESH.CHANGE(
      name                  IN VARCHAR2,
      next_date             IN DATE           := NULL,
      interval              IN VARCHAR2       := NULL,
      implicit_destroy      IN BOOLEAN        := NULL,
      rollback_seg          IN VARCHAR2       := NULL,
      push_deferred_rpc     IN BOOLEAN        := NULL,
      refresh_after_errors  IN BOOLEAN        := NULL,
      purge_option          IN BINARY_INTEGER := NULL,
      parallelism           IN BINARY_INTEGER := NULL,
      heap_size             IN BINARY_INTEGER := NULL)

Table 9-68 Parameters for CHANGE

Parameter	Description
name	Name of the refresh group for which you want to alter the refresh interval.
next_date	Next date that you want a refresh to occur. By default, this date remains unchanged.
interval	Function used to calculate the next time to refresh the snapshots in the group. This interval is evaluated immediately before the refresh. Thus, you should select an interval that is greater than the time it takes to perform a refresh. By default, the interval remains unchanged.
implicit_destroy	Allows you to reset the value of the IMPLICIT_DESTROY flag. If this flag is set, Oracle automatically deletes the group if it no longer contains any members. By default, this flag remains unchanged.
rollback_seg	Allows you to change the rollback segment used. By default, the rollback segment remains unchanged. To reset this parameter to use the default rollback segment, specify 'NULL', including the quotes. Specifying NULL without quotes indicates that you do not want to change the rollback segment currently being used.
push_deferred_rpc	Used by updatable snapshots only. Set this parameter to TRUE if you want to push changes from the snapshot to its associated master before refreshing the snapshot. Otherwise, these changes may appear to be temporarily lost. By default, this flag remains unchanged
refresh_after_ errors	Used by updatable snapshots only. Set this parameter to TRUE if you want the refresh to proceed even if there are outstanding conflicts logged in the DEFERROR view for the snapshot's master. By default, this flag remains unchanged.
purge_option	If you are using the parallel propagation mechanism (in other words, parallelism is set to 1 or greater), 0 = don't purge; 1 = lazy (default); 2 = aggressive. In most cases, lazy purge is the optimal setting. Set purge to aggressive to trim back the queue if multiple master replication groups are pushed to different target sites, and updates to one or more replication groups are infrequent and infrequently pushed. If all replication groups are infrequently updated and pushed, set purge to don't purge and occasionally execute PUSH with purge set to aggressive to reduce the queue.
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.

DBMS_REFRESH.DESTROY

Purpose

To remove all of the snapshots from a refresh group and delete the refresh group. For additional information, see "Managing Snapshot Refreshes and Refresh Groups" on page 2-37.

Syntax

The parameter for the DESTROY procedure is described in Table 9-69. The syntax for this procedure is shown below:

DBMS_REFRESH.DESTROY(name   IN   VARCHAR2)

Table 9-69 Parameter for DESTROY

Parameter	Description
name	Name of the refresh group that you want to destroy.

DBMS_REFRESH.MAKE

Purpose

To specify the members of a refresh group and the time interval used to determine when the members of this group should be refreshed. For additional information, see "Managing Snapshot Refreshes and Refresh Groups" on page 2-37.

Syntax

The parameters for the MAKE procedure are described in Table 9-70. The syntax for this procedure is shown below:

DBMS_REFRESH.MAKE(
      name                  IN    VARCHAR2
      { list                IN    VARCHAR2,
      | tab                  IN     DBMS_UTILITY.UNCL_ARRAY,}
      next_date               IN     DATE,
      interval                IN     VARCHAR2,
      implicit_destroy        IN     BOOLEAN         := FALSE,
      lax                     IN     BOOLEAN         := FALSE,
      job                     IN     BINARY INTEGER  := 0,
      rollback_seg            IN     VARCHAR2        := NULL,
      push_deferred_rpc       IN     BOOLEAN         := TRUE,
      refresh_after_errors    IN     BOOLEAN         := FALSE)
      purge_option          IN     BINARY_INTEGER := NULL,
      parallelism           IN     BINARY_INTEGER := NULL,
      heap_size             IN     BINARY_INTEGER := NULL)

Note: This procedure is overloaded. The LIST and TAB parameters are mutually exclusive.

Table 9-70 Parameters for MAKE

Parameter	Description
name	Unique name used to identify the refresh group. Refresh groups must follow the same naming conventions as tables.
list	Comma-separated list of snapshots that you want to refresh. (Synonyms are not supported.) These snapshots can be located in different schemas and have different master tables; however, all of the listed snapshots must be in your current database.
tab	Instead of a comma separated list, you can supply a PL/SQL table of names of snapshots that you want to refresh using the datatype DBMS_UTILITY.UNCL_ARRAY. If the table contains the names of N snapshots, the first snapshot should be in position 1 and the N + 1 position should be set to null.
next_date	Next date that you want a refresh to occur.
interval	Function used to calculate the next time to refresh the snapshots in the group. This field is used with the NEXT_DATE value. For example, if you specify NEXT_DAY(SYSDATE+1, "MONDAY") as your interval, and your NEXT_DATE evaluates to Monday, Oracle will refresh the snapshots every Monday. This interval is evaluated immediately before the refresh. Thus, you should select an interval that is greater than the time it takes to perform a refresh. See "Example Date Expressions" on page 2-26.
implicit_destroy	Set this argument to TRUE if you want to delete the refresh group automatically when it no longer contains any members. Oracle checks this flag only when you call the SUBTRACT procedure. That is, setting this flag still allows you to create an empty refresh group.
lax	A snapshot can belong to only one refresh group at a time. If you are moving a snapshot from an existing group to a new refresh group, you must set the LAX flag to TRUE to succeed. Oracle then automatically removes the snapshot from the other refresh group and updates its refresh interval to be that of its new group. Otherwise, the call to MAKE generates an error message.
job	This parameter is needed by the Import utility. Use the default value, 0.
rollback_seg	Name of the rollback segment to use while refreshing snapshots. The default, null, uses the default rollback segment.
push_deferred_rpc	Used by updatable snapshots only. Use the default value, TRUE, if you want to push changes from the snapshot to its associated master before refreshing the snapshot. Otherwise, these changes may appear to be temporarily lost.
refresh_after_errors	Used by updatable snapshots only. Set this parameter to TRUE if you want the refresh to proceed even if there are outstanding conflicts logged in the DEFERROR view for the snapshot's master.
purge_option	If you are using the parallel propagation mechanism (in other words, parallelism is set to 1 or greater), 0 = don't purge; 1 = lazy (default); 2 = aggressive. In most cases, lazy purge is the optimal setting. Set purge to aggressive to trim back the queue if multiple master replication groups are pushed to different target sites, and updates to one or more replication groups are infrequent and infrequently pushed. If all replication groups are infrequently updated and pushed, set purge to don't purge and occasionally execute PUSH with purge set to aggressive to reduce the queue.
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.

DBMS_REFRESH.REFRESH

Purpose

To manually refresh a refresh group. For additional information, see "Managing Snapshot Refreshes and Refresh Groups" on page 2-37.

Syntax

The parameter for the REFRESH procedure is described in Table 9-71. The syntax for this procedure is shown below:

DBMS_REFRESH.REFRESH(name   IN    VARCHAR2)

Table 9-71 Parameter for REFRESH

Parameter	Description
name	Name of the refresh group that you want to refresh manually.

DBMS_REFRESH.SUBTRACT

Purpose

To remove snapshots from a refresh group. For additional information, see "Managing Snapshot Refreshes and Refresh Groups" on page 2-37.

Syntax

The parameters for the SUBTRACT procedure are described in Table 9-72. The syntax for this procedure is shown below:

DBMS_REFRESH.SUBTRACT(
      name       IN    VARCHAR2,
      { list     IN    VARCHAR2,
      | tab       IN    DBMS_UTILITY.UNCL_ARRAY, }
      lax         IN    BOOLEAN := FALSE)

Note: This procedure is overloaded. The LIST and TAB parameters are mutually exclusive.

Table 9-72 Parameters for SUBTRACT

Parameter	Description
name	Name of the refresh group from which you want to remove members.
list	Comma-separated list of snapshots that you want to remove from the refresh group. (Synonyms are not supported.) These snapshots can be located in different schemas and have different master tables; however, all of the listed snapshots must be in your current database.
tab	Instead of a comma-separated list, you can supply a PL/SQL table of names of snapshots that you want to refresh using the datatype DBMS_UTILITY.UNCL_ARRAY. If the table contains the names of N snapshots, the first snapshot should be in position 1 and the N+1 position should be set to NULL.
lax	Set this parameter to FALSE if you want Oracle to generate an error message if the snapshot you are attempting to remove is not a member of the refresh group.

DBMS_REPCAT Package

The DBMS_REPCAT package includes the following procedures and functions:

• DBMS_REPCAT.ADD_GROUPED_COLUMN
• DBMS_REPCAT.ADD_MASTER_DATABASE
• DBMS_REPCAT.ADD_PRIORITY_datatype
• DBMS_REPCAT.ADD_SITE_PRIORITY_SITE
• DBMS_REPCAT.ADD_conflicttype_RESOLUTION
• DBMS_REPCAT.ALTER_MASTER_PROPAGATION
• DBMS_REPCAT.ALTER_MASTER_REPOBJECT
• DBMS_REPCAT.ALTER_PRIORITY
• DBMS_REPCAT.ALTER_PRIORITY_datatype
• DBMS_REPCAT.ALTER_SITE_PRIORITY
• DBMS_REPCAT.ALTER_SITE_PRIORITY_SITE
• DBMS_REPCAT.ALTER_SNAPSHOT_PROPAGATION
• DBMS_REPCAT.CANCEL_STATISTICS
• DBMS_REPCAT.COMMENT_ON_COLUMN_GROUP
• DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP/
• DBMS_REPCAT.COMMENT_ON_REPGROUP
• DBMS_REPCAT.COMMENT_ON_REPSITES
• DBMS_REPCAT.COMMENT_ON_REPOBJECT
• DBMS_REPCAT.COMMENT_ON_conflicttype_RESOLUTION
• DBMS_REPCAT.CREATE_MASTER_REPGROUP
• DBMS_REPCAT.CREATE_MASTER_REPOBJECT
• DBMS_REPCAT.CREATE_SNAPSHOT_REPGROUP
• DBMS_REPCAT.CREATE_SNAPSHOT_REPOBJECT
• DBMS_REPCAT.DEFINE_COLUMN_GROUP
• DBMS_REPCAT.DEFINE_PRIORITY_GROUP
• DBMS_REPCAT.DEFINE_SITE_PRIORITY
• DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN
• DBMS_REPCAT.DROP_COLUMN_GROUP
• DBMS_REPCAT.DROP_GROUPED_COLUMN
• DBMS_REPCAT.DROP_MASTER_REPGROUP
• DBMS_REPCAT.DROP_MASTER_REPOBJECT
• DBMS_REPCAT.DROP_PRIORITY
• DBMS_REPCAT.DROP_PRIORITY_GROUP
• DBMS_REPCAT.DROP_PRIORITY_datatype
• DBMS_REPCAT.DROP_SITE_PRIORITY
• DBMS_REPCAT.DROP_SITE_PRIORITY_SITE
• DBMS_REPCAT.DROP_SNAPSHOT_REPGROUP
• DBMS_REPCAT.DROP_SNAPSHOT_REPOBJECT
• DBMS_REPCAT.DROP_conflicttype_RESOLUTION
• DBMS_REPCAT.EXECUTE_DDL
• DBMS_REPCAT.GENERATE_REPLICATION_PACKAGE
• DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT
• DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER
• DBMS_REPCAT.GENERATE_SNAPSHOT_SUPPORT
• DBMS_REPCAT.MAKE_COLUMN_GROUP
• DBMS_REPCAT.PURGE_MASTER_LOG
• DBMS_REPCAT.PURGE_STATISTICS
• DBMS_REPCAT.REFRESH_SNAPSHOT_REPGROUP
• DBMS_REPCAT.REGISTER_SNAPSHOT_REPGROUP
• DBMS_REPCAT.REGISTER_STATISTICS
• DBMS_REPCAT.RELOCATE_MASTERDEF
• DBMS_REPCAT.REMOVE_MASTER_DATABASES
• DBMS_REPCAT.REPCAT_IMPORT_CHECK
• DBMS_REPCAT.RESUME_MASTER_ACTIVITY
• DBMS_REPCAT.SEND_AND_COMPARE_OLD_VALUES
• DBMS_REPCAT.SET_COLUMNS
• DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY
• DBMS_REPCAT.SWITCH_SNAPSHOT_MASTER
• DBMS_REPCAT.UNREGISTER_SNAPSHOT_REPGROUP
• DBMS_REPCAT.VALIDATE
• DBMS_REPCAT.WAIT_MASTER_LOG

The following pages discuss each procedure and function.

DBMS_REPCAT.ADD_GROUPED_COLUMN

Purpose

To add members to an existing column group. You must call this procedure from the master definition site.

Syntax

The parameters for the ADD_GROUPED_COLUMN procedure are described in Table 9-73, and the exceptions are listed in Table 9-74. The syntax for this procedure is shown below:

DBMS_REPCAT.ADD_GROUPED_COLUMN( 
      sname,                IN   VARCHAR2,
      oname,                IN   VARCHAR2,
      column_group          IN   VARCHAR2,
      list_of_column_names  IN   VARCHAR2 | DBMS_REPCAT.VARCHAR2S)

Table 9-73 Parameters for ADD_GROUPED_COLUMN

Parameter	Description
sname	The schema in which the replicated table is located.
oname	The name of the replicated table with which the column group is associated.
column_group	The name of the column group to which you are adding members.
list_of_column_names	The names of the columns that you are adding to the designated column group. This can either be a comma-separated list or a PL/SQL table of column names. The PL/SQL table must be of type dbms_repcat.varchar2s. Use the single value `*' to create a column group that contains all of the columns in your table.

Table 9-74 Exceptions for ADD_GROUPED_COLUMN

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingobject	The given table does not exist.
missinggroup	The given column group does not exist.
missingcolumn	A given column does not exist in the designated table.
duplicatecolumn	The given column is already a member of another column group.
missingschema	The given schema does not exist.
notquiesced	The object group that the given table belongs to is not quiesced.

DBMS_REPCAT.ADD_MASTER_DATABASE

Purpose

To add another master site to your replicated environment. This procedure regenerates all the triggers and their associated packages at existing master sites. You must call this procedure from the master definition site.

Syntax

The parameters for the ADD_MASTER_DATABASE procedure are described in Table 9-75, and the exceptions are listed in Table 9-76. The syntax for this procedure is shown below:

DBMS_REPCAT.ADD_MASTER_DATABASE(
      gname                 IN   VARCHAR2,
      master                IN   VARCHAR2, 
      use_existing_objects  IN   BOOLEAN  := TRUE, 
      copy_rows             IN   BOOLEAN  := TRUE,
      comment               IN   VARCHAR2 := '',
      propagation_mode      IN   VARCHAR2 := 'ASYNCHRONOUS')

Table 9-75 Parameters for ADD_MASTER_DATABASE

Parameter	Description
gname	The name of the object group being replicated. This object group must already exist at the master definition site.
master	The fully qualified database name of the new master database.
use_existing_objects	Indicate TRUE if you want to reuse any objects of the same type and shape that already exist in the schema at the new master site. See "Replicating Object Definitions to Master Sites" on page 3-21 for more information on how these changes are applied.
copy_rows	Indicate TRUE if you want the initial contents of a table at the new master site to match the contents of the table at the master definition site.
comment	This comment is added to the MASTER_COMMENT field of the RepSite view.
propagation_mode	Method of forwarding changes to and receiving changes from new master database. Accepted values are SYNCHRONOUS and ASYNCHRONOUS.

Table 9-76 Exceptions for ADD_MASTER_DATABASE

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
notquiesced	The replicated object group has not been suspended.
missingrepgroup	The object group does not exist at the given database site.
commfailure	The new master is not accessible.
typefailure	An incorrect propagation mode was specified.
notcompat	Compatibility mode must be 7.3.0.0 or greater.
duplrepgrp	The master site already exists.

DBMS_REPCAT.ADD_PRIORITY_datatype

Purpose

To add a member to a priority group. You must call this procedure from the master definition site. The procedure that you must call is determined by the datatype of your "priority" column. You must call this procedure once for each of the possible values of the "priority" column.

For additional information, see "Priority Groups and Site Priority" on page 5-20.

Syntax

The parameters for the ADD_PRIORITY_datatype procedure are described in Table 9-77, and the exceptions are listed in Table 9-78. The syntax for the ADD_PRIORITY_datatype procedure is shown below.

DBMS_REPCAT.ADD_PRIORITY_datatype(
      gname              IN   VARCHAR2, 
      pgroup             IN   VARCHAR2, 
      value              IN   datatype, 
      priority           IN   NUMBER)

where datatype:

{ NUMBER
| VARCHAR2
| CHAR
| DATE
| RAW
| NCHAR
| NVARCHAR2 }

Table 9-77 Parameters for ADD_PRIORITY_datatype

Parameter	Description
gname	The replicated object group for which you are creating a priority group.
pgroup	The name of the priority group.
value	The value of the priority group member. This would be one of the possible values of the associated "priority" column of a table using this priority group.
priority	The priority of this value. The higher the number, the higher the priority.

Table 9-78 Exceptions for ADD_PRIORITY_datatype

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
duplicatevalue	The given value already exists in the priority group.
duplicatepriority	The given priority already exists in the priority group.
missingrepgroup	The given replicated object group does not exist.
missingprioritygroup	The given priority group does not exist.
typefailure	The given value has the incorrect datatype for the priority group.
notquiesced	The given replicated object group is not quiesced.

DBMS_REPCAT.ADD_SITE_PRIORITY_SITE

Purpose

To add a new site to a site priority group. You must call this procedure from the master definition site. For additional information, see "Adding a Site to the Group" on page 5-29.

Syntax

The parameters for the ADD_SITE_PRIORITY_SITE procedure are described in Table 9-79, and the exceptions are listed in Table 9-80. The syntax for this procedure is shown below:

DBMS_REPCAT.ADD_SITE_PRIORITY_SITE(
      gname          IN   VARCHAR2, 
      name           IN   VARCHAR2
      site           IN   VARCHAR2,
      priority       IN   NUMBER)

Table 9-79 Parameters for ADD_SITE_PRIORITY_SITE

Parameter	Description
gname	The replicated object group for which you are adding a site to a group.
name	The name of the site priority group to which you are adding a member.
site	The global database name of the site that you are adding.
priority	The priority level of the site that you are adding. A higher number indicates a higher priority level.

Table 9-80 Exceptions for ADD_SITE_PRIORITY_SITE

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
missingpriority	The given site priority group does not exist.
duplicatepriority	The given priority level already exists for another site in the group.
duplicatevalue	The given site already exists in the site priority group.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.ADD_conflicttype_RESOLUTION

Purpose

To designate a method for resolving an update, delete, or uniqueness conflict. You must call these procedures from the master definition site. The procedure that you need to call is determined by the type of conflict that the routine resolves.

Conflict Type	Procedure Name
update	ADD_UPDATE_RESOLUTION
uniqueness	ADD_UNIQUE_RESOLUTION
delete	ADD_DELETE_RESOLUTION

For more information about designating methods to resolve update conflicts, see "Assigning an Update Conflict Resolution Method" on page 5-15. For more information about selecting uniqueness conflict resolution methods, see "Assigning a Uniqueness Conflict Resolution Method" on page 5-33. For more information about assigning delete conflict resolution methods, see "Assigning a Delete Conflict Resolution Method" on page 5-36.

Syntax

The parameters for the ADD_conflicttype_RESOLUTION procedure are described in Table 9-81, and the exceptions are listed in Table 9-82. The syntax for the ADD_UPDATE_RESOLUTION procedure is shown below:

DBMS_REPCAT.ADD_UPDATE_RESOLUTION(
      sname                  IN   VARCHAR2, 
      oname                  IN   VARCHAR2, 
      column_group           IN   VARCHAR2,
      sequence_no            IN   NUMBER,
      method                 IN   VARCHAR2, 
      parameter_column_name  IN   VARCHAR2 | DBMS_REPCAT.VARCHAR2S, 
      priority_group         IN   VARCHAR2     := NULL,
      function_name          IN   VARCHAR2     := NULL,
      comment                IN   VARCHAR2     := NULL)

The syntax for the ADD_DELETE_RESOLUTION procedure is shown below:

DBMS_REPCAT.ADD_DELETE_RESOLUTION(
     sname                  IN   VARCHAR2, 
     oname                  IN   VARCHAR2, 
     sequence_no            IN   NUMBER,
     parameter_column_name  IN   VARCHAR2 | DBMS_REPCAT.VARCHAR2S, 
     function_name          IN   VARCHAR2,
     comment                IN   VARCHAR2     := NULL)

The syntax for the ADD_UNIQUE_RESOLUTION procedure is shown below:

DBMS_REPCAT.ADD_UNIQUE_RESOLUTION(
      sname                 IN   VARCHAR2, 
      oname                 IN   VARCHAR2, 
      constraint_name       IN   VARCHAR2,
      sequence_no           IN   NUMBER,
      method                IN   VARCHAR2, 
      parameter_column_name IN   VARCHAR2 | DBMS_REPCAT.VARCHAR2S, 
      function_name         IN   VARCHAR2     := NULL,
      comment              IN   VARCHAR2     := NULL)

Table 9-81 Parameters for ADD_conflicttype_RESOLUTION

Parameter	Description
sname	The name of the schema containing the table to be replicated.
oname	The name of the table for which you are adding a conflict resolution routine.
column_group	The name of the column group for which you are adding a conflict resolution routine. Column groups are required for update conflict resolution routines only.
constraint_name	The name of the unique constraint or unique index for which you are adding a conflict resolution routine. Use the name of the unique index if it differs from the name of the associated unique constraint. Constraint names are required for uniqueness conflict resolution routines only.
sequence_no	The order in which the designated conflict resolution methods should be applied.
method	The type of conflict resolution routine that you want to create. This can be the name of one of the standard routines provided with advanced replication, or, if you have written your own routine, you should choose USER FUNCTION, and provide the name of your routine as the FUNCTION_NAME argument. The methods supported in this release are: MINIMUM, MAXIMUM, LATEST TIMESTAMP, EARLIEST TIMESTAMP, ADDITIVE, AVERAGE, PRIORITY GROUP, SITE PRIORITY, OVERWRITE, and DISCARD (for update conflicts) and APPEND SITE NAME, APPEND SEQUENCE NUMBER, and DISCARD (for uniqueness conflicts). There are no standard methods for delete conflicts, so this argument is not used.
parameter_column_ name	The name of the columns used to resolve the conflict. The standard methods operate on a single column. For example, if you are using the LATEST TIMESTAMP method for a column group, you should pass the name of the column containing the timestamp value as this argument. If your are using a USER FUNCTION, you can resolve the conflict using any number of columns. This argument accepts either a comma separated list of column names, or a PL/SQL table of type dbms_repcat.varchar2s. The single value `*' indicates that you want to use all of the columns in the table (or column group, for update conflicts) to resolve the conflict. If you specify `*', the columns will be passed to your function in alphabetical order.
priority_group	If you are using the PRIORITY GROUP or SITE PRIORITY update conflict resolution method, you must supply the name of the priority group that you have created. See "Priority Groups and Site Priority" on page 5-20. If you are using a different method, you can use the default value for this argument, NULL. This argument is applicable to update conflicts only.
function_name	If you selected the USER FUNCTION method, or if you are adding a delete conflict resolution routine, you must supply the name of the conflict resolution routine that you have written. If you are using one of the standard methods, you can use the default value for this argument, NULL.
comment	This user comment is added to the RepResolution view.

Table 9-82 Exceptions for ADD_conflicttype_RESOLUTION

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingobject	The given object does not exist as a table in the given schema using row-level replication.
missingschema	The given schema does not exist.
missingcolumn	The column that you specified as part of the PARAMETER_COLUMN_NAME argument does not exist.
missinggroup	The given column group does not exist.
missingprioritygroup	The priority group that you specified does not exist for the table.
invalidmethod	The resolution method that you specified is not recognized.
invalidparameter	The number of columns that you specified for the PARAMETER_COLUMN_NAME argument is invalid. (The standard routines take only one column name.)
missingfunction	The user function that you specified does not exist.
missingconstraint	The constraint that you specified for a uniqueness conflict does not exist.
notquiesced	The object group that the given table belongs to is not quiesced.
duplicateresolution	The given conflict resolution method is already registered.
paramtype	The type is different from the type assigned to the priority group.

DBMS_REPCAT.ALTER_MASTER_PROPAGATION

Purpose

To alter the propagation method for a given object group at a given master site. This object group must be quiesced. You must call this procedure from the master definition site. If the master appears in the dblink_list or dblink_table, ALTER_MASTER_PROPAGATION ignores that database link. You cannot change the propagation mode from a master to itself.

Syntax

The parameters for the ALTER_MASTER_PROPAGATION procedure are described in Table 9-83, and the exceptions are listed in Table 9-84. The syntax for this procedure is shown below:

DBMS_REPCAT.ALTER_MASTER_PROPAGATION(
      gname               IN   VARCHAR2, 
      master              IN   VARCHAR2,
      { dblink_list       IN   VARCHAR2, 
      | dblink_table      IN   dbms_utility.dblink_array,}
      propagation_mode    IN   VARCHAR2 : ='asynchronous',
      comment             IN   VARCHAR2 := '')

Note: This procedure is overloaded. The DBLINK_LIST and DBLINK_TABLE parameters are mutually exclusive.

Table 9-83 Parameters for ALTER_MASTER_PROPAGATION

Parameter	Description
gname	The name of the object group to which to alter the propagation mode.
master	The name of the master site at which to alter the propagation mode.
dblink_list	A comma-separated list of database links for which to alter propagation. If null, all masters except the master site being altered will be used by default.
dblink_table	A PL/SQL table, indexed from position 1, of database links for which to alter propagation.
propagation_mode	Determines the manner in which changes from the given master site are propagated to the sites identified by the list of database links. Appropriate values are SYNCHRONOUS and ASYNCHRONOUS.
comment	This comment is added to the RepProp view.

Table 9-84 Exception for ALTER_MASTER_PROPAGATION

Exception	Description
nonmasterdef	The local site is not the master definition site.
notquiesced	The local site is not quiesced.
typefailure	The propagation mode specified was not recognized.
nonmaster	The list of database links includes a site that is not a master site.

DBMS_REPCAT.ALTER_MASTER_REPOBJECT

Purpose

To alter an object in your replicated environment. You must call this procedure from the master definition site.

Syntax

The parameters for the ALTER_MASTER_REPOBJECT procedure are described in Table 9-85, and the exceptions are listed in Table 9-86. The syntax for this procedure is shown below:

DBMS_REPCAT.ALTER_MASTER_REPOBJECT(
      sname        IN   VARCHAR2, 
      oname        IN   VARCHAR2, 
      type         IN   VARCHAR2, 
      ddl_text     IN   VARCHAR2, 
      comment      IN   VARCHAR2     := '', 
      retry        IN   BOOLEAN      := FALSE)

Note: If the DDL is supplied without specifying a schema, the default schema is the replication administrator's schema. Be sure to specify the schema if it is other than the replication administrator's schema.

Table 9-85 Parameters for ALTER_MASTER_REPOBJECT

Parameter	Description
sname	The schema containing the object that you want to alter.
oname	The name of the object that you want to alter.
type	The type of the object that you are altering. The types supported are: TABLE, INDEX, SYNONYM, TRIGGER, VIEW, PROCEDURE, FUNCTION, PACKAGE, and PACKAGE BODY.
ddl_text	The DDL text that you want used to alter the object. Oracle does not parse this DDL before applying it; therefore, you must ensure that your DDL text provides the appropriate schema and object name for the object being altered.
comment	If not null, this comment will be added to the COMMENT field of the RepObject view.
retry	If retry is TRUE, ALTER_MASTER_REPOBJECT alters the object only at masters whose object status is not VALID.

Table 9-86 Exceptions for ALTER_MASTER_REPOBJECT

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
notquiesced	The associated object group has not been suspended.
missingobject	The object identified by SNAME and ONAME does not exist.
typefailure	The given type parameter is not supported.
ddlfailure	DDL at the master definition site did not succeed.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.ALTER_PRIORITY

Purpose

To alter the priority level associated with a given priority group member. You must call this procedure from the master definition site. See "Altering the Priority of a Member" on page 5-25.

Syntax

The parameters for the ALTER_PRIORITY procedure are described in Table 9-87, and the exceptions are listed in Table 9-88. The syntax for this procedure is shown below:

DBMS_REPCAT.ALTER_PRIORITY(
      gname            IN   VARCHAR2, 
      pgroup           IN   VARCHAR2, 
      old_priority     IN   NUMBER, 
      new_priority     IN   NUMBER)

Table 9-87 Parameters for ALTER_PRIORITY

Parameter	Description
gname	The replicated object group with which the priority group is associated.
pgroup	The name of the priority group containing the priority that you want to alter.
old_priority	The current priority level of the priority group member.
new_priority	The new priority level that you want assigned to the priority group member.

Table 9-88 Exceptions for ALTER_PRIORITY

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
duplicatepriority	The new priority level already exists in the priority group.
missingrepgroup	The given replicated object group does not exist.
missingvalue	The value was not registered by a call to DBMS_REPCAT.ADD_PRIORITY_datatype.
missingprioritygroup	The given priority group does not exist.
notquiesced	The given replicated object group is not quiesced.

DBMS_REPCAT.ALTER_PRIORITY_datatype

Purpose

To alter the value of a member in a priority group. You must call this procedure from the master definition site. The procedure that you must call is determined by the datatype of your "priority" column.

For additional information, see "Altering the Value of a Member" on page 5-25.

Syntax

The parameters for the ALTER_PRIORITY_datatype procedure are described in Table 9-89, and the exceptions are listed in Table 9-90. The syntax for the ALTER_PRIORITY_datatype procedure is shown below.

DBMS_REPCAT.ALTER_PRIORITY_datatype(
      gname        IN   VARCHAR2, 
      pgroup       IN   VARCHAR2, 
      old_value    IN   datatype, 
      new_value    IN   datatype)

where datatype:

{ NUMBER
| VARCHAR2
| CHAR
| DATE
| RAW
| NCHAR
| NVARCHAR2 }

Table 9-89 Parameters for ALTER_PRIORITY_datatype

Parameter	Description
gname	The replicated object group with which the priority group is associated.
pgroup	The name of the priority group containing the value that you want to alter.
old_value	The current value of the priority group member.
new_value	The new value that you want assigned to the priority group member.

Table 9-90 Exceptions for ALTER_PRIORITY_datatype

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
duplicatevalue	The new value already exists in the priority group.
missingrepgroup	The given replicated object group does not exist.
missingprioritygroup	The given priority group does not exist.
missingvalue	The old value does not already exist.
paramtype	The new value has the incorrect datatype for the priority group.
typefailure	The given value has the incorrect datatype for the priority group.
notquiesced	The given replicated object group is not quiesced.

DBMS_REPCAT.ALTER_SITE_PRIORITY

Purpose

To alter the priority level associated with a given site. You must call this procedure from the master definition site. See "Altering the Priority Level of a Site" on page 5-29.

Syntax

The parameters for the ALTER_SITE_PRIORITY procedure are described in Table 9-91, and the exceptions are listed in Table 9-92. The syntax for this procedure is shown below:

DBMS_REPCAT.ALTER_SITE_PRIORITY(
      gname         IN   VARCHAR2,
      name          IN   VARCHAR2
      old_priority  IN   NUMBER,
      new_priority  IN   NUMBER)

Table 9-91 Parameters for ALTER_SITE_PRIORITY

Parameter	Description
gname	The replicated object group with which the site priority group is associated.
name	The name of the site priority group whose member you are altering.
old_priority	The current priority level of the site whose priority level you want to change.
new_priority	The new priority level for the site. A higher number indicates a higher priority level.

Table 9-92 Exceptions for ALTER_SITE_PRIORITY

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
missingpriority	The old priority level is not associated with any group members.
duplicatepriority	The new priority level already exists for another site in the group.
missingvalue	The old value does not already exist.
paramtype	The new value has the incorrect datatype for the priority group.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.ALTER_SITE_PRIORITY_SITE

Purpose

To alter the site associated with a given priority level. You must call this procedure from the master definition site. See "Altering the Site Associated with a Priority Level" on page 5-30.

Syntax

The parameters for the ALTER_SITE_PRIORITY_SITE procedure are described in Table 9-93, and the exceptions are listed in Table 9-94. The syntax for this procedure is shown below:

DBMS_REPCAT.ALTER_SITE_PRIORITY_SITE(
      gname     IN   VARCHAR2,
      name      IN   VARCHAR2
      old_site  IN   VARCHAR2,
      new_site  IN   VARCHAR2)

Table 9-93 Parameters for ALTER_SITE_PRIORITY_SITE

Parameter	Description
gname	The replicated object group with which the site priority group is associated.
name	The name of the site priority group whose member you are altering.
old_site	The current global database name of the site to dissociate from the priority level.
new_site	The new global database name that you want to associate with the current priority level.

Table 9-94 Exceptions for ALTER_SITE_PRIORITY_SITE

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
missingpriority	The given site priority group does not exist.
missingvalue	The old site is not a group member.
notquiesced	The replicated object group is not quiesced

DBMS_REPCAT.ALTER_SNAPSHOT_PROPAGATION

Purpose

To alter the propagation method for a given object group at the current snapshot site. This procedure pushes the deferred transaction queue at the snapshot site, locks the snapshot base tables, and regenerates any triggers and their associated packages. You must call this procedure from the snapshot site.

Syntax

The parameters for the ALTER_SNAPSHOT_PROPAGATION procedure are described in Table 9-95, and the exceptions are listed in Table 9-96. The syntax for this procedure is shown below:

DBMS_REPCAT.ALTER_SNAPSHOT_PROPAGATION(
      gname                IN  VARCHAR2, 
      propagation_mode     IN  VARCHAR2,
      comment              IN  VARCHAR2   := '')

Table 9-95 Parameters for ALTER_SNAPSHOT_PROPAGATION

Parameter	Description
gname	The name of the object group for which to alter propagation mode.
propagation_mode	The manner in which changes from the current snapshot site are propagated to its associated master site. Appropriate values are SYNCHRONOUS and ASYNCHRONOUS.
comment	This comment is added to the RepProp view.

Table 9-96 Exceptions for ALTER_SNAPSHOT_PROPAGATION

Exception	Description
notcompat	Only databases operating in 7.3.0 or later mode can use this procedure.
missingrepgroup	The given replicated object group does not exist.
typefailure	The propagation mode was specified incorrectly.
nonsnapshot	The current site is not a snapshot site for the given object group.
commfailure	Cannot contact master.

DBMS_REPCAT.CANCEL_STATISTICS

Purpose

To stop collecting statistics about the successful resolution of update, uniqueness, and delete conflicts for a table.

Syntax

The parameters for the CANCEL_STATISTICS procedure are described in Table 9-97, and the exceptions are listed in Table 9-98. The syntax for this procedure is shown below:

DBMS_REPCAT.CANCEL_STATISTICS(
      sname    IN   VARCHAR2,
      oname    IN   VARCHAR2)

Table 9-97 Parameters for CANCEL_STATISTICS

Parameter	Description
sname	The name of the schema in which the table is located.
oname	The name of the table for which you do not want to gather conflict resolution statistics.

Table 9-98 Exceptions for CANCEL_STATISTICS

Exception	Description
missingschema	The given schema does not exist.
missingobject	The given table does not exist.
statnotreg	The given table is not currently registered to collect statistics.

DBMS_REPCAT.COMMENT_ON_COLUMN_GROUP

Purpose

To update the comment field in the RepColumn_Group view for a column group. This comment is not added at all master sites until the next call to DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT.

Syntax

The parameters for the COMMENT_ON_COLUMN_GROUP procedure are described in Table 9-99, and the exceptions are listed in Table 9-100. The syntax for this procedure is shown below:

DBMS_REPCAT.COMMENT_ON_COLUMN_GROUP(
      sname           IN   VARCHAR2, 
      oname           IN   VARCHAR2, 
      column_group    IN   VARCHAR2, 
      comment         IN   VARCHAR2)

Table 9-99 Parameters for COMMENT_ON_COLUMN_GROUP

Parameter	Description
sname	The name of the schema in which the object is located.
oname	The name of the replicated table with which the column group is associated.
column_group	The name of the column group.
comment	The text of the updated comment that you want included in the GROUP_COMMENT field of the RepColumn_Group view.

Table 9-100 Exceptions for COMMENT_ON_COLUMN_GROUP

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missinggroup	The given column group does not exist.
missingobj	The object is missing.

DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP/

DBMS_REPCAT.COMMENT_ON_SITE_PRIORITY

Purpose

COMMENT_ON_PRIORITY_GROUP updates the comment field in the REPPRIORITY_GROUP view for a priority group. This comment is not added at all master sites until the next call to DBMS_REPCAT.GENERATE_ REPLICATION_SUPPORT.

COMMENT_ON_SITE_PRIORITY updates the comment field in the REPPRIORITY_GROUP view for a site priority group. This procedure is a wrapper for the COMMENT_ON_COLUMN_GROUP procedure and is provided as a convenience only. This procedure must be issued at the master definition site.

Syntax

The parameters for the COMMENT_ON_PRIORITY_GROUP and COMMENT_ON_SITE_PRIORITY procedures are described in Table 9-101, and the exceptions are listed in Table 9-102.

The syntax for the COMMENT_ON_PRIORITY_GROUP procedure is shown below:

DBMS_REPCAT.COMMENT_ON_PRIORITY_GROUP(
      gname       IN   VARCHAR2, 
      pgroup      IN   VARCHAR2, 
      comment     IN   VARCHAR2)

The syntax for the COMMENT_ON_SITE_PRIORITY procedure is shown below:

DBMS_REPCAT.COMMENT_ON_SITE_PRIORITY(
      gname       IN   VARCHAR2, 
      name        IN   VARCHAR2, 
      comment     IN   VARCHAR2)

Table 9-101 Parameters for COMMENT_ON_PRIORITY_GROUP and COMMENT_ON_SITE_PRIORITY

Parameter	Description
gname	The name of the replicated object group.
pgroup/name	The name of the priority or site priority group.
comment	The text of the updated comment that you want included in the PRIORITY_COMMENT field of the RepPriority_Group view.

Table 9-102 Exceptions for COMMENT_ON_PRIORITY_GROUP and COMMENT_ON_SITE_PRIORITY

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingrepgroup	The given replicated object group does not exist.
missingprioritygroup	The given priority group does not exist.

DBMS_REPCAT.COMMENT_ON_REPGROUP

Purpose

To update the comment field in the REPGROUP view for a replicated object group. This procedure must be issued at the master definition site.

Syntax

The parameters for the COMMENT_ON_REPGROUP procedure are described in Table 9-103, and the exceptions are listed in Table 9-104. The syntax for this procedure is shown below:

DBMS_REPCAT.COMMENT_ON_REPGROUP(
      gname     IN   VARCHAR2,
      comment   IN   VARCHAR2)

Table 9-103 Parameters for COMMENT_ON_REPGROUP

Parameter	Description
gname	The name of the object group that you want to comment on.
comment	The updated comment to include in the SCHEMA_COMMENT field of the RepGroup view.

Table 9-104 Exceptions for COMMENT_ON_REPGROUP

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.COMMENT_ON_REPSITES

Purpose

To update the comment field in the RepSite view for a replicated site. This procedure must be issued at the master definition site.

Syntax

The parameters for the COMMENT_ON_REPSITES procedure are described in Table 9-105, and the exceptions are listed in Table 9-106. The syntax for this procedure is shown below:

DBMS_REPCAT.COMMENT_ON_REPSITES( 
      gname       IN   VARCHAR2, 
      [ master    IN   VARCHAR,] 
      comment     IN   VARCHAR2)

Table 9-105 Parameters for COMMENT_ON_REPSITES

Parameter	Description
gname	The name of the object group. This avoids confusion if a database is a master site in more than one replicated environment.
master	Optional; the fully qualified database name of the master site that you want to comment on. To update comments at a snapshot site, omit this parameter.
comment	The text of the updated comment that you want to include in the MASTER_COMMENT field of the RepSites view.

Table 9-106 Exceptions for COMMENT_ON_REPSITESS

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
nonmaster	The invocation site is not a master site.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.COMMENT_ON_REPOBJECT

Purpose

To update the comment field in the RepObject view for a replicated object. This procedure must be issued at the master definition site.

Syntax

The parameters for the COMMENT_ON_REPOBJECT procedure are described in Table 9-107, and the exceptions are listed in Table 9-108. The syntax for this procedure is shown below:

DBMS_REPCAT.COMMENT_ON_REPOBJECT(
      sname    IN   VARCHAR2, 
      oname    IN   VARCHAR2, 
      type     IN   VARCHAR2, 
      comment  IN   VARCHAR2)

Table 9-107 Parameters for COMMENT_ON_REPOBJECT

Parameter	Description
sname	The name of the schema in which the object is located.
oname	The name of the object that you want to comment on.
type	The type of the object.
comment	The text of the updated comment that you want to include in the OBJECT_COMMENT field of the RepObject view.

Table 9-108 Exceptions for COMMENT_ON_REPOBJECT

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist.
typefailure	The given type parameter is not supported.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.COMMENT_ON_conflicttype_RESOLUTION

Purpose

To update the comment field in the RepResolution view for a conflict resolution routine. The procedure that you need to call is determined by the type of conflict that the routine resolves. These procedures must be issued at the master definition site.

Conflict Type	Procedure Name
update	COMMENT_ON_UPDATE_RESOLUTION
uniqueness	COMMENT_ON_UNIQUE_RESOLUTION
delete	COMMENT_ON_DELETE_RESOLUTION

The comment is not added at all master sites until the next call to DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT.

Syntax

The parameters for the COMMENT_ON_conflicttype_RESOLUTION procedures are described in Table 9-109, and the exceptions are listed in Table 9-110.

The syntax for the COMMENT_ON_UPDATE_RESOLUTION procedure is shown below:

DBMS_REPCAT.COMMENT_ON_UPDATE_RESOLUTION(
      sname                 IN   VARCHAR2,
      oname                 IN   VARCHAR2,
      column_group          IN   VARCHAR2,
      sequence_no           IN   NUMBER, 
      comment               IN   VARCHAR2)

The syntax for the COMMENT_ON_UNIQUE_RESOLUTION procedure is shown below:

DBMS_REPCAT.COMMENT_ON_UNIQUE_RESOLUTION(
      sname                 IN   VARCHAR2,
      oname                 IN   VARCHAR2,
      constraint_name       IN   VARCHAR2,
      sequence_no           IN   NUMBER, 
      comment               IN   VARCHAR2)

The syntax for the COMMENT_ON_DELETE_RESOLUTION procedure is shown below:

DBMS_REPCAT.COMMENT_ON_DELETE_RESOLUTION(
      sname                 IN   VARCHAR2,
      oname                 IN   VARCHAR2,
      sequence_no           IN   NUMBER, 
      comment               IN   VARCHAR2)

Table 9-109 Parameters for COMMENT_ON_conflicttype_RESOLUTION

Parameter	Description
sname	The name of the schema.
oname	The name of the replicated table with which the conflict resolution routine is associated.
column_group	The name of the column group with which the update conflict resolution routine is associated.
constraint_name	The name of the unique constraint with which the uniqueness conflict resolution routine is associated.
sequence_no	The sequence number of the conflict resolution procedure.
comment	The text of the updated comment that you want included in the RESOLUTION_COMMENT field of the RepResolution view.

Table 9-110 Exceptions for COMMENT_ON_conflicttype_RESOLUTION

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist.
missingresolution	SEQUENCE_NO or COLUMN_GROUP is not registered.

DBMS_REPCAT.CREATE_MASTER_REPGROUP

Purpose

To create a new, empty, quiesced master replication object group.

Syntax

The parameters for the CREATE_MASTER_REPGROUP procedure are described in Table 9-111, and the exceptions are listed in Table 9-112. The syntax for this procedure is shown below:

DBMS_REPCAT.CREATE_MASTER_REPGROUP(
      gname            IN   VARCHAR2, 
      group_comment    IN   VARCHAR2     := '', 
      master_comment   IN   VARCHAR2     := ''),
      qualifier        IN   VARCHAR2     := '')

Table 9-111 Parameters for CREATE_MASTER_REPGROUP

Parameter	Description
gname	The name of the object group that you want to create.
group_comment	This comment is added to the RepCat view.
master_comment	This comment is added to the RepGroup view.
qualifier	Connection qualifier for object group. Be sure to use the @ sign, as shown in the example: See "Using Connection Qualifiers for a Master Group" on page 3-16.

Table 9-112 Exceptions for CREATE_MASTER_REPGROUP

Exception	Description
duplicaterepgroup	The object group already exists.
ddlfailure	There is a problem creating the rep$what_am_i package or package body.
norepopt	The advanced replication option is not installed.
missingrepgrp	The object group name was not specified.
qualifiertoolong	Connection qualifier is too long.

DBMS_REPCAT.CREATE_MASTER_REPOBJECT

Purpose

To indicate that an object is a replicated object.

Syntax

The parameters for the CREATE_MASTER_REPOBJECT procedure are shown in Table 9-113, and the exceptions are listed in Table 9-114. The syntax for this procedure is shown below:

DBMS_REPCAT.CREATE_MASTER_REPOBJECT(
      sname                IN   VARCHAR2,
      oname                IN   VARCHAR2, 
      type                 IN   VARCHAR2,
      use_existing_object  IN   BOOLEAN     := TRUE, 
      ddl_text             IN   VARCHAR2    := NULL, 
      comment              IN   VARCHAR2    := '', 
      retry                IN   BOOLEAN     := FALSE
      copy_rows            IN   BOOLEAN     := TRUE,
      gname                IN   VARCHAR2    := '')

Note: If the DDL is supplied without specifying a schema, the default schema is the replication administrator's schema. Be sure to specify the schema if it is other than the replication administrator's schema.

Table 9-113 Parameters for CREATE_MASTER_REPOBJECT

Parameters	Description
sname	The name of the schema in which the object that you want to replicate is located.
oname	The name of the object you are replicating. If DDL_TEXT is NULL, this object must already exist in the given schema. To ensure uniqueness, table names should be a maximum of 27 bytes long, and packages should be no more than 24 bytes.
type	The type of the object that you are replicating. The types supported are: TABLE, INDEX, SYNONYM, TRIGGER, VIEW, PROCEDURE, FUNCTION, PACKAGE, and PACKAGE BODY.
use_existing_object	Indicate TRUE if you want to reuse any objects of the same type and shape at the current master sites. See Table 9-116 for more information on how these changes are applied.
ddl_text	If the object does not already exist at the master definition site, you must supply the DDL text necessary to create this object. PL/SQL packages, package bodies, procedures, and functions must have a trailing semicolon. SQL statements do not end with trailing semicolon. Oracle does not parse this DDL before applying it; therefore, you must ensure that your DDL text provides the appropriate schema and object name for the object being created.
comment	This comment will be added to the OBJECT_COMMENT field of the RepObject view.
retry	Indicate TRUE if you want Oracle to reattempt to create an object that it was previously unable to create. Use RETRY if the error was transient or has since been rectified; for example, if you previously had insufficient resources. If RETRY is TRUE, Oracle creates the object only at master sites whose object status is not VALID.
copy_rows	Indicate TRUE if you want the initial contents of a newly replicated object to match the contents of the object at the master definition site. See Table 9-116 for more information.
gname	The name of the object group in which you want to create the replicated object. The schema name is used as the default object group name if none is specified.

Table 9-114 Exceptions for CREATE_MASTER_REPOBJECT

Exceptions	Description
nonmasterdef	The invocation site is not the master definition site.
notquiesced	The replicated object group has not been suspended.
duplicateobject	The given object already exists in the replicated object group and retry is FALSE, or if a name conflict occurs.
missingobject	The object identified by SNAME and ONAME does not exist and appropriate DDL has not been provided.
typefailure	Objects of the given type cannot be replicated.
ddlfailure	DDL at the master definition site did not succeed.
commfailure	At least one master site is not accessible.
notcompat	Not all remote masters in 7.3 compatibility mode.

Table 9-115 Object Creation at Master Sites

Object Already Exists?	COPY_ROWS	USE_EXISTING_ OBJECTS	Result
yes	TRUE	TRUE	duplicatedobject message if objects do not match. For tables, use data from master definition site.
yes	FALSE	TRUE	duplicatedobject message if objects do not match. For tables, Admin must ensure contents are identical.
yes	TRUE/FALSE	FALSE	duplicatedobject message.
no	TRUE	TRUE/FALSE	Object is created. Tables populated using data from master definition site.
no	FALSE	TRUE/FALSE	Object is created. DBA must populate tables and ensure consistency of tables at all sites.

DBMS_REPCAT.CREATE_SNAPSHOT_REPGROUP

Purpose

To create a new, empty snapshot replication object group in your local database.

Syntax

The parameters for the CREATE_SNAPSHOT_REPGROUP procedure are described in Table 9-116, and the procedures are listed in Table 9-117. The syntax for this procedure is shown below:

DBMS_REPCAT.CREATE_SNAPSHOT_REPGROUP(
      gname              IN   VARCHAR2, 
      master             IN   VARCHAR2, 
      comment            IN   VARCHAR2     := '',
      propagation_mode   IN   VARCHAR2     := 'ASYNCHRONOUS')

Note: CREATE_SNAPSHOT_REPGROUP automatically calls DBMS_REPCAT.REGISTER_SNAPSHOT_REPGROUP, but ignores any errors that may have happened during registration.

Table 9-116 Parameters for CREATE_SNAPSHOT_REPGROUP

Parameter	Description
gname	The name of the replicated object group. This object group must exist at the given master site.
master	The fully qualified database name of the database in the replicated environment to use as the master.
comment	This comment is added to the GROUP_COMMENT field of the RepCat view.
propagation_mode	The method of propagation for all updatable snapshots in the object group. Acceptable values are SYNCHRONOUS and ASYNCHRONOUS.

Table 9-117 Exceptions for CREATE_SNAPSHOT_REPGROUP

Exception	Description
duplicaterepgroup	The object group already exists at the invocation site.
nonmaster	The given database is not a master site.
commfailure	The given database is not accessible.
norepopt	The advanced replication option is not installed.
typefailure	The propagation mode was specified incorrectly.
missingrepgroup	If replicated object group not at master site.
notcompatible	Must be 7.3 compatible.

DBMS_REPCAT.CREATE_SNAPSHOT_REPOBJECT

Purpose

To add a replicated object to your snapshot site.

Syntax

The parameters for the CREATE_SNAPSHOT_REPOBJECT procedure are shown in Table 9-118, and the exceptions are listed in Table 9-119. The syntax for this procedure is shown below:

DBMS_REPCAT.CREATE_SNAPSHOT_REPOBJECT(
     sname          IN   VARCHAR2,
     oname          IN   VARCHAR2, 
     type           IN   VARCHAR2, 
     ddl_text       IN   VARCHAR2  := '',
     comment        IN   VARCHAR2  := '',
     gname          IN   VARCHAR2  := '',
     gen_objs_owner  IN   VARCHAR2 := '',
     min_communication IN BOOLEAN  := TRUE )

Note: If the DDL is supplied without specifying a schema, the default schema is the replication administrator's schema. Be sure to specify the schema if it is other than the replication administrator's schema.

Table 9-118 Parameters for CREATE_SNAPSHOT_REPOBJECT

Parameter	Description
sname	The name of the schema in which the object is located.
oname	The name of the object that you want to add to the replicated snapshot object group. ONAME must exist at the associated master site.
type	The type of the object that you are replicating. The types supported for snapshot sites are: PACKAGE, PACKAGE BODY, PROCEDURE, FUNCTION, SNAPSHOT, SYNONYM, and VIEW.
ddl_text	For objects of type SNAPSHOT, the DDL text needed to create the object; for other types, use the default, '' (an empty string). If a snapshot with the same name already exists, Oracle ignores the DDL and registers the existing snapshot as a replicated object. If the master table for a snapshot does not exist in the replicated object group of the master site designated for this schema, Oracle raises a missingobject error.
comment	This comment is added to the OBJECT_COMMENT field of the RepObject view.
gname	The name of the replicated object group to which you are adding an object. The schema name is used as the default group name if none is specified.
gen_objs_owner	The name of the user you want to assign as owner of the transaction.
min_communication	Set to FALSE if any master site is running Oracle7 release 7.3. Set to TRUE to minimize new and old values of propagation. The default is TRUE. For more information, see "Minimizing Data Propagation for Update Conflict Resolution" on page 5-40.

Table 9-119 Exceptions for CREATE_SNAPSHOT_REPOBJECT

Exception	Description
nonsnapshot	The invocation site is not a snapshot site.
nonmaster	The master is no longer a master site.
missingobject	The given object does not exist in the master's replicated object group.
duplicateobject	The given object already exists with a different shape.
typefailure	The type is not an allowable type.
ddlfailure	The DDL did not succeed.
commfailure	The master site is not accessible.
missingschema	The schema does not exist as a database schema.
badsnapddl	DDL was executed but snapshot does not exist.
onlyonesnap	Only one snapshot for master table can be created.
badsnapname	Snapshot base table differs from master table.
missingrepgroup	Replicated object group does not exist.

DBMS_REPCAT.DEFINE_COLUMN_GROUP

Purpose

To create an empty column group. You must call this procedure from the master definition site. For more information, see "Update Conflict Resolution and Column Groups" on page 5-7.

Syntax

The parameters for the DEFINE_COLUMN_GROUP procedure are described in Table 9-120, and the exceptions are listed in Table 9-121. The syntax for this procedure is shown below:

DBMS_REPCAT.DEFINE_COLUMN_GROUP( 
     sname            IN   VARCHAR2,
     oname            IN   VARCHAR2,
     column_group     IN   VARCHAR2,
     comment          IN   VARCHAR2 := NULL)

Table 9-120 Parameters for DEFINE_COLUMN_GROUP

Parameter	Description
sname	The schema in which the replicated table is located.
oname	The name of the replicated table for which you are creating a column group.
column_group	The name of the column group that you want to create.
comment	This user text is displayed in the RepColumnGroup view.

Table 9-121 Exceptions for DEFINE_COLUMN_GROUP

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingobject	The given table does not exist.
duplicategroup	The given column group already exists for the table.
notquiesced	The object group that the given table belongs to is not quiesced.

DBMS_REPCAT.DEFINE_PRIORITY_GROUP

Purpose

To create a new priority group for a replicated object group. You must call this procedure from the master definition site. See "Priority Groups and Site Priority" on page 5-20.

Syntax

The parameters for the DEFINE_PRIORITY_GROUP procedure are described in Table 9-122, and the exceptions are listed in Table 9-123. The syntax for this procedure is shown below:

DBMS_REPCAT.DEFINE_PRIORITY_GROUP(
     gname         IN   VARCHAR2, 
     pgroup        IN   VARCHAR2, 
     datatype      IN   VARCHAR2, 
     fixed_length  IN   INTEGER := NULL,
     comment       IN   VARCHAR2 := NULL)

Table 9-122 Parameters for DEFINE_PRIORITY_GROUP

Parameter	Description
gname	The replicated object group for which you are creating a priority group.
pgroup	The name of the priority group that you are creating.
datatype	The datatype of the priority group members. The datatypes supported are: CHAR, VARCHAR2, NUMBER, DATE, RAW, NCHAR, and NVARCHAR2.
fixed_length	You must provide a column length for the CHAR datatype. All other types can use the default, NULL.
comment	This user comment is added to the RepPriority view.

Table 9-123 Exceptions for DEFINE_PRIORITY_GROUP

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
duplicateprioritygroup	The given priority group already exists in the replicated object group.
typefailure	The given datatype is not supported.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.DEFINE_SITE_PRIORITY

Purpose

To create a new site priority group for a replicated object group. You must call this procedure from the master definition site. See "Priority Groups and Site Priority" on page 5-20.

Syntax

The parameters for the DEFINE_SITE_PRIORITY procedure are described in Table 9-124, and the exceptions are listed in Table 9-125. The syntax for this procedure is shown below:

DBMS_REPCAT.DEFINE_SITE_PRIORITY(
      gname        IN   VARCHAR2, 
      name         IN   VARCHAR2,
      comment      IN   VARCHAR2 := NULL)

Table 9-124 Parameters for DEFINE_SITE_PRIORITY

Parameter	Description
gname	The replicated object group for which you are creating a site priority group.
name	The name of the site priority group that you are creating.
comment	This user comment is added to the RepPriority view.

Table 9-125 Exceptions for DEFINE_SITE_PRIORITY

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
duplicateprioritygroup	The given site priority group already exists in the replicated object group.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN

Purpose

To execute the local outstanding deferred administrative procedures for the given replicated object group at the current master site, or (with assistance from job queues) for all master sites.

Note: DO_DEFERRED_REPCAT_ADMIN executes only those administrative requests submitted by the connected user that called DO_DEFERRED_ REPCAT_ADMIN. Requests submitted by other users are ignored.

Syntax

The parameters for the DO_DEFERRED_REPCAT_ADMIN procedure are described in Table 9-126, and the exceptions are listed in Table 9-127. The syntax for this procedure is shown below:

DBMS_REPCAT.DO_DEFERRED_REPCAT_ADMIN(
      gname          IN   VARCHAR2,
      all_sites      IN   BOOLEAN := FALSE)

Table 9-126 Parameters for DO_DEFERRED_REPCAT_ADMIN

Parameter	Description
gname	The name of the replicated object group.
all_sites	If ALL_SITES is TRUE, use a job to execute the local administrative procedures at each master.

Table 9-127 Exceptions for DO_DEFERRED_REPCAT_ADMIN

Exception	Description
nonmaster	The invocation site is not a master site.
commfailure	At least one master site is not accessible and all_sites is TRUE.

DBMS_REPCAT.DROP_COLUMN_GROUP

Purpose

To drop a column group. You must call this procedure from the master definition site. See "Using Priority Groups for Update Conflict Resolution" on page 5-22.

Syntax

The parameters for the DROP_COLUMN_GROUP procedure are described in Table 9-128, and the exceptions are listed in Table 9-129. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_COLUMN_GROUP(
      sname        IN   VARCHAR2,
      oname        IN   VARCHAR2,
      column_group IN   VARCHAR2)

Table 9-128 Parameters for DROP_COLUMN_GROUP

Parameter	Description
sname	The schema in which the replicated table is located.
oname	The name of the replicated table whose column group you are dropping.
column_group	The name of the column group that you want to drop.

Table 9-129 Exceptions for DROP_COLUMN_GROUP

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
referenced	The given column group is being used in conflict detection and resolution.
missingobject	The given table does not exist.
missinggroup	The given column group does not exist.
notquiesced	The replicated object group that the table belongs to is not quiesced.

DBMS_REPCAT.DROP_GROUPED_COLUMN

Purpose

To remove members from a column group. You must call this procedure from the master definition site. For more information, see "Adding and Removing Columns in a Column Group" on page 5-14.

Syntax

The parameters for the DROP_GROUPED_COLUMN procedure are described in Table 9-130, and the exceptions are listed in Table 9-131. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_GROUPED_COLUMN(
      sname                 IN   VARCHAR2,
      oname                 IN   VARCHAR2,
      column_group          IN   VARCHAR2,
      list_of_column_names  IN   VARCHAR2 | DBMS_REPCAT.VARCHAR2S)

Table 9-130 Parameters for DROP_GROUPED_COLUMN

Parameter	Description
sname	The schema in which the replicated table is located.
oname	The name of the replicated table in which the column group is located.
column_group	The name of the column group from which you are removing members.
list_of_column_names	The names of the columns that you are removing from the designated column group. This can either be a comma-separated list or a PL/SQL table of column names. The PL/SQL table must be of type dbms_repcat.varchar2s.

Table 9-131 Exceptions for DROP_GROUPED_COLUMN

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingobject	The given table does not exist.
notquiesced	The replicated object group that the table belongs to is not quiesced.

DBMS_REPCAT.DROP_MASTER_REPGROUP

Purpose

To drop a replicated object group from your current site. To drop the replicated object group from all master sites, including the master definition site, you can call this procedure at the master definition site, and set the final argument to TRUE.

Syntax

The parameters for the DROP_MASTER_REPGROUP procedure are described in Table 9-132, and the exceptions are listed in Table 9-133. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_MASTER_REPGROUP(
      gname             IN VARCHAR2,
      drop_contents     IN BOOLEAN    := FALSE,
      all_sites         IN BOOLEAN     := FALSE)

Table 9-132 Parameters for DROP_MASTER_REPGROUP

Parameter	Description
gname	The name of the replicated object group that you want to drop from the current master site.
drop_contents	By default, when you drop the object group at a master site, all of the objects remain in the schema. They simply are no longer replicated; that is, the replicated objects in the object group no longer send changes to, or receive changes from, other master sites. If you set this argument to TRUE, any replicated objects in the replicated object group are dropped from their associated schemas.
all_sites	If ALL_SITES is TRUE and the invocation site is the master definition site, the procedure synchronously multicasts the request to all masters. In this case, execution is immediate at the master definition site and may be deferred at all other master sites.

Table 9-133 Exceptions for DROP_MASTER_REPGROUP

Exception	Description
nonmaster	The invocation site is not a master site.
nonmasterdef	The invocation site is not the master definition site and ALL_SITES is TRUE.
commfailure	At least one master site is not accessible and ALL_SITES is TRUE.
fullqueue	The deferred RPC queue has entries for the replicated object group.
masternotremoved	Master does not recognize the masterdef.

DBMS_REPCAT.DROP_MASTER_REPOBJECT

Purpose

To drop a replicated object from a replicated object group. You must call this procedure from the master definition site.

Syntax

The parameters for the DROP_MASTER_REPOBJECT procedure are described in Table 9-134, and the exceptions are listed in Table 9-135. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_MASTER_REPOBJECT(
      sname          IN   VARCHAR2, 
      oname          IN   VARCHAR2, 
      type           IN   VARCHAR2, 
      drop_objects   IN   BOOLEAN     := FALSE)

Table 9-134 Parameters for DROP_MASTER_REPOBJECT

Parameter	Description
sname	The name of the schema in which the object is located.
oname	The name of the object that you want to remove from the replicated object group.
type	The type of object that you want to drop.
drop_objects	By default, the object remains in the schema, but is dropped from the replicated object group; that is, any changes to the object are no longer replicated to other master and snapshot sites. To completely remove the object from the replicated environment, set this argument to TRUE.

Table 9-135 Exceptions for DROP_MASTER_REPOBJECT

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist.
typefailure	The given type parameter is not supported.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.DROP_PRIORITY

Purpose

To drop a member of a priority group by priority level. You must call this procedure from the master definition site. See "Dropping a Member by Priority" on page 5-27.

Syntax

The parameters for the DROP_PRIORITY procedure are described in Table 9-136, and the exceptions are listed in Table 9-137. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_PRIORITY(
      gname          IN   VARCHAR2,
      pgroup         IN   VARCHAR2, 
      priority_num   IN   NUMBER)

Table 9-136 Parameters for DROP_PRIORITY

Parameter	Description
gname	The replicated object group with which the priority group is associated.
pgroup	The name of the priority group containing the member that you want to drop.
priority_num	The priority level of the priority group member that you want to remove from the group.

Table 9-137 Exceptions for DROP_PRIORITY

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
missingprioritygroup	The given priority group does not exist.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.DROP_PRIORITY_GROUP

Purpose

To drop a priority group for a given replicated object group. You must call this procedure from the master definition site. See "Dropping a Priority Group" on page 5-27.

Syntax

The parameters for the DROP_PRIORITY_GROUP procedure are described in Table 9-138, and the exceptions are listed in Table 9-139. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_PRIORITY_GROUP(
      gname     IN   VARCHAR2,
      pgroup    IN   VARCHAR2)

Table 9-138 Parameters for DROP_PRIORITY_GROUP

Parameter	Description
gname	The replicated object group with which the priority group is associated.
pgroup	The name of the priority group that you want to drop.

Table 9-139 Exceptions for DROP_PRIORITY_GROUP

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
referenced	The given priority group is being used in conflict resolution.
notquiesced	The given replicated object group is not quiesced.

DBMS_REPCAT.DROP_PRIORITY_datatype

Purpose

To drop a member of a priority group by value. You must call this procedure from the master definition site. The procedure that you must call is determined by the datatype of your "priority" column. See "Dropping a Member by Value" on page 5-26.

Syntax

The parameters for the DROP_PRIORITY_datatype procedure are described in Table 9-140, and the exceptions are listed in Table 9-141. The syntax for the DROP_PRIORITY_datatype procedure is shown below.

DBMS_REPCAT.DROP_PRIORITY_datatype(
      gname    IN   VARCHAR2,
      pgroup   IN   VARCHAR2, 
      value    IN   datatype)

where datatype:

{ NUMBER
| VARCHAR2
| CHAR
| DATE
| RAW
| NCHAR
| NVARCHAR2 }

Table 9-140 Parameters for DROP_PRIORITY_datatype

Parameter	Description
gname	The replicated object group with which the priority group is associated.
pgroup	The name of the priority group containing the member that you want to drop.
value	The value of the priority group member that you want to remove from the group.

Table 9-141 Exceptions for DROP_PRIORITY_datatype

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
missingprioritygroup	The given priority group does not exist.
paramtype, typefailure	The value has the incorrect datatype for the priority group.
notquiesced	The given replicated object group is not quiesced

DBMS_REPCAT.DROP_SITE_PRIORITY

Purpose

To drop a site priority group for a given replicated object group. You must call this procedure from the master definition site. See "Dropping a Site Priority Group" on page 5-30.

Syntax

The parameters for the DROP_SITE_PRIORITY procedure are described in Table 9-142, and the exceptions are listed in Table 9-143. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_SITE_PRIORITY(
      gname      IN   VARCHAR2,
      name       IN   VARCHAR2)

Table 9-142 Parameters for DROP_SITE_PRIORITY

Parameter	Description
gname	The replicated object group with which the site priority group is associated.
name	The name of the site priority group that you want to drop.

Table 9-143 Exceptions for DROP_SITE_PRIORITY

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
referenced	The given site priority group is being used in conflict resolution.
notquiesced	The given replicated object group is not quiesced

DBMS_REPCAT.DROP_SITE_PRIORITY_SITE

Purpose

To drop a given site, by name, from a site priority group. You must call this procedure from the master definition site. See "Dropping a Site by Site Name" on page 5-30.

Syntax

The parameters for the DROP_SITE_PRIORITY_SITE procedure are described in Table 9-144, and the exceptions are listed in Table 9-145. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_SITE_PRIORITY_SITE(
      gname      IN   VARCHAR2, 
      name       IN   VARCHAR2,
      site       IN   VARCHAR2)

Table 9-144 Parameters for DROP_SITE_PRIORITY_SITE

Parameter	Description
gname	The replicated object group with which the site priority group is associated.
name	The name of the site priority group whose member you are dropping.
site	The global database name of the site you are removing from the group.

Table 9-145 Exceptions for DROP_SITE_PRIORITY_SITE

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingrepgroup	The given replicated object group does not exist.
missingpriority	The given site priority group does not exist.
missingsite	The given site does not exist.
notquiesced	The given replicated object group is not quiesced.

DBMS_REPCAT.DROP_SNAPSHOT_REPGROUP

Purpose

To drop a snapshot site from your replicated environment.

Syntax

The parameters for the DROP_SNAPSHOT_REPGROUP procedure are described in Table 9-146, and the exceptions are listed in Table 9-147. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_SNAPSHOT_REPGROUP(
     gname                 IN   VARCHAR2, 
     drop_contents         IN   BOOLEAN   := FALSE)

Note: DBMS_REPCAT.DROP_SNAPSHOT_REPGROUP automatically calls DBMS_REPCAT.REGISTER_SNAPSHOT_ REPGROUP to unregister the snapshot, but ignores any errors that may have occurred during unregistration.

Table 9-146 Parameters for DROP_SNAPSHOT_REPGROUP

Parameter	Description
gname	The name of the replicated object group that you want to drop from the current snapshot site. All objects generated to support replication, such as triggers and packages, are dropped.
drop_contents	By default, when you drop the replicated object group at a snapshot site, all of the objects remain in their associated schemas; they simply are no longer replicated. If you set this argument to TRUE, any replicated objects in the replicated object group are dropped from their schemas.

Table 9-147 Exceptions for DROP_SNAPSHOT_REPGROUP

Exception	Description
nonsnapshot	The invocation site is not a snapshot site.
missrepgrp	The specified object group does not exist.

DBMS_REPCAT.DROP_SNAPSHOT_REPOBJECT

Purpose

To drop a replicated object from a snapshot site.

Syntax

The parameters for the DROP_SNAPSHOT_REPOBJECT procedure are described in Table 9-148, and the exceptions are listed in Table 9-149. The syntax for this procedure is shown below:

DBMS_REPCAT.DROP_SNAPSHOT_REPOBJECT( 
     sname          IN   VARCHAR2, 
     oname          IN   VARCHAR2, 
     type           IN   VARCHAR2, 
     drop_objects   IN   BOOLEAN  := FALSE)

Table 9-148 Parameters for DROP_SNAPSHOT_REPOBJECT

Parameter	Description
sname	The name of the schema in which the object is located.
oname	The name of the object that you want to drop from the replicated object group.
type	The type of the object that you want to drop.
drop_objects	By default, the object remains in its associated schema, but is dropped from its associated object group. To completely remove the object from its schema at the current snapshot site, set this argument to TRUE.

Table 9-149 Exceptions for DROP_SNAPSHOT_REPOBJECT

Exception	Description
nonsnapshot	The invocation site is not a snapshot site.
missingobject	The given object does not exist.
typefailure	The given type parameter is not supported.

DBMS_REPCAT.DROP_conflicttype_RESOLUTION

Purpose

To drop an update, delete, or uniqueness conflict resolution routine. You must call these procedures from the master definition site. The procedure that you must call is determined by the type of conflict that the routine resolves.

Conflict Type	Procedure Name
update	DROP_UPDATE_RESOLUTION
uniqueness	DROP_UNIQUE_RESOLUTION
delete	DROP_DELETE_RESOLUTION

Syntax

The parameters for the DROP_conflicttype_RESOLUTION procedure are described in Table 9-150, and the exceptions are listed in Table 9-151. The syntax for the DROP_UPDATE_RESOLUTION procedure is shown below:

DBMS_REPCAT.DROP_UPDATE_RESOLUTION(
     sname              IN   VARCHAR2, 
     oname              IN   VARCHAR2, 
     column_group       IN   VARCHAR2, 
     sequence_no        IN   NUMBER)

The syntax for the DROP_DELETE_RESOLUTION procedure is shown below:

DBMS_REPCAT.DROP_DELETE_RESOLUTION(
     sname              IN   VARCHAR2, 
     oname              IN   VARCHAR2, 
     sequence_no        IN   NUMBER)

The syntax for the DROP_UNIQUE_RESOLUTION procedure is shown below:

DBMS_REPCAT.DROP_UNIQUE_RESOLUTION(
     sname              IN   VARCHAR2, 
     oname              IN   VARCHAR2, 
     constraint_name    IN  VARCHAR2, 
     sequence_no        IN  NUMBER)

Table 9-150 Parameters for DROP_conflicttype_RESOLUTION

Parameter	Description
sname	The schema in which the table is located.
oname	The name of the table for which you want to drop a conflict resolution routine.
column_group	The name of the column group for which you want to drop an update conflict resolution routine.
constraint_name	The name of the Unique constraint for which you want to drop a unique conflict resolution routine.
sequence_no	The sequence number assigned to the conflict resolution method that you want to drop. This number uniquely identifies the routine.

Table 9-151 Exceptions for DROP_conflicttype_RESOLUTION

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
missingobject	The given object does not exist as a table in the given schema, or a conflict resolution routine with the given sequence number is not registered.
referenced	The conflict resolution routine is being used in conflict resolution.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.EXECUTE_DDL

Purpose

To supply DDL that you want to have executed at each master site. You can call this procedure only from the master definition site.

Syntax

The parameters for the EXECUTE_DDL procedure are described in Table 9-152, and the exceptions are listed in Table 9-153. The syntax for this procedure is shown below:

DBMS_REPCAT.EXECUTE_DDL(
     gname           IN   VARCHAR2,
     { master_list   IN   VARCHAR2     := NULL, 
     | master_table  IN   DBMS_UTILITY.DBLINK_ARRAY,}
     DDL_TEXT        IN   VARCHAR2)

Note: If the DDL is supplied without specifying a schema, the default schema is the replication administrator's schema. Be sure to specify the schema if it is other than the replication administrator's schema. This procedure is overloaded. The MASTER_LIST and MASTER_TABLE parameters are mutually exclusive.

Table 9-152 Parameters for EXECUTE_DDL

Parameter	Description
gname	The name of the replicated object group.
master_list	A comma-separated list of master sites at which you want to execute the supplied DDL. There must be no extra white space between site names. The default value, NULL, indicates that the DDL should be executed at all sites, including the master definition site.
master_table	A table of master sites at which you want to execute the supplied DDL. The first master should be at offset 1, the second at offset 2, and so on.
ddl_text	The DDL that you want to have executed at each of the given master sites.

Table 9-153 Exceptions for EXECUTE_DDL

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
nonmaster	At least one site is not a master site.
ddlfailure	DDL at the master definition site did not succeed.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.GENERATE_REPLICATION_PACKAGE

Purpose

To provide more fine-grained control of replication support generation. Primarily used for environments that include Oracle7 Release 7.3 sites. Generates the packages needed to support replication for a given table at all master sites. You must call this procedure from the master definition site.

Syntax

The parameters for the GENERATE_REPLICATION_PACKAGE procedure are described in Table 9-154, and the exceptions are listed in Table 9-155. The syntax for this procedure is shown below:

DBMS_REPCAT.GENERATE_REPLICATION_PACKAGE(
      sname  IN    VARCHAR2, 
      oname  IN    VARCHAR2)

Table 9-154 Parameters for GENERATE_REPLICATION_PACKAGE

Parameter	Description
sname	The schema in which the table is located.
oname	The name of the table for which you are generating replication support.

Table 9-155 Exceptions for GENERATE_REPLICATION_PACKAGE

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist as a table in the given schema awaiting row-level replication information or as a procedure or package (body) awaiting wrapper generation.
commfailure	At least one master site is not accessible.
notcompat	This procedure requires release 7.3 or greater.
notquiesced	The replicated object group was not quiesced.

DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT

Purpose

To generate the triggers, packages, and procedures needed to support replication. You must call this procedure from the master definition site.

Syntax

The parameters for the GENERATE_REPLICATION_SUPPORT procedure are described in Table 9-156, and the exceptions are listed in Table 9-157. The syntax for this procedure is shown below:

DBMS_REPCAT.GENERATE_REPLICATION_SUPPORT(
  sname                  IN    VARCHAR2, 
  oname                  IN    VARCHAR2, 
  type                   IN    VARCHAR2, 
  package_prefix         IN    VARCHAR2   := NULL, 
  procedure_prefix       IN    VARCHAR2   := NULL, 
  distributed            IN    BOOLEAN    := TRUE,
  gen_objs_owner         IN    VARCHAR2   := NULL,
  min_communication      IN    BOOLEAN    := TRUE )

Table 9-156 Parameters for GENERATE_REPLICATION_SUPPORT

Parameter	Description
sname	The schema in which the object is located.
oname	The name of the object for which you are generating replication support.
type	The type of the object. The types supported are: TABLE, PACKAGE, and PACKAGE BODY.
package_prefix	For objects of type PACKAGE or PACKAGE BODY this value is prepended to the generated wrapper package name. The default is DEFER_.
procedure_prefix	For objects of type PROCEDURE, PACKAGE or PACKAGE BODY, this value is prepended to the generated wrapper procedure names. By default, no prefix is assigned. The default is DEFER_.
distributed	This parameter must be set to TRUE if your COMPATIBLE parameter is set to 7.3.0 or greater.
gen_objs_owner	The name of the user you want to use as owner of the transaction.
min_communication	Set to FALSE if any master site is running Oracle7 release 7.3. Set to TRUE when you want propagation of new and old values to be minimized. The default is TRUE. For more information, see "Minimizing Data Propagation for Update Conflict Resolution" on page 5-40.

Table 9-157 Exceptions for GENERATE_REPLICATION_SUPPORT

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist as a table in the given schema awaiting row-level replication information or as a procedure or package (body) awaiting wrapper generation.
typefailure	The given type parameter is not supported.
notquiesced	The replicated object group has not been suspended.
commfailure	At least one master site is not accessible.
missschema	Schema does not exist.
dbnotcompatible	One of the masters is not 7.3 compatible.
duplicateobject	Object already exists.

DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER

Purpose

To provide more fine-grained control of replication support generation. Primarily used for environments that include Oracle7 Release 7.3 sites. Generates the triggers and their associated packages needed to support replication for a given object at all master sites, or to generate the triggers and their associated packages needed to support replication for all of the objects in a given object group at a list of master sites. You must call this procedure from the master definition site. The associated object group must be quiesced.

Syntax

The parameters for the GENERATE_REPLICATION_TRIGGER procedure are described in Table 9-158, and the exceptions are listed in Table 9-159. This syntax for this procedure is shown below:

DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER(
      sname                      IN  VARCHAR2, 
      oname                      IN  VARCHAR2,
      gen_objs_owner             IN  VARCHAR2 := NULL
      min_communication          IN  BOOLEAN  := TRUE)
DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER(
      gname                      IN  VARCHAR2, 
      gen_objs_owner             IN  VARCHAR2 := NULL
      min_communication          IN  BOOLEAN  := NULL)

Attention: The GENERATE_REPLICATION_TRIGGER procedure is overloaded to allow you to generate support for a single object at all master sites or for an object group at a list of sites. Because the parameter types are the same for both calls, you may need to use named notation to indicate whether you are calling the procedure for a single object or for an object group.

Attention: If you want to generate support for a list of master sites (that is, if you will not be using the default, NULL), you must use either an array or named notation.

Table 9-158 Parameters for GENERATE_REPLICATION_TRIGGER

Parameter	Description
sname	The schema in which the object is located.
oname	The name of the object for which you are generating replication support.
gname	The name of the object group for which you want to generate support.
gen_objs_owner	This parameter is provided for compatibility with previous releases. If you have any pre-release 7.3 snapshot sites, you must set this parameter to TRUE.
min_communication	Set to FALSE if any master site is running Oracle7 release 7.3. Set to TRUE when you want propagation of new and old values to be minimized. The default is varies. For more information, see "Minimizing Data Propagation for Update Conflict Resolution" on page 5-40.

Table 9-159 Exceptions for GENERATE_REPLICATION_TRIGGER

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist as a table in the given schema awaiting row-level replication information or as a procedure or package (body) awaiting wrapper generation.
notquiesced	The replicated object group has not been suspended.
commfailure	At least one master site is not accessible.
notcompat	One of the masters is not 7.3 compatible.
missingschema	The given schema does not exist.

Altering Propagation Mode

After altering the propagation mode of an object group, you need to regenerate the supporting PL/SQL triggers for these objects at each Oracle7 Release 7.3 site in the replicated environment. Internal triggers automatically change propagation mode as directed by ALTER_MASTER_PROPAGATION and are not affected by attempts to regenerate triggers.

To generate the supporting PL/SQL triggers and their associated packages for all Oracle7 release 7.3 members of an object group for a given set of master sites, call the DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER procedure, as shown in the following example:

DBMS_REPCAT.GENERATE_REPLICATION_TRIGGER( gname => 'acct');

Because no list of master sites is specified in this example, Oracle regenerates the supporting triggers and their associated packages for the objects in the GNAME object group at all Oracle7 release 7.3 master sites. You must call this procedure from the master definition site for the given replicated object group. Oracle must successfully create the necessary triggers at the master definition site for this procedure to complete successfully. These objects are asynchronously created at the other master sites as described

DBMS_REPCAT.GENERATE_SNAPSHOT_SUPPORT

PURPOSE

To activate triggers and generate packages needed to support the replication of updatable snapshots or procedural replication.You must call this procedure from the snapshot site.

SYNTAX

The parameters for the GENERATE_SNAPSHOT_SUPPORT procedure are described in Table 9-160, and the exceptions are listed in Table 9-161. The syntax for this procedure is shown below:

DBMS_REPCAT.GENERATE_SNAPSHOT_SUPPORT
      sname              IN VARCHAR2,
      oname              IN VARCHAR2,
      type               IN VARCHAR2,
      gen_objs_owner     IN VARCHAR2 := '',
      min_communication  IN BOOLEAN  := TRUE)

Note: CREATE_SNAPSHOT_REPOBJECT automatically generates snapshot support for updatable snapshots.

Table 9-160 Parameters for GENERATE_SNAPSHOT_SUPPORT

Parameter	Description
sname	The schema in which the object is located.
oname	If the object exists in the replicated snapshot object group as an updatable snapshot using row/column level replication, generate the row-level replication trigger and stored packages.
type	Type of the object. The types supported are SNAPSHOT, PACKAGE, and PACKAGE BODY.
gen_objs_owner	Specifies the schema in which the generated replication trigger and trigger package or wrapper is installed. If NULL, the generated trigger and trigger package or wrapper are installed in the schema specified by the sname parameter.
min_communication	If TRUE, the update trigger sends the new value of a column only if the update statement modifies the column. The update trigger sends the old value of the column only if it is a key column or a column in a modified column group.

Table 9-161 Exceptions for GENERATE_SNAPSHOT_SUPPORT

Exceptions	Descriptions
nonsnapshot	The invocation site is not a snapshot site.
missingobject	The given object does not exist as a snapshot in the replicated schema awaiting row/column-level replication information or as a procedure or package (body) awaiting wrapper generation.
typefailure	The given type parameter is not supported.
missingschema	The specified owner of generated objects does not exist.
missingremoteobject	The master object has not yet generated replication support.
commfailure	The master is not accessible.

DBMS_REPCAT.MAKE_COLUMN_GROUP

Purpose

To create a new column group with one or more members. You must call this procedure from the master definition site. For more information, see "Creating a Column Group" on page 5-13.

Syntax

The parameters for the MAKE_COLUMN_GROUP procedure are described in Table 9-162, and the exceptions are listed in Table 9-163. The syntax for this procedure is shown below:

DBMS_REPCAT.MAKE_COLUMN_GROUP( 
     sname                 IN   VARCHAR2,
     oname                 IN   VARCHAR2,
     column_group          IN   VARCHAR2,
     list_of_column_names  IN   VARCHAR2 | DBMS_REPCAT.VARCHAR2S)

Table 9-162 Parameters for MAKE_COLUMN_GROUP

Parameter	Description
sname	The schema in which the replicated table is located.
oname	The name of the replicated table for which you are creating a new column group.
column_group	The name that you want assigned to the column group that you are creating.
list_of_column_names	The names of the columns that you are grouping. This can either be a comma-separated list or a PL/SQL table of column names. The PL/SQL table must be of type dbms_repcat.varchar2s. Use the single value `*' to create a column group that contains all of the columns in your table.

Table 9-163 Exceptions for MAKE_COLUMN_GROUP

Exception	Description
nonmasterdef	The invocation site is not the masterdef site.
duplicategroup	The given column group already exists for the table.
missingobject	The given table does not exist.
missingcolumn	The given column does not exist in the designated table.
duplicatecolumn	The given column is already a member of another column group.
notquiesced	The replicated object group is not quiesced.

DBMS_REPCAT.PURGE_MASTER_LOG

Purpose

To remove local messages in the RepCatLog associated with a given identification number, source, or replicated object group.

Syntax

The parameters for the PURGE_MASTER_LOG procedure are described in Table 9-164, and the exception is listed in Table 9-165. If any parameter is NULL, Oracle treats it as a wildcard. The syntax for this procedure is shown below:

DBMS_REPCAT.PURGE_MASTER_LOG(
      id      IN   NATURAL, 
      source  IN   VARCHAR2, 
      gname   IN   VARCHAR2)

Table 9-164 Parameters for PURGE_MASTER_LOG

Parameter	Description
id	The identification number of the request, as it appears in the RepCatLog view.
source	The master site from which the request originated.
gname	The name of the replicated object group for which the request was made.

Table 9-165 Exception for PURGE_MASTER_LOG

Exception	Description
nonmaster	GNAME is not NULL and the invocation site is not a master site.

DBMS_REPCAT.PURGE_STATISTICS

Purpose

To remove information from the RepResolution_Statistics view.

Syntax

The parameters for the PURGE_STATISTICS procedure are described in Table 9-166, and the exceptions are listed in Table 9-167. The syntax for this procedure is shown below:

DBMS_REPCAT.PURGE_STATISTICS(
      sname      IN   VARCHAR2, 
      oname      IN   VARCHAR2, 
      start_date IN   DATE,
      end_date   IN   DATE)

Table 9-166 Parameters for PURGE_STATISTICS

Parameter	Description
sname	The name of the schema in which the replicated table is located.
oname	The name of the table whose conflict resolution statistics you want to purge.
start_date/end_date	The range of dates for which you want to purge statistics. If START_DATE is NULL, purge all statistics up to the END_DATE. If END_DATE is NULL, purge all statistics after the START_DATE.

Table 9-167 Exceptions for PURGE_STATISTICS

Exception	Description
missingschema	The given schema does not exist.
missingobject	The given table does not exist.
statnotreg	Table not registered to collect statistics.

DBMS_REPCAT.REFRESH_SNAPSHOT_REPGROUP

Purpose

To refresh a snapshot site object group with the most recent data from its associated master site.

Syntax

The parameters for the REFRESH_SNAPSHOT_REPGROUP procedure are described in Table 9-168, and the exceptions are listed in Table 9-169. The syntax for this procedure is shown below:

DBMS_REPCAT.REFRESH_SNAPSHOT_REPGROUP(
     gname                  IN   VARCHAR2,
     drop_missing_contents  IN   BOOLEAN    := FALSE,
     refresh_snapshots      IN   BOOLEAN    := FALSE,
     refresh_other_objects  IN   BOOLEAN    := FALSE)

Table 9-168 Parameters for REFRESH_SNAPSHOT_REPGROUP

Parameter	Description
gname	The name of the replicated object group.
drop_missing_contents	If an object was dropped from the replicated object group, it is not automatically dropped from the schema at the snapshot site. It is simply no longer replicated; that is, changes to this object are no longer sent to its associated master site. Snapshots can continue to be refreshed from their associated master tables; however, any changes to an updatable snapshot will be lost. When an object is dropped from the object group, you can choose to have it dropped from the schema entirely by setting this argument to TRUE.
refresh_snapshots	Set this parameter to TRUE to refresh the contents of the snapshots in the replicated object group.
refresh_other_objects	Set this parameter to TRUE to refresh the contents of the non-snapshot objects in the replicated object group.

Table 9-169 Exceptions for REFRESH_SNAPSHOT_REPGROUP

Exception	Description
nonsnapshot	The invocation site is not a snapshot site.
nonmaster	The master is no longer a master site.
commfailure	The master is not accessible.
missrepgroup	Object group name not specified.

DBMS_REPCAT.REGISTER_SNAPSHOT_REPGROUP

Purpose

To facilitate the administration of snapshots at their respective master sites by inserting/modifying/deleting from repcat_repsite.

Syntax

The parameters for REGISTER_SNAPSHOT_REPGROUP are described in Table 9-170. The syntax for the REGISTER_SNAPSHOT_REPGROUP procedure is shown below.

DBMS_REPCAT.REGISTER_SNAPGROUP_REPGROUP(
     gname            IN   VARCHAR2,
     snapsite         IN   VARCHAR2,
     comment          IN   VARCHAR2  := NULL,
     rep_type         IN   NUMBER    := reg_unknown)

Table 9-170 Parameters for REGISTER_SNAPSHOT_REPGROUP

Parameter	Description
gname	The name of the snapshot object group to be registered.
snapsite	Global name of the snapshot site.
comment	Comment for the snapshot site or update for an existing comment.
rep_type	Version of the snapshot group. Valid constants that can be assigned include reg_uknown (the default), reg_v7_group, reg_v8_group, and reg_repapi_group.

Table 9-171 Exceptions for REGISTER_SNAPSHOT_REPGROUP

Exception	Description
missrepgroup	Object group name not specified.
nullsitename	A snapshot site was not specified.
nonmaster	The procedure must be executed at the snapshot's master site.
duplrepgrp	The object already exists.

DBMS_REPCAT.REGISTER_STATISTICS

Purpose

To collect information about the successful resolution of update, delete and uniqueness conflicts for a table.

Syntax

The parameters for the REGISTER_STATISTICS procedure are described in Table 9-172, and the exceptions are listed in Table 9-173. The syntax for this procedure is shown below:

DBMS_REPCAT.REGISTER_STATISTICS(
      sname IN   VARCHAR2,
      oname IN   VARCHAR2)

Table 9-172 Parameters for REGISTER_STATISTICS

Parameter	Description
sname	The name of the schema in which the table is located.
oname	The name of the table for which you want to gather conflict resolution statistics.

Table 9-173 Exceptions for REGISTER_STATISTICS

Exception	Description
missingschema	The given schema does not exist.
missingobject	The given table does not exist.

DBMS_REPCAT.RELOCATE_MASTERDEF

Purpose

To change your master definition site to another master site in your replicated environment.

Syntax

The parameters for the RELOCATE_MASTERDEF procedure are described in Table 9-174, and the exceptions are listed in Table 9-175. The syntax for this procedure is shown below:

DBMS_REPCAT.RELOCATE_MASTERDEF(
     gname                  IN   VARCHAR2, 
     old_masterdef          IN   VARCHAR2, 
     new_masterdef          IN   VARCHAR2, 
     notify_masters         IN   BOOLEAN    := TRUE,
     include_old_masterdef  IN   BOOLEAN    := TRUE)

Table 9-174 Parameters for RELOCATE_MASTERDEF

Parameter	Description
gname	The name of the object group whose master definition you want to relocate.
old_masterdef	The fully qualified database name of the current master definition site.
new_masterdef	The fully qualified database name of the existing master site that you want to make the new master definition site.
notify_masters	If NOTIFY_MASTERS is TRUE, the procedure synchronously multicasts the change to all masters (including OLD_MASTERDEF only if INCLUDE_OLD_MASTERDEF is TRUE). If any master does not make the change, roll back the changes at all masters.
include_old_ masterdef	If NOTIFY_MASTERS is TRUE and INCLUDE_OLD_MASTERDEF is also TRUE, the old master definition site is also notified of the change.

Table 9-175 Exceptions for RELOCATE_MASTERDEF

Exception	Description
nonmaster	NEW_MASTERDEF is not a master site or the invocation site is not a master site.
nonmasterdef	OLD_MASTERDEF is not the master definition site.
commfailure	At least one master site is not accessible and NOTIFY_MASTERS is TRUE.

Usage Notes

It is not necessary for either the old or new master definition site to be available when you call RELOCATE_MASTERDEF. In a planned reconfiguration, you should invoke RELOCATE_MASTERDEF with NOTIFY_MASTERS TRUE and INCLUDE_OLD_MASTERDEF TRUE. If just the master definition site fails, you should invoke RELOCATE_MASTERDEF with NOTIFY_MASTERS TRUE and INCLUDE_OLD_MASTERDEF FALSE. If several master sites and the master definition site fail, the administrator should invoke RELOCATE_MASTERDEF at each operational master with NOTIFY_MASTERS FALSE.

DBMS_REPCAT.REMOVE_MASTER_DATABASES

Purpose

To remove one or more master databases from a replicated environment. This procedure regenerates the triggers and their associated packages at the remaining master sites. You must call this procedure from the master definition site.

Syntax

The parameters for the REMOVE_MASTER_DATABASES procedure are described in Table 9-176, and the exceptions are listed in Table 9-177. The syntax for this procedure is shown below:

DBMS_REPCAT.REMOVE_MASTER_DATABASES(
     gname           IN   VARCHAR2,
     master_list     IN   VARCHAR2 |
     master_table    IN   DBMS_UTILITY.DBLINK_ARRAY)

Table 9-176 Parameters for REMOVE_MASTER_DATABASES

Parameter	Description
gname	The name of the object group associated with the replicated environment. This prevents confusion if a master database is involved in more than one replicated environment.
master_list	A comma-separated list of fully qualified master database names that you want to remove from the replicated environment. There must be no extra white space between names in the list.
master_table	In place of a list, you may also specify the database names in a PL/SQL table of type DBMS_UTILITY.DBLINK_ARRAY.

Table 9-177 Exceptions for REMOVE_MASTER_DATABASES

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
nonmaster	At least one of the given databases is not a master site.
reconfigerror	One of the given databases is the master definition site.
commfailure	At least one remaining master site is not accessible.

DBMS_REPCAT.REPCAT_IMPORT_CHECK

Purpose

To ensure that the objects in the replicated object group have the appropriate object identifiers and status values after you perform an export/import of a replicated object or an object used by the advanced replication facility.

Syntax

The parameters for the REPCAT_IMPORT_CHECK procedure are described in Table 9-178, and the exceptions are listed in Table 9-179. The syntax for this procedure is shown below:

DBMS_REPCAT.REPCAT_IMPORT_CHECK(
     gname      IN   VARCHAR2,
     master     IN   BOOLEAN)

Table 9-178 Parameters for REPCAT_IMPORT_CHECK

Parameter	Description
gname	The name of the replicated object group. If you omit both parameters, the procedure checks all replicated object groups at your current site.
master	Set this flag to TRUE if you are checking a master site or FALSE if you are checking a snapshot site.

Table 9-179 Exceptions for REPCAT_IMPORT_CHECK

Exception	Description
nonmaster	MASTER is TRUE and either the database is not a master site for the schema or the database is not the expected database.
nonsnapshot	MASTER is FALSE and the database is not a snapshot site for the schema.
missingobject	A valid replicated object in the schema does not exist.
missingschema	The given group name does not exist.

DBMS_REPCAT.RESUME_MASTER_ACTIVITY

Purpose

To resume normal replication activity after quiescing a replicated environment.

Syntax

The parameters for the RESUME_MASTER_ACTIVITY procedure are described in Table 9-180, and the exceptions are listed in Table 9-181. The syntax for this procedure is shown below:

DBMS_REPCAT.RESUME_MASTER_ACTIVITY(
     gname       IN  VARCHAR2, 
     override    IN  BOOLEAN := FALSE)

Table 9-180 Parameters for RESUME_MASTER_ACTIVITY

Parameter	Description
gname	The name of the replicated object group.
override	If override is TRUE, it ignores any pending RepCat administration requests and restores normal replication activity at each master as quickly as possible. This should be considered only in emergency situations. If override is FALSE, it restores normal replication activity at each master only when there is no pending RepCat administration request for GNAME at that master.

Table 9-181 Exceptions for RESUME_MASTER_ACTIVITY

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
notquiesced	The replicated object group is not quiescing or quiesced.
commfailure	At least one master site is not accessible.

DBMS_REPCAT.SEND_AND_COMPARE_OLD_VALUES

Purpose

You have the option of sending old column values for each non-key column of a replicated table for updates and deletes. The default is to send old values for all columns. You can change this behavior at all master and snapshot sites by invoking DBMS_REPCAT.SEND_AND_COMPARE_OLD_VALUES at the master definition site.

Note: The OPERATION parameter allows you to decide whether or not to transmit old values for non-key columns when rows are deleted or when non-key columns are updated. If you do not send the old value, Oracle sends a NULL in place of the old value and assumes the old value is equal to the current value of the column at the target side when the update or delete is applied.

Caution: Read "Minimizing Data Propagation for Update Conflict Resolution" on page 5-40.before changing the default behavior of Oracle.

Syntax

The parameters for the SEND_AND_COMPARE_OLD_VALUES procedure are described in Table 9-182, and the exceptions are listed in Table 9-183. The syntax for this procedure is shown below:

DBMS_REPCAT.SEND_AND_COMPARE_OLD_VALUES(
     sname           IN    VARCHAR2,
     oname           IN    VARCHAR2,
     { column_list   IN    VARCHAR2,
     | column_table  IN    DBMS_REPCAT.VARCHAR2s,}
     operation       IN    VARCHAR2 := 'UPDATE',
     send            IN    BOOLEAN  :=  TRUE)

Note: This procedure is overloaded. The COLUMN_LIST and COLUMN_TABLE parameters are mutually exclusive.

Table 9-182 Parameters for SEND_AND_COMPARE_OLD_VALUES

Parameter	Description
sname	The schema in which the table is located.
oname	The name of the table.
column_list	A comma-separated list of the columns in the table. There must be no white space between entries.
column_table	Instead of a list, you can use a PL/SQL table of type DBMS_REPCAT.VARCHAR2S to contain the column names. The first column name should be at offset 1, the second at offset 2, and so on.
operation	Possible values are: UPDATE, DELETE, or the asterisk wildcard '*', which means update and delete.
send	If TRUE, the old values of the specified columns are sent. If FALSE, the old values of the specified columns are not sent. Unspecified columns and unspecified operations are not affected. The specified change takes effect at the master definition site as soon as min_communication is TRUE for the table. The change takes effect at a master site or at a snapshot site the next time replication support is generated at that site with min_communication TRUE.

Table 9-183 Exceptions for SEND_AND_COMPARE_OLD_VALUES

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist as a table in the given schema awaiting row-level replication information.
missingcolumn	At least one column is not in the table.
notquiesced	The replicated object group has not been suspended.
typefailure	An illegal operation is given.

DBMS_REPCAT.SET_COLUMNS

Purpose

To use an alternate column or group of columns, instead of the primary key, to determine which columns of a table to compare when using row-level replication. You must call this procedure from the master definition site. See "Designating an Alternate Key for a Replicated Table" on page 3-20

Syntax

The parameters for the SET_COLUMNS procedure are described in Table 9-184, and the exceptions are listed in Table 9-185. The syntax for this procedure is shown below:

DBMS_REPCAT.SET_COLUMNS(
     sname           IN    VARCHAR2,
     oname           IN    VARCHAR2,
     { column_list   IN    VARCHAR2
     | column_table  IN    DBMS_UTILITY.NAME_ARRAY } )

Note: This procedure is overloaded. The COLUMN_LIST and COLUMN_TABLE parameters are mutually exclusive.

Table 9-184 Parameters for SET_COLUMNS

Parameter	Description
sname	The schema in which the table is located.
oname	The name of the table.
column_list	A comma-separated list of the columns in the table that you want to use as a "primary key". There must be no white space between entries.
column_table	Instead of a list, you can use a PL/SQL table of type DBMS_UTILITY.NAME_ARRAY to contain the column names. The first column name should be at offset 1, the second at offset 2, and so on.

Table 9-185 Exceptions for SET_COLUMNS

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
missingobject	The given object does not exist as a table in the given schema awaiting row-level replication information.
missingcolumn	At least one column is not in the table.

DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY

Purpose

To suspend replication activity for an object group. You must call this procedure from the master definition site.

Note: The current implementation of SUSPEND_MASTER_ACTIVITY quiesces all replicated object groups at each master site.

Syntax

The parameter for the SUSPEND_MASTER_ACTIVITY procedure is described in Table 9-186, and the exceptions are listed in Table 9-187. The syntax for this procedure is shown below:

DBMS_REPCAT.SUSPEND_MASTER_ACTIVITY(gname   IN   VARCHAR2)

Table 9-186 Parameter for SUSPEND_MASTER_ACTIVITY

Parameter	Description
gname	The name of the object group for which you want to suspend activity.

Table 9-187 Exceptions for SUSPEND_MASTER_ACTIVITY

Exception	Description
nonmasterdef	The invocation site is not the master definition site.
notnormal	The replicated object group is not in normal operation.
commfailure	At least one master site is not accessible.
missingobjectgroup	The given object group does not exist.

DBMS_REPCAT.SWITCH_SNAPSHOT_MASTER

Purpose

To change the master database of a snapshot replicated object group to another master site. This procedure does a full refresh of the affected snapshots and regenerates the triggers and their associated packages as needed. This procedure does not push the queue to the old master site before changing masters.

Syntax

The parameters for the SWITCH_SNAPSHOT_MASTER procedure are described in Table 9-188, and the exceptions are listed in Table 9-189. The syntax for this procedure is shown below:

DBMS_REPCAT.SWITCH_SNAPSHOT_MASTER(
     gname              IN   VARCHAR2, 
     master             IN   VARCHAR2)

Table 9-188 Parameters for SWITCH_SNAPSHOT_MASTER

Parameter	Description
gname	The name of the snapshot object group for which you want to change master sites.
master	The fully qualified database name of the new master database to use for the snapshot site.

Table 9-189 Exceptions for SWITCH_SNAPSHOT_MASTER

Exception	Description
nonsnapshot	The invocation site is not a snapshot site.
nonmaster	The given database is not a master site.
commfailure	The given database is not accessible.

DBMS_REPCAT.UNREGISTER_SNAPSHOT_REPGROUP

Purpose

To facilitate the administration of snapshots at their respective master sites by inserting/modifying/deleting from repcat$_repsite.

Syntax

The parameters for UNREGISTER_SNAPSHOT_REPGROUP are described in Table 9-190. The syntax for the UNREGISTER_SNAPSHOT_REPGROUP procedure is shown below.

DBMS_REPCAT.UNREGISTER_SNAPGROUP_REPGROUP(
     gname     IN   VARCHAR2,
     snapsite  IN   VARCHAR2)

Table 9-190 Parameters for UNREGISTER_SNAPSHOT_REPGROUP

Parameter	Description
gname	The name of the snapshot object group to be unregistered.
snapsite	Global name of the snapshot site.

DBMS_REPCAT.VALIDATE

Purpose

To validate the correctness of key conditions of a multiple master replication environment, you can execute the VALIDATE procedure, which is overloaded.

Syntax

The parameters for the VALIDATE function are described in Table 9-191 and the exceptions are described in Table 9-192. The syntax for this procedure is shown below:

DBMS_REPCAT.VALIDATE (
      gname               IN VARCHAR2, 
      check_genflags      IN BOOLEAN := FALSE,
      check_valid_objs    IN BOOLEAN := FALSE,
      check_links_sched   IN BOOLEAN := FALSE,
      check_links         IN BOOLEAN := FALSE,
      error_table         OUT dbms_repcat.validate_err_table )
  RETURN BINARY_INTEGER

DBMS_REPCAT.VALIDATE (
      gname               IN VARCHAR2, 
      check_genflags      IN BOOLEAN := FALSE,
      check_valid_objs    IN BOOLEAN := FALSE,
      check_links_sched   IN BOOLEAN := FALSE,
      check_links         IN BOOLEAN := FALSE,
      error_msg_table     OUT DBMS_UTILITY.UNCL_ARRAY,
      error_num_table     OUT DBMS_UTILITY.NUMBER_ARRAY )
  RETURN BINARY_INTEGER

Table 9-191 Parameters for VALIDATE

Parameter	Description
gname	The name of the master group to validate.
check_genflags	Check whether all the objects in the group are generated. This must be done at the masterdef site only.
check_valid_objs	Check that the underlying objects for objects in the group valid. This must be done at the masterdef site only. The masterdef site goes to all other sites and checks that the underlying objects are valid. The validity of the objects is checked within the schema of the connected user.
check_links_sched	Check whether the links are scheduled for execution. This should be invoked at each master site.
check_links	Check whether the connected user (repadmin), as well as the propagator, have correct links for replication to work properly. Checks that the links exist in the database and are accessible. This should be invoked at each master site.
error_table	Returns the message and numbers of all errors that are found.
error_msg_table	Returns the messages of all errors that are found.
error_num_table	Returns the numbers of all errors that are found.

The return value of VALIDATE is the number of errors found. The function's OUT parameter(s) returns any errors that are found. In the first interface function, the ERROR_TABLE consists of an array of records. Each record has a VARCHAR2 and a NUMBER in it. The string field contains the error message and the number field contains the Oracle error number.

The second interface is similar except that there are two OUT arrays. A VARCHAR2 array with the error messages and a NUMBER array with the error numbers.

Table 9-192 Exceptions for VALIDATE

Exception	Description
missingdblink	The database link does not exist in the schema of the replication propagator or has not been scheduled. Ensure that the database link exists in the database, is accessible, and is scheduled for execution.
dblinkmismatch	The database link name at the local node does not match the global name of the database that the link accesses. Ensure that global names is set to true and the link name matches the global name.
dblinkuidmismatch	The user name of the replication administration user at the local node and the user name at the node corresponding to the database link are not the same. Advanced replication expects the two users to be the same. Ensure that the user ID of the replication administration user at the local node and the user ID at the node corresponding to the database link are the same.
objectnotgenerated	The object has not been generated at other master sites or is still being generated. Ensure that the object is generated by calling generate_replication_support and do_deferred_repcat_admin for the object at the masterdef site.
opnotsupported	Operation is not supported if the object group is replicated at a pre-V8 node. Ensure that all nodes of the replicated object group are V8.

DBMS_REPCAT.WAIT_MASTER_LOG

Purpose

To determine whether changes that were asynchronously propagated to a master site have been applied.

Syntax

The parameters for the WAIT_MASTER_LOG procedure are described in Table 9-193, and the exception is listed in Table 9-194. The syntax for this procedure is shown below:

DBMS_REPCAT.WAIT_MASTER_LOG(
     gname          IN   VARCHAR2, 
     record_count   IN   NATURAL, 
     timeout        IN   NATURAL, 
     true_count     OUT   NATURAL)

Table 9-193 Parameters for WAIT_MASTER_LOG

Parameter	Description
gname	The name of the replicated object group.
record_count	The procedure returns whenever the number of incomplete activities is at or below this threshold.
timeout	The maximum number of seconds to wait before the procedure returns.
true_count (out parameter)	Returns the number of incomplete activities.

Table 9-194 Exception for WAIT_MASTER_LOG

Exception	Description
nonmaster	The invocation site is not a master site.

DBMS_REPCAT_ADMIN Package

The DBMS_REPCAT_ADMIN package contains the following procedures:

• DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_SCHEMA
• DBMS_REPCAT_ADMIN.GRANT_ADMIN_SCHEMA
• DBMS_REPCAT_ADMIN.REVOKE_ADMIN_ANY_SCHEMA
• DBMS_REPCAT_ADMIN.REVOKE_ADMIN_SCHEMA

The following pages discuss each procedure.

DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_SCHEMA

Purpose

To grant the necessary privileges to the replication administrator to administer any replicated object group at the current site.

Syntax

The parameter for the GRANT_ADMIN_ANY_SCHEMA procedure is described in Table 9-195, and the exception is described in Table 9-196. The syntax for this procedure is shown below:

DBMS_REPCAT_ADMIN.GRANT_ADMIN_ANY_SCHEMA(username  IN   VARCHAR2)

Table 9-195 Parameter for GRANT_ADMIN_ANY_SCHEMA

Parameter	Description
username	The name of the replication administrator to whom you want to grant the necessary privileges and roles to administer any replicated object groups at the current site.

Table 9-196 Exception for GRANT_ADMIN_ANY_REPGROUP

Exception	Description
ORA-01917	The user does not exist.

DBMS_REPCAT_ADMIN.GRANT_ADMIN_SCHEMA

Purpose

To grant the necessary privileges to the replication administrator to administer a schema at the current site. This procedure is most useful if your object group does not span schemas.

Syntax

The parameter for the GRANT_ADMIN_REPSCHEMA procedure is described in Table 9-197, and the exception is described in Table 9-198. The syntax for this procedure is shown below:

DBMS_REPCAT_ADMIN.GRANT_ADMIN_SCHEMA(username IN VARCHAR2)

Table 9-197 Parameter for GRANT_ADMIN_REPSCHEMA

Parameter	Description
username	The name of the replication administrator. This user is then granted the necessary privileges and roles to administer the schema of the same name within a replicated object group at the current site.

Table 9-198 Exception for GRANT_ADMIN_REPSCHEMA

Exception	Description
ORA-01917	The user does not exist.

DBMS_REPCAT_ADMIN.REVOKE_ADMIN_ANY_SCHEMA

Purpose

To revoke the privileges and roles from the replication administrator that would be granted by GRANT_ADMIN_ANY_SCHEMA.

Attention: Identical privileges and roles that were granted independently of GRANT_ADMIN_ANY_SCHEMA are also revoked.

Syntax

The parameter for the REVOKE_ADMIN_ANY_SCHEMA procedure is described in Table 9-199, and the exception is described in Table 9-200. The syntax for this procedure is shown below:

DBMS_REPCAT_ADMIN.REVOKE_ADMIN_ANY_SCHEMA(username IN   VARCHAR2)

Table 9-199 Parameter for REVOKE_ADMIN_ANY_SCHEMA

Parameter	Description
username	The name of the replication administrator whose privileges you want to revoke.

Table 9-200 Exception for REVOKE_ADMIN_ANY_SCHEMA

Exception	Description
ORA-01917	The user does not exist.

DBMS_REPCAT_ADMIN.REVOKE_ADMIN_SCHEMA

Purpose

To revoke the privileges and roles from the replication administrator that would be granted by GRANT_ADMIN_SCHEMA.

Attention: Identical privileges and roles that were granted independently of GRANT_ADMIN_SCHEMA are also revoked.

Syntax

The parameter for the REVOKE_ADMIN_SCHEMA procedure is described in Table 9-201, and the exception is described in Table 9-202. The syntax for this procedure is shown below:

DBMS_REPCAT_ADMIN.REVOKE_ADMIN_SCHEMA(username IN VARCHAR2)

Table 9-201 Parameter for REVOKE_ADMIN_SCHEMA

Parameter	Description
username	The name of the replication administrator whose privileges you want to revoke.

Table 9-202 Exception for REVOKE_ADMIN_SCHEMA

Exception	Description
ORA-01917	The user does not exist.

DBMS_REPCAT_AUTH Package

The DBMS_REPCAT_AUTH package contains the following procedures:

• DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT
• DBMS_REPCAT_AUTH.REVOKE_SURROGATE_REPCAT

The following pages discuss each procedure.

DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT

Purpose

To grant the privileges needed by the advanced replication facility to a user.

Syntax

The parameter for the GRANT_SURROGATE_REPCAT procedure is described in Table 9-203, and the exception is described in Table 9-204. The syntax for this procedure is shown below:

DBMS_REPCAT_AUTH.GRANT_SURROGATE_REPCAT(userid IN VARCHAR2)

Table 9-203 Parameter for GRANT_SURROGATE_REPCAT

Parameter	Description
userid	The name of the user to whom you wish to grant the necessary privileges.

Table 9-204 Exception for GRANT_SURROGATE_REPCAT

Exception	Description
ORA-01917	The user does not exist.

DBMS_REPCAT_AUTH.REVOKE_SURROGATE_REPCAT

Purpose

To revoke the privileges granted to the surrogate repcat user.

Syntax

The parameters for the REVOKE_SURROGATE_REPCAT procedure is described in Table 9-205, and the exception is described in Table 9-206. The syntax for this procedure is shown below:

DBMS_REPCAT_AUTH.REVOKE_SURROGATE_REPCAT(userid IN VARCHAR2)

Table 9-205 Parameter for REVOKE_SURROGATE_REPCAT

Parameter	Description
userid	The name of the user from whom you wish to revoke the necessary privileges.

Table 9-206 Exception for REVOKE_SURROGATE_REPCAT

Exception	Description
ORA-01917	The user does not exist.

DBMS_REPUTIL Package

The DBMS_REPUTIL package contains the following procedures:

• DBMS_REPUTIL.REPLICATION_OFF
• DBMS_REPUTIL.REPLICATION_ON

The following pages discuss each procedure.

DBMS_REPUTIL.REPLICATION_OFF

Purpose

To modify tables without replicating the modifications to any other sites in the replicated environment, or to disable row-level replication when using procedural replication. In general, you should suspend replication activity for all master groups in your replicated environment before setting this flag.

Syntax

The syntax for the REPLICATION_OFF procedure is shown below. This procedure takes no arguments.

DBMS_REPUTIL.REPLICATION_OFF

DBMS_REPUTIL.REPLICATION_ON

Purpose

To reenable replication of changes after replication has been temporarily suspended by calling REPLICATION_OFF.

Syntax

The syntax for the REPLICATION_ON procedure is shown below. This procedure takes no arguments.

DBMS_REPUTIL.REPLICATION_ON

DBMS_SNAPSHOT Package

The DBMS_SNAPSHOT package contains the following procedures and one function:

• DBMS_SNAPSHOT.BEGIN_TABLE_REORGANIZATION
• DBMS_SNAPSHOT.END_TABLE_REORGANIZATION
• DBMS_SNAPSHOT.I_AM_A_REFRESH
• DBMS_SNAPSHOT.PURGE_LOG
• DBMS_SNAPSHOT.REFRESH
• DBMS_SNAPSHOT.REGISTER_SNAPSHOT
• DBMS_SNAPSHOT.SET_I_AM_A_REFRESH
• DBMS_SNAPSHOT.UNREGISTER_SNAPSHOT

DBMS_SNAPSHOT.BEGIN_TABLE_REORGANIZATION

Purpose

This procedure must be called before a master table is reorganized. It performs process to preserve snapshot data needed for refresh.

Additional Information: See "Reorganizing Master Tables that Have Snapshot Logs" on page 2-30.

Syntax

The parameters for the BEGIN_TABLE_REORGANIZATION procedure are described in Table 9-207. The syntax for BEGIN_TABLE_REORGANIZATION is shown below.

DBMS_SNAPSHOT.BEGIN_TABLE_REORGANIZATION(
      tabowner    IN   VARCHAR2
      tabname     IN   VARCHAR2)

Table 9-207 Parameters for BEGIN_TABLE_REORGANIZATION

Parameter	Description
tabowner	The owner of the table being reorganized.
tabname	The name of the table being reorganized.

DBMS_SNAPSHOT.END_TABLE_REORGANIZATION

Purpose

This procedure must be called after a master table is reorganized. It ensures that the snapshot data for the master table is valid and that the master table is in the proper state.

Additional Information: See "Reorganizing Master Tables that Have Snapshot Logs" on page 2-30.

Syntax

The parameters for END_TABLE_REORGANIZATION are described in Table 9-208. The syntax for END_TABLE_REORGANIZATION is shown below.

DBMS_SNAPSHOT.END_TABLE_REORGANIZATION(
      tabowner    IN   VARCHAR2
      tabname     IN   VARCHAR2)

Table 9-208 Parameters for END_TABLE_REORGANIZATION

Parameter	Description
tabowner	The owner of the table being reorganized.
tabname	The name of the table being reorganized.

DBMS_SNAPSHOT.I_AM_A_REFRESH

Purpose

To return the value of the I_AM_REFRESH package state.

Syntax

The I_AM_A_REFRESH function takes no arguments. A return value of TRUE indicates that all local replication triggers for snapshots will be effectively disabled in this session because each replication trigger first checks this state. A return value of FALSE indicates that these triggers are enabled. The syntax for this procedure is shown below.

DBMS_SNAPSHOT.I_AM_A_REFRESH RETURN BOOLEAN

DBMS_SNAPSHOT.PURGE_LOG

Purpose

To purge rows from the snapshot log.

Syntax

The parameters for the PURGE_LOG procedure are described in Table 9-209. The syntax for this procedure is shown below:

DBMS_SNAPSHOT.PURGE_LOG(
     master        IN   VARCHAR2,
     num           IN   BINARY_INTEGER := 1,
     flag          IN   VARCHAR2       := 'NOP')

Table 9-209 Parameters for PURGE_LOG

Parameter	Description
master	Name of the master table.
num	Number of least recently refreshed snapshots whose rows you want to remove from snapshot log. For example, the following statement deletes rows needed to refresh the two least recently refreshed snapshots: dbms_snapshot.purge_log('master_table', 2); To delete all rows in the snapshot log, indicate a high number of snapshots to disregard, as in this example: dbms_snapshot.purge_log('master_table',9999); This statement completely purges the snapshot log that corresponds to MASTER_TABLE if fewer than 9999 snapshots are based on MASTER_TABLE. A simple snapshot whose rows have been purged from the snapshot log must be completely refreshed the next time it is refreshed.
flag	Specify DELETE to guarantee that rows are deleted from the snapshot log for at least one snapshot. This argument can override the setting for the argument NUM. For example, the following statement deletes rows from the least recently refreshed snapshot that actually has dependent rows in the snapshot log: dbms_snapshot.purge_log('master_table',1,'DELETE');

DBMS_SNAPSHOT.REFRESH

Purpose

To consistently refresh one or more snapshots that are not members of the same refresh group. For additional information, see page Table 9-210.

Syntax

The parameters for the REFRESH procedure are described in Table 9-210. The syntax for this procedure is shown below:

DBMS_SNAPSHOT.REFRESH(
      { list                 IN VARCHAR2,
      | tab                  IN OUT DBMS_UTILITY.UNCL_ARRAY,}
      method                 IN VARCHAR2       := NULL,
      rollback_seg           IN VARCHAR2       := NULL,
      push_deferred_rpc      IN BOOLEAN        := TRUE,
      refresh_after_errors   IN BOOLEAN        := FALSE,
      purge_option           IN BINARY_INTEGER := 1,
      parallelism            IN BINARY_INTEGER := 0,
      heap_size              IN BINARY_INTEGER := 0)

Table 9-210 Parameters for REFRESH

Parameter	Description
list tab	Comma-separated list of snapshots that you want to refresh. (Synonyms are not supported.) These snapshots can be located in different schemas and have different master tables; however, all of the listed snapshots must be in your current database. Alternatively, you may pass in a PL/SQL table of type DBMS_UTILITY.UNCL_ARRAY, where each element is the name of a snapshot.
method	Type of refresh to perform for each snapshot listed; `F' or `f' indicates a fast refresh, `C' or `c' indicates a complete refresh, and `?' indicates a default refresh. If you specified a refresh mode when you created the snapshot, that mode is used when you specify a default refresh. If no mode was specified, Oracle performs a fast refresh if possible; otherwise, it performs a complete refresh. If the METHOD list contains fewer elements than the snapshot LIST, the trailing elements in the snapshot list are refreshed using a default refresh. For example, the following EXECUTE statement within SQL*Plus: dbms_snapshot.refresh ('emp,dept,scott.salary','CF'); performs a complete refresh of the EMP snapshot, a fast refresh of the DEPT snapshot, and a default refresh of the SCOTT.SALARY snapshot.
rollback_seg	Name of the snapshot site rollback segment to use while refreshing snapshots. When you call REFRESH, all of the listed snapshots are updated to a single point in time. If the refresh fails for any of the snapshots, none of the snapshots are updated.
push_deferred_rpc	Used by updatable snapshots only. Use the default value, TRUE, if you want to push changes from the snapshot to its associated master before refreshing the snapshot. Otherwise, these changes may appear to be temporarily lost.
refresh_after_errors	Used by updatable snapshots only. Set this parameter to TRUE if you want the refresh to proceed even if there are outstanding conflicts logged in the DEFERROR view for the snapshot's master.
purge_option	If you are using the parallel propagation mechanism (in other words, parallelism is set to 1 or greater), 0 = don't purge; 1 = lazy (default); 2 = aggressive. In most cases, lazy purge is the optimal setting. Set purge to aggressive to trim back the queue if multiple master replication groups are pushed to different target sites, and updates to one or more replication groups are infrequent and infrequently pushed. If all replication groups are infrequently updated and pushed, set purge to don't purge and occasionally execute PUSH with purge set to aggressive to reduce the queue.
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.

DBMS_SNAPSHOT.REGISTER_SNAPSHOT

Purpose

To enable the administration of individual snapshots.

Syntax

The parameters for the REGISTER_SNAPSHOT procedure are described in Table 9-211. The syntax for the REGISTER_SNAPSHOT procedure is shown below.

DBMS_SNAPSHOT.REGISTER_SNAPSHOT(
      snapowner   IN   VARCHAR2,
      snapname    IN   VARCHAR2,
      snapsite    IN   VARCHAR2,
      snapshot_id IN   DATE | BINARY_INTEGER,
      flag        IN   BINARY_INTEGER,
      qry_txt     IN   VARCHAR2,
      rep_type    IN   BINARY_INTEGER := DBMS_SNAPSHOT.REG_UNKNOWN)

Note: This procedure is overloaded. The SNAPSHOT_ID and FLAG parameters are mutually exclusive.

Table 9-211 Parameters for REGISTER_SNAPSHOT

Parameter	Description
sowner	The owner of the snapshot.
snapname	The name of the snapshot.
snapsite	The name of the snapshot site for a snapshot registering at an Oracle8 master. This parameter should not contain any double quotes.
snapshot_id	The identification number of the snapshot. Specify an Oracle8 snapshot as a BINARY_INTEGER; specify an Oracle7 snapshot registering at an Oracle8 master sites as a DATE.
flag	PL/SQL package variable indicating whether subsequent create or move commands are registered in the query text.
query_txt	The first 32,000 bytes of the query.
rep_type	Version of the snapshot. Valid constants that can be assigned include reg_uknown (the default), reg_v7_group, reg_v8_group, and reg_repapi_group.

Note: This procedure is executed at the master site, and can be done by a remote procedure call. If REGISTER_SNAPSHOT is called multiple times with the same SNAPOWNER, SNAPNAME, and SNAPSITE, the most recent values for SNAPSHOT_ID, FLAG, and QUERY_TXT are stored. If a query exceeds the maximum VARCHAR2 size, QUERY_TXT contains the first 32000 characters of the query and the remainder is truncated. When invoked manually, the values of SNAPSHOT_ID and FLAG have to be looked up in the snapshot views by the person who calls the procedure.

Note: If you do NOT want the snapshot query registered at the master site, call the SET_REGISTER_QUERY_TEXT procedure with the option set to FALSE. To see the most recent setting of the option, call the GET_REG_QUERY_TEXT_FLAG function at the snapshot site before issuing the DDL.

DBMS_SNAPSHOT.SET_I_AM_A_REFRESH

Purpose

To set the I_AM_REFRESH package state to the appropriate value.

Syntax

The parameter for the SET_I_AM_A_REFRESH procedure is described in Table 9-212. The syntax for this procedure is shown below.

DBMS_SNAPSHOT.SET_I_AM_A_REFRESH(value IN BOOLEAN)

Table 9-212 Parameter for SET_I_AM_A_REFRESH

Parameter	Description
value	Value that you want to set the I_AM_A_REFRESH package state to. If this state is set to TRUE, all local replication triggers for snapshots will be effectively disabled in this session because each replication trigger first checks this state. If this state is set to FALSE, these triggers will be enabled.

DBMS_SNAPSHOT.UNREGISTER_SNAPSHOT

Purpose

To enable the administration of individual snapshots. Invoked at a master site to unregister a snapshot.

Syntax

The parameters for the UNREGISTER_SNAPSHOT procedure are described in Table 9-213. The syntax for the UNREGISTER_SNAPSHOT procedure is shown below.

DBMS_SNAPSHOT.UNREGISTER_SNAPSHOT(
      snapowner      IN   VARCHAR2,
      snapname       IN   VARCHAR2,
      snapsite       IN   VARCHAR2)

Table 9-213 Parameters for UNREGISTER_SNAPSHOT

Parameters	Description
snapowner	The owner of the snapshot.
snapname	The name of the snapshot.
snapsite	The name of the snapshot site.

Package Variables

Table 9-214 describes the package variables that are used by the advanced replication facility. You may need to check the value of one or more of these variables in your own packages or triggers.

Table 9-214 Replication Package Variables

Variable	Type	Description
dbms_reputil. replication_is_on	BOOLEAN	TRUE indicates that the generated replication triggers are enabled. FALSE indicates that replication is disabled at the current site for the replicated object group. This variable is set by calling the REPLICATION_ON or REPLICATION_OFF procedures in the DBMS_REPUTIL package.
dbms_reputil. from_remote	BOOLEAN	This variable is set to TRUE at the beginning of procedures in the $RP replication packages, and is set to FALSE at the end of these procedures. You may need to check this variable if you have any triggers that could be fired as the result of an update by a $RP package.
dbms_reputil. global_name	VARCHAR2(128)	This variable contains the global database name of the local database.

---