Oracle8 Replication
Release 8.0

A58245-01

Library

Product

Contents

Index

Prev Next

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:

Packages

Oracle's replication management API includes the following packages:

Examples of Using Oracle's Replication Management API

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

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

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

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

Prerequisites to Consider

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

Replication Manager and Oracle Replication Management API

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

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

DBMS_DEFER Package

The DBMS_DEFER package contains the following procedures:

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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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:

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

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.  




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index