DELETE_ERROR Procedure

Syntax

Parameters

Table 11-6 DELETE_ERROR Procedure Parameters

Parameter

Description

deferred_tran_id

ID number from the DEFERROR view of the deferred transaction that you want to remove from the DEFERROR view. If this parameter is NULL, then all transactions meeting the requirements of the other parameter are removed.

destination

The fully qualified database name from the DEFERROR view of the database to which the transaction was originally queued. If this parameter is NULL, then all transactions meeting the requirements of the other parameter are removed from the DEFERROR view.

DELETE_TRAN Procedure

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

Syntax

Parameters

Table 11-7 DELETE_TRAN Procedure Parameters

ID number from the DEFTRAN view of the deferred transaction that you want to delete. If this is NULL, then all transactions meeting the requirements of the other parameter are deleted.

destination

The fully qualified database name from the DEFTRANDEST view of the database to which the transaction was originally queued. If this is NULL, then all transactions meeting the requirements of the other parameter are deleted.

DISABLED Function

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

Syntax

DBMS_DEFER_SYS.DISABLED (
destination IN VARCHAR2)
RETURN BOOLEAN;

Parameters

Table 11-8 DISABLED Function Parameters

Parameter

Description

destination

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

Returns

Table 11-9 DISABLED Function Return Values

Value

Description

TRUE

Propagation to this site from the current site is disabled.

FALSE

Propagation to this site from the current site is enabled.

Exceptions

Table 11-10 DISABLED Function Exceptions

Exception

Description

NO_DATA_FOUND

Specified destination does not appear in the DEFSCHEDULE view.

EXCLUDE_PUSH Procedure

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

Syntax

DBMS_DEFER_SYS.EXCLUDE_PUSH (
timeout IN INTEGER)
RETURN INTEGER;

Parameters

Table 11-11 EXCLUDE_PUSH Function Parameters

Parameter

Description

timeout

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

Syntax

Parameters

Table 11-13 EXECUTE_ERROR Procedure Parameters

ID number from the DEFERROR view of the deferred transaction that you want to re-execute. If this is NULL, then all transactions queued for destination are re-executed.

destination

The fully qualified database name from the DEFERROR view of the database to which the transaction was originally queued. This must not be NULL. If the provided database name is not fully qualified or is invalid, no error will be raised.

Table 11-17 PURGE Function Parameters

If you use purge_method_quick, deferred transactions and deferred procedure calls that have been successfully pushed may remain in the DEFTRAN and DEFCALL data dictionary views for longer than expected before they are purged. See "Usage Notes" for more information.

rollback_segment

Name of rollback segment to use for the purge, or NULL for default.

startup_seconds

Maximum number of seconds to wait for a previous purge of the same deferred transaction queue.

execution_seconds

If >0, then stop purge cleanly after the specified number of seconds of real time.

delay_seconds

Stop purge cleanly after the deferred transaction queue has no transactions to purge for delay_seconds.

transaction_count

If > 0, then shut down cleanly after purging transaction_count number of transactions.

write_trace

When set to TRUE, Oracle records the result value returned by the PURGE function in the server's trace file.

Returns

Table 11-18 Purge Function Return Values

Value

Description

0

OK, terminated after delay_seconds expired.

1

Terminated by lock timeout while starting.

2

Terminated by exceeding execution_seconds.

3

Terminated by exceeding transaction_count.

5

Terminated after errors.

Exceptions

Table 11-19 PURGE Function Exceptions

Exception

Description

argoutofrange

Parameter value is out of a valid range.

executiondisabled

Execution of purging is disabled.

defererror

Internal error.

Usage Notes

When you use the purge_method_quick for the purge_method parameter in the DBMS_DEFER_SYS.PURGE function, deferred transactions and deferred procedure calls may remain in the DEFCALL and DEFTRAN data dictionary views after they have been successfully pushed. This behavior occurs in replication environments that have more than one database link and the push is executed to only one database link.

To purge the deferred transactions and deferred procedure calls, perform one of the following actions:

Use purge_method_precise for the purge_method parameter instead of the purge_method_quick. Using purge_method_precise is more expensive, but it ensures that the deferred transactions and procedure calls are purged after they have been successfully pushed.

Using purge_method_quick for the purge_method parameter, push the deferred transactions to all database links. The deferred transactions and deferred procedure calls are purged efficiently when the push to the last database link is successful.

PUSH Function

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

Maximum number of transactions to be examined simultaneously for parallel propagation scheduling. Oracle automatically calculates the default setting for optimal performance. Do not set the parameter unless so directed by Oracle Worldwide Support.

stop_on_error

The default, FALSE, indicates that the executor should continue even if errors, such as conflicts, are encountered. If TRUE, then shut down (cleanly if possible) at the first indication that a transaction encountered an error at the destination site.

write_trace

When set to TRUE, Oracle records the result value returned by the function in the server's trace file.

startup_seconds

Maximum number of seconds to wait for a previous push to the same destination.

execution_seconds

If >0, then stop push cleanly after the specified number of seconds of real time. If transaction_count and execution_seconds are zero (the default), then transactions are executed until there are no more in the queue.

The execution_seconds parameter only controls the duration of time that operations can be started. It does not include the amount of time that the transactions require at remote sites. Therefore, the execution_seconds parameter is not intended to be used as a precise control to stop the propagation of transactions to a remote site. If a precise control is required, use the transaction_count or delivery_order parameters.

delay_seconds

Do not return before the specified number of seconds have elapsed, even if the queue is empty. Useful for reducing execution overhead if PUSH is called from a tight loop.

transaction_count

If > 0, then the maximum number of transactions to be pushed before stopping. If transaction_count and execution_seconds are zero (the default), then transactions are executed until there are no more in the queue that need to be pushed.

REGISTER_PROPAGATOR Procedure

This procedure registers the specified user as the propagator for the local database. It also grants to the specified user CREATESESSION, CREATEPROCEDURE, CREATEDATABASELINK, and EXECUTEANYPROCEDURE privileges (so that the user can create wrappers).

Syntax

DBMS_DEFER_SYS.REGISTER_PROPAGATOR (
username IN VARCHAR2);

Parameters

Table 11-23 REGISTER_PROPAGATOR Procedure Parameters

Parameter

Description

username

Name of the user.

Exceptions

Table 11-24 REGISTER_PROPAGATOR Procedure Exceptions

Exception

Description

missinguser

Specified user does not exist.

alreadypropagator

Specified user is already the propagator.

duplicatepropagator

There is already a different propagator.

SCHEDULE_PURGE Procedure

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

Parameters

Table 11-25 SCHEDULE_PURGE Procedure Parameters

Parameter

Description

interval

Allows you to provide a function to calculate the next time to purge. This value is stored in the interval field of the DEFSCHEDULE view and calculates the next_date field of this view. If you use the default value for this parameter, NULL, then the value of this field remains unchanged. If the field had no previous value, it is created with a value of NULL. If you do not supply a value for this field, you must supply a value for next_date.

next_date

Allows you to specify a time to purge pushed transactions from the site's queue. This value is stored in the next_date field of the DEFSCHEDULE view. If you use the default value for this parameter, NULL, then the value of this field remains unchanged. If this field had no previous value, it is created with a value of NULL. If you do not supply a value for this field, then you must supply a value for interval.

reset

Set to TRUE to reset LAST_TXN_COUNT, LAST_ERROR, and LAST_MSG to NULL.

Parameters

Table 11-26 SCHEDULE_PUSH Procedure Parameters (Page 1 of 2)

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, then the value of this field remains unchanged. If the field had no previous value, it is created with a value of NULL. If you do not supply a value for this field, then you must supply a value for next_date.

next_date

Allows you to specify a 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, then the value of this field remains unchanged. If this field had no previous value, then it is created with a value of NULL. If you do not supply a value for this field, then you must supply a value for interval.

Maximum number of transactions to be examined simultaneously for parallel propagation scheduling. Oracle automatically calculates the default setting for optimal performance. Do not set the parameter unless so directed by Oracle Worldwide Support.

stop_on_error

The default, FALSE, indicates that the executor should continue even if errors, such as conflicts, are encountered. If TRUE, then shut down (cleanly if possible) at the first indication that a transaction encountered an error at the destination site.

write_trace

When set to TRUE, Oracle records the result value returned by the function in the server's trace file.

startup_seconds

Maximum number of seconds to wait for a previous push to the same destination.

execution_seconds

If >0, then stop execution cleanly after the specified number of seconds of real time. If transaction_count and execution_seconds are zero (the default), then transactions are executed until there are no more in the queue.

delay_seconds

Do not return before the specified number of seconds have elapsed, even if the queue is empty. Useful for reducing execution overhead if PUSH is called from a tight loop.

transaction_count

If > 0, then the maximum number of transactions to be pushed before stopping. If transaction_count and execution_seconds are zero (the default), then transactions are executed until there are no more in the queue that need to be pushed.

SET_DISABLED Procedure

To disable or enable propagation of the deferred transaction queue from the current site to a specified destination site. If the disabled parameter is TRUE, then the procedure disables propagation to the specified destination and future invocations of PUSH do not push the deferred remote procedure call (RPC) queue. SET_DISABLED eventually affects a session already pushing the queue to the specified destination, but does not affect sessions appending to the queue with DBMS_DEFER.

If the disabled parameter is FALSE, then the procedure enables propagation to the specified destination and, although this does not push the queue, it permits future invocations of PUSH to push the queue to the specified destination. Whether the disabled parameter is TRUE or FALSE, a COMMIT is required for the setting to take effect in other sessions.