1 PACKAGE dbms_defer_sys AUTHID CURRENT_USER AS
2 -------------------
3 -- OVERVIEW
4 --
5 -- This package is the system administrator interface to a replicated
6 -- transactional deferred remote
7 -- procedure call facility. Administrators and replication
8 -- deamons can execute
9 -- transactions queued for remote nodes using this facility
10 -- and administrators
11 -- can control the nodes to which remote calls are destined.
12 ------------
13 -- SECURITY
14 --
15 -- By default, this package is owned by user SYS and
16 -- execution should be granted
17 -- only to administrators and deamons that perform
18 -- replication administration and
19 -- execute deferred transactions. See the security considerations for
20 -- the dbms_defer package for related considerations.
21 -------------
22 -- EXCEPTIONS
23 --
24 -- Parameter type does not match actual type. Message varies.
25 crt_err_err EXCEPTION;
26 PRAGMA exception_init(crt_err_err, -23324);
27 crt_err_num NUMBER := -23324;
28 crt_err_msg VARCHAR(76) := 'Error creating deferror entry: ';
29
30 -- Replication is not linked as an option
31 norepoption EXCEPTION;
32 PRAGMA exception_init(norepoption, -2094);
33 norepoption_num NUMBER := -2094;
34
35 -- Invalid user
36 missinguser EXCEPTION;
37 PRAGMA exception_init(missinguser, -23362);
38 missinguser_num NUMBER := -23362;
39
40 -- Already the propagator
41 alreadypropagator EXCEPTION;
42 PRAGMA exception_init(alreadypropagator, -23393);
43 alreadypropagator_num NUMBER := -23393;
44
45 -- Duplicate propagator
46 duplicatepropagator EXCEPTION;
47 PRAGMA exception_init(duplicatepropagator, -23394);
48 duplicatepropagator_num NUMBER := -23394;
49
50 -- Missing propagator
51 missingpropagator EXCEPTION;
52 PRAGMA exception_init(missingpropagator, -23357);
53 missingpropagator_num NUMBER := -23357;
54
55 -- Propagator in use
56 propagator_inuse EXCEPTION;
57 PRAGMA exception_init(propagator_inuse, -23418);
58 propagator_inuse_num NUMBER := -23418;
59
60 -- Incomplete parallel propagation/push, added for bug 430300
61 incompleteparallelpush EXCEPTION;
62 PRAGMA exception_init(incompleteparallelpush, -23388);
63 incompleteparallelpush_num NUMBER := -23388;
64
65 -- purge queue argument is out of range
66 argoutofrange EXCEPTION;
67 PRAGMA exception_init(argoutofrange, -23427);
68 argoutofrange_num NUMBER := -23427;
69
70 -- there are deferred RPC for some destination
71 notemptyqueue EXCEPTION;
72 PRAGMA exception_init(notemptyqueue, -23426);
73 notemptyqueue_num NUMBER := -23426;
74
75 -- serial propagation can not be used
76 serialpropnotallowed EXCEPTION;
77 PRAGMA exception_init(serialpropnotallowed, -23495);
78 serialpropnotallowed_num NUMBER := -23495;
79
80 cantsetdisabled EXCEPTION;
81 PRAGMA exception_init(cantsetdisabled, -23496);
82 cantsetdisabled_num NUMBER := -23496;
83
84 -------------
85 -- CONSTANTS
86
87 --
88 -- constants for result of push or purge
89 --
90 result_ok BINARY_INTEGER := 0;
91 -- okay, terminated after delay_seconds expired
92 result_startup_seconds BINARY_INTEGER := 1;
93 -- terminated by lock timeout while starting
94 result_execution_seconds BINARY_INTEGER := 2;
95 -- terminated by exceeding execution_seconds
96 result_transaction_count BINARY_INTEGER := 3;
97 -- terminated by exceeding transaction_count
98 result_delivery_order_limit BINARY_INTEGER := 4;
99 -- terminated at delivery_order_limit
100 result_errors BINARY_INTEGER := 5;
101 -- terminated after errors
102 result_push_disabled BINARY_INTEGER := 6;
103 -- terminated after detecting that propagation is disabled
104 result_purge_disabled BINARY_INTEGER := 6;
105 -- terminated after detecting that purge is disabled
106 result_cant_get_sr_enq BINARY_INTEGER := 7;
107 -- terminated after failing to acquire SR enqueue
108
109 --
110 -- constants for purge_method in purge_queue
111 --
112 purge_method_quick BINARY_INTEGER := 1;
113 purge_method_precise BINARY_INTEGER := 2;
114 --
115 -- constants for parameter defaults
116 --
117 seconds_infinity BINARY_INTEGER := 60*60*24*180;
118 transactions_infinity BINARY_INTEGER := 1000000000;
119 delivery_order_infinity NUMBER := 100000000000000000000;
120
121 -- PROCEDURES
122
123 -- manage default replication node lists
124
125 PROCEDURE add_default_dest(dblink IN VARCHAR2);
126 -- Add a node to the default list for replication targets.
127 -- Input parameters
128 -- dblink
129 -- name of the node (dblink) to add tRo the default list.
130 -- Exceptions
131 -- ORA-23352
132 -- dblink is already in the default list.
133 ----------
134
135 PROCEDURE delete_default_dest(dblink IN VARCHAR2);
136 -- Delete a node from the default list for replication targets
137 -- Input parameters
138 -- dblink
139 -- name of the node (dblink) to delete from the default list.
140 -- Operation is a no-op if dblink is not in the list.
141 -- Exceptions
142 -- none.
143 -----------------
144
145 FUNCTION push(
146 destination IN VARCHAR2,
147 parallelism IN BINARY_INTEGER := 0,
148 heap_size IN BINARY_INTEGER := 0,
149 stop_on_error IN BOOLEAN := FALSE,
150 write_trace IN BOOLEAN := FALSE,
151 startup_seconds IN BINARY_INTEGER := 0,
152 execution_seconds IN BINARY_INTEGER := seconds_infinity,
153 delay_seconds IN BINARY_INTEGER := 0,
154 transaction_count IN BINARY_INTEGER := transactions_infinity,
155 delivery_order_limit IN NUMBER := delivery_order_infinity
156 ) RETURN BINARY_INTEGER;
157 --
158 -- Push transactions queued for destination node, choosing either
159 -- serial or parallel propagation.
160 --
161 -- Parameters:
162 -- destination
163 -- name of destination (dblink) to push to
164 -- parallelism
165 -- max degree of parallelism of the push
166 -- 0 = (old algorithm) serial propagation
167 -- 1 = (new algorithm) parallel propagation with only 1 slave
168 -- n = (new algorithm) parallel propagation with n slaves
169 -- heap_size
170 -- if > 0, max number of txns to be examined simultaneously for
171 -- parallel scheduling computation; default is to compute this
172 -- from specified parallelism
173 -- stop_on_error
174 -- stop on first error even if not fatal
175 -- write_trace
176 -- record execution result value and non-fatal errors in trace file
177 -- startup_seconds
178 -- max secs to wait for another instance of push
179 -- (pushing to the same destination) to finish
180 -- execution_seconds
181 -- shutdown cleanly after this many seconds of real time
182 -- delay_seconds
183 -- shutdown cleanly if queue is empty for this long
184 -- transaction_count
185 -- shutdown cleanly after pushing this many transactions
186 -- delivery_order_limit
187 -- shutdown cleanly before pushing a transaction with
188 -- delivery_order >= delivery_order_limit
189 --
190 -- Result:
191 -- a value from the constants
192 -- dbms_defer_sys.result_%
193 -- indicating how the push completed
194 --
195 ----------------
196
197 PROCEDURE execute(destination IN VARCHAR2,
198 stop_on_error IN BOOLEAN := FALSE,
199 transaction_count IN BINARY_INTEGER := 0,
200 execution_seconds IN BINARY_INTEGER := 0,
201 execute_as_user IN BOOLEAN,
202 delay_seconds IN NATURAL := 0,
203 batch_size IN NATURAL := 0);
204 -- The execute_as_user parameter is obsolete and ignored.
205 -----------------
206
207 PROCEDURE execute(destination IN VARCHAR2,
208 stop_on_error IN BOOLEAN := FALSE,
209 transaction_count IN BINARY_INTEGER := 0,
210 execution_seconds IN BINARY_INTEGER := 0,
211 delay_seconds IN NATURAL := 0,
212 batch_size IN NATURAL := 0);
213 -- Execute transactions queued for destination_node using the security
214 -- context of the propagator. stop_on_error
215 -- determines whether processing of subsequent transaction continues
216 -- after an error is detected.
217 -- deftrandest (and defcalldest if appropriate) entries
218 -- for the successfully executed transactions are deleted and if there
219 -- are no other references, the defcall and deftran entries are deleted.
220 --
221 -- Input Parameters:
222 -- destination
223 -- node (dblink) at which to execute
224 -- deferred transaction. Case
225 -- insensitive comparisons used.
226 -- stop_on_error
227 -- If TRUE, execution of queued transactions will
228 -- alway stop when an error is
229 -- encountered, leaving unattempted transaction in
230 -- the queue. If FALSE,
231 -- execution continues except when errors that appear
232 -- to mean that node is
233 -- unavailable are encountered, it which case execution
234 -- always stops, leaving
235 -- unattempted transactions queued.
236 -- transaction_count
237 -- If positive, at most this many transactions will be executed.
238 -- executions_seconds
239 -- If positive, execution will stop after completions of the
240 -- last transaction after this many seconds of executions.
241 -- delay_seconds
242 -- If positive, the routine will sleep for this many seconds before
243 -- returning when it finds no deferred RPCs queued for the destination
244 -- Non-zero values can reduce execution overhead compared to calling
245 -- dbms_defer_sys.execute from a tight loop.
246 -- batch_size
247 -- The number of deferred rpc calls should be executed before
248 -- committing deferred transactions. If batch_size is 0 a commit will
249 -- occur after each deferred transaction. If batch_size is greater than
250 -- zero a commit will occur when the total number of deferred calls
251 -- executed exceeds batch_size and a complete transaction has been
252 -- executed.
253 --
254 -- Exceptions
255 -- Raises the last exception encountered before execution
256 -- stops because of
257 -- an exception.
258 ----------------
259
260 PROCEDURE execute_error(deferred_tran_id IN VARCHAR2,
261 destination IN VARCHAR2);
262 -- (Re)Execute transactions that previously encountered conflicts.
263 -- Each transaction is executed in the security context of the original
264 -- receiver of the transaction.
265 -- Execution stops when any error is encountered. If some input is null,
266 -- then each transaction is committed as it completes. If exactly one
267 -- transaction is specified, then the transactions is not committed.
268 -- Upon successful execution, transactions are removed for deferror, and if
269 -- there are no other references, entries are deleted from
270 -- defcall and deftran.
271 -- Input Parameters:
272 -- deferred_tran_id
273 -- The identifier of the transaction to be reexecuted.
274 -- If null then all transactions in deferror matching
275 -- destination (as specified) are re-executed.
276 -- destination
277 -- dblink that transaction was originally destined to.
278 -- Must not be null.
279 -- Exceptions
280 -- Raises an exception if destination is null.
281 -- Raises an exception if the original receiver is an invalid user.
282 -- Raises the last exception encountered before execution
283 -- stops because of an exception.
284 ----------------
285
286 PROCEDURE execute_error_as_user(deferred_tran_id IN VARCHAR2,
287 destination IN VARCHAR2);
288 -- (Re)Execute transactions that previously encountered conflicts.
289 -- Each transaction is executed in the security context of the connected
290 -- user.
291 -- Execution stops when any error is encountered. If some input is null,
292 -- then each transaction is committed as it completes. If exactly one
293 -- transaction is specified, then the transactions is not committed.
294 -- Upon successful execution, transactions are removed for deferror, and if
295 -- there are no other references, entries are deleted from
296 -- defcall and deftran.
297 -- Input Parameters:
298 -- deferred_tran_id
299 -- The identifier of the transaction to be reexecuted.
300 -- If null then all transactions in deferror matching
301 -- destination (as specified) are re-executed.
302 -- destination
303 -- dblink that transaction was originally destined to.
304 -- Must not be null.
305 -- Exceptions
306 -- Raises an exception if destination is null.
307 -- Raises the last exception encountered before execution
308 -- stops because of an exception.
309 ----------------
310
311 PROCEDURE delete_tran(deferred_tran_id IN VARCHAR2,
312 destination IN VARCHAR2);
313 -- Delete transactions from queues. Deletes deftrandest (and defcalldest
314 -- entries if appropriate. If there are not other references,
315 -- deftran and defcall entries are deleted.
316 -- Input Parameters:
317 -- destination
318 -- dblink for which transaction(s) are to be removed from queues.
319 -- If null, the transaction specified by the other parameters are
320 -- deleted from queues for all destinations.
321 -- deferred_tran_id
322 -- The identifier of the transaction to be deleted
323 -- If null then all transactions matching destination
324 -- are deleted.
325 -- Exceptions
326 -- tid and/or node not found.
327 ---------------
328 PROCEDURE delete_error(deferred_tran_id IN VARCHAR2,
329 destination IN VARCHAR2);
330
331 -- Delete transactions from deferror table. If there are
332 -- not other references,
333 -- deftran and defcall entries are deleted.
334 -- Input Parameters:
335 -- destination
336 -- destination for which transaction(s) are to be removed from
337 -- deferror.
338 -- If null, the transaction specified by the other parameters are
339 -- deleted from deferror for all destinations.
340 -- deferred_tran_id
341 -- The identifier of the transaction to be deleted
342 -- If null then all transactions matching destination and
343 -- are deleted.
344 -- Exceptions
345 -- tid and/or node not found.
346 ---------------
347
348 PROCEDURE schedule_execution(dblink IN VARCHAR2,
349 interval IN VARCHAR2,
350 next_date IN DATE,
351 reset IN BOOLEAN default FALSE,
352 stop_on_error IN BOOLEAN := NULL,
353 transaction_count IN BINARY_INTEGER := NULL,
354 execution_seconds IN BINARY_INTEGER := NULL,
355 execute_as_user IN BOOLEAN,
356 delay_seconds IN NATURAL := NULL,
357 batch_size IN NATURAL := NULL);
358 -- The execute_as_user parameter is obsolete and ignored.
359 -----------------
360
361 PROCEDURE schedule_execution(dblink IN VARCHAR2,
362 interval IN VARCHAR2,
363 next_date IN DATE,
364 reset IN BOOLEAN default FALSE,
365 stop_on_error IN BOOLEAN := NULL,
366 transaction_count IN BINARY_INTEGER := NULL,
367 execution_seconds IN BINARY_INTEGER := NULL,
368 delay_seconds IN NATURAL := NULL,
369 batch_size IN NATURAL := NULL);
373 -- dblink
370 -- Insert or update a defschedule entry and signal the background process.
371 -- this procedure does a commit;
372 -- Input Parameters:
374 -- Queue name to schedule execution for;
375 -- interval
376 -- If non-null then DefSchedule.interval for dblink is set to this
377 -- value. If null and the DefSchedule entry for dblink exists,
378 -- the value of DefSchedule.interval is not modified. If
379 -- null and the DefSchedule entry
380 -- for dblink does not exist, then the DefSchedule entry for
381 -- dblink is created with a null interval value.
382 -- next_date
383 -- If non-null then DefSchedule.next_date for dblink is set to this
384 -- value. If null and the DefSchedule entry for dblink exists, the value
385 -- of DefSchedule.next_date is not modified. If null and
386 -- the DefSchedule entry
387 -- for dblink does not exist, then the DefSchedule entry
388 -- for dblink is created with a null next_date value.
389 -- reset
390 -- If TRUE then last_txn_count, last_error, and last_msg are nulled.
391 -- stop_on_error
392 -- transaction_count
393 -- execution_seconds
394 -- delay_seconds
395 -- batch_size
396 -- If non-null, these parameters are passed to the
397 -- dbms_defer_sys.execute call that is scheduled for execution by
398 -- this call.
399 -----------------
400
401 PROCEDURE schedule_push(
402 destination IN VARCHAR2,
403 interval IN VARCHAR2,
404 next_date IN DATE,
405 reset IN BOOLEAN := FALSE,
406 parallelism IN BINARY_INTEGER := NULL,
407 heap_size IN BINARY_INTEGER := NULL,
408 stop_on_error IN BOOLEAN := NULL,
409 write_trace IN BOOLEAN := NULL,
410 startup_seconds IN BINARY_INTEGER := NULL,
411 execution_seconds IN BINARY_INTEGER := NULL,
412 delay_seconds IN BINARY_INTEGER := NULL,
413 transaction_count IN BINARY_INTEGER := NULL
414 );
415 --
416 -- Schedule a job to invoke push
417 --
418 -- Parameters:
419 -- interval
420 -- used to calculate the next next_date, via
421 -- select _interval_ into next_date from dual;
422 -- next_date
423 -- the next date that the queue will be pushed
424 -- to the specified destination
425 -- reset
426 -- if TRUE then last_txn_count, last_error, and last_msg
427 -- are nulled in the def$_destination row for the
428 -- specified destination
429 --
430 -- remaining parameters are as for push
431 -----------------
432
433 PROCEDURE unschedule_execution(dblink IN VARCHAR2);
434 -- Delete a defschedule entry. Signal to background process to stop
435 -- servicing this queue.
436 -- Obsolescent; use unschedule_push, below.
437 -- Input Parameters:
438 -- dblink
439 -- Queue name to stop automatic execution of.
440 -- Exceptions:
441 -- NO_DATA_FOUND
442 -- no entry for dblink in DefSchedule.
443 -----------------
444
445 PROCEDURE unschedule_push(dblink IN VARCHAR2);
446 -- Delete a defschedule entry.
447 -- Signal to background process to stop servicing this queue.
448 -- Input Parameters:
449 -- dblink
450 -- Queue name to stop automatic execution of.
451 -- Exceptions:
452 -- NO_DATA_FOUND
453 -- no entry for dblink in DefSchedule.
454 -----------------
455
456 FUNCTION disabled(destination IN VARCHAR2,
457 catchup IN RAW := '00') RETURN BOOLEAN;
458 --
459 -- Test whether disabled for given destination.
460 --
461 -- Parameters:
462 -- destination or NULL (which implicitly identifies the purge row)
463 -- catchup: extension ID if any
464 -- Returns:
465 -- TRUE iff the deferred RPC queue is disabled for the given
466 -- destination.
467 --
468 -- Raises the following exceptions:
469 -- no_data_found:
470 -- if the "destination" does not appear in defschedule.
471 -----------------
472
473 PROCEDURE set_disabled(destination IN VARCHAR2,
474 disabled IN BOOLEAN := TRUE,
475 catchup IN RAW := '00',
476 override IN BOOLEAN := FALSE);
477 --
478 -- Turn on/off the disabled state for a destination.
479 --
480 -- Parameters:
481 -- destination
482 -- name of dest site, or NULL (implicitly identifies the purge row)
483 -- disabled
484 -- on/off
485 -- catchup
486 -- extension ID if any
487 -- override
488 -- see comment below
489 -- WARNING: Do not set this parameter unless directed to do so by
490 -- Oracle Support Services.
491 --
492 -- If "disabled" is TRUE, disable propagation to the given
493 -- "destination." All future invocations of dbms_defer_sys.execute
494 -- will not be able to push the deferred RPC queue to this
495 -- destination until it is enabled. This function has no effect
496 -- on a session already pushing the queue to the given
497 -- destination. This function has no effect on sessions appending
498 -- to the queue with dbms_defer.
499 -- If "disabled" is FALSE, enable propagation to the given "destination."
503 -- sessions.
500 -- Although this does not push the queue, it permits future invocations
501 -- of dbms_defer_sys.execute to push the queue to the given destination.
502 -- In either case, a COMMIT is required for this to take effect in other
504 -- If "override" is TRUE, it ignores whether the disabled state
505 -- was set internally for synchronization and always tries to set
506 -- the state as specified by the "disabled" parameter.
507 --
508 -- Raises the following exceptions:
509 -- no_data_found:
510 -- if the "destination" does not appear in defschedule.
511 -- dbms_defer_sys.cantsetdisabled:
512 -- if the disabled was set internally for synchronization.
513 -----------------
514
515 PROCEDURE register_propagator(username IN VARCHAR2);
516 -- Register the given user as the propagator for the local database. It
517 -- also grants to the given user CREATE SESSION, CREATE PROCEDURE,
518 -- CREATE DATABASE LINK and EXECUTE ANY PROCEDURE
519 -- privileges (so that the user can create wrappers).
520 -- It ensures that only one user is the propagator. It ignores any existing
521 -- invalid propagator that may be in the catalog.
522 -- Input Parameters:
523 -- username
524 -- Name of the user
525 -- Exceptions:
526 -- missinguser
527 -- The given user does not exist.
528 -- alreadypropagator
529 -- The given user is already the propagator.
530 -- duplicatepropagator
531 -- There is already a different propagator.
532 -----------------
533
534 PROCEDURE unregister_propagator(username IN VARCHAR2,
535 timeout IN INTEGER
536 DEFAULT dbms_lock.maxwait);
537 -- Unregister the given user as the given propagator for the local database.
538 -- It also revokes all privileges that were granted by register_propagator()
539 -- from the given user, including those identical privileges that were
540 -- granted independently of register_propagator().
541 -- It drops any existing genereted wrappers in the schema of the given
542 -- propagator, and marks them as dropped in the replication catalog.
543 -- If the propagator is in use, it will wait until the provided timeout
544 -- (in seconds), then an exception will be raised.
545 -- Input Parameters:
546 -- username
547 -- Name of the user
548 -- timeout
549 -- Timeout in seconds. If the propagator is in use, it will wait until
550 -- the given timeout. The default value is dbms_lock.maxwait.
551 -- Exceptions:
552 -- missingpropagator
553 -- The given user is not the propagator.
554 -- propagator_inuse
555 -- The propagator is in use, thus cannot be unregistered. Try later.
556 -----------------
557
558 FUNCTION exclude_push(timeout IN INTEGER) RETURN INTEGER;
559 -- Acquire an exclusive lock that prevents deferred transaction push
560 -- (either serial or parallel).
561 --
562 -- Input:
563 -- timeout
564 -- Timeout in seconds. If the lock cannot be acquired within this
565 -- time period (either because of an error or because a push is
566 -- currently under way) then the call returns a value of 1 (see
567 -- below).
568 -- A timeout value of dbms_lock.maxwait waits forever.
569 -- Return value (lock held?):
570 -- (as for dbms_lock.acquire(.))
571 -- 0 - success (Y)
572 -- 1 - timeout (N)
573 -- 2 - deadlock (N)
574 -- 4 - already own the lock (Y)
575 --
576 -- Note:
577 -- ** this function does a commit **
578 -- The lock is acquired with release_on_commit=>TRUE, so pushing may
579 -- resume after the next commit.
580 -----------------
581
582 PROCEDURE delete_def_destination(destination IN VARCHAR2,
583 force IN BOOLEAN := FALSE,
584 catchup IN RAW := NULL);
585 -- This procedure is to delete a row in system.def$_destination.
586 -- It is used to get rid of some destination which is not active (no
587 -- replication activities) and will not be active for a significant amount
588 -- of time. Without that entry in def$_destination, purge_method_quick will
589 -- serve its purpose by being able to purge effectively.
590 --
591 -- Input:
592 -- destination: the row with dblink to be deleted
593 --
594 -- force: ignore any safety check and delete the row anyway
595 --
596 -- catchup: catchup value for the destination to be deleted.
597 -- If null, all the rows matching destination will be deleted.
598 --
599 -- Notes:
600 -- 1. To do that, we need to lock the site-specific lock for pushing to
601 -- make sure no one is pushing at that time.
602 -- 2. To avoid repushing transactions after a site is deleted and then
603 -- added back, we make sure there are no transactions for this site
604 -- (regardless whether the transactions have been pushed or not)
605 -- 3. To avoid deleting the destination after an incomplete (unclean)
606 -- parallel push, we have an explicit check on that.
607 -- 4. If force is TRUE, we will ignore condition (2) and (3). What it means
608 -- is unless you are absolutely sure you want to get rid of the site
609 -- (destination) and there is NO transaction for it and parallel push is
610 -- clean, do NOT set force to TRUE. Otherwise, you may end up
611 -- repushing some transactions.
615 -- 6. There is no commit in this procedure. So, the caller can rollback
612 -- 5. To delete a dblink which has some repschema and D-type transaction,
613 -- you need to remove the repschema and push, purge the D-type
614 -- transaction first.
616 -- the change if necessary.
617 ------------------
618
619 FUNCTION purge(
620 purge_method IN BINARY_INTEGER := purge_method_quick,
621 rollback_segment IN VARCHAR2 := NULL,
622 startup_seconds IN BINARY_INTEGER := 0,
623 execution_seconds IN BINARY_INTEGER := seconds_infinity,
624 delay_seconds IN BINARY_INTEGER := 0,
625 transaction_count IN BINARY_INTEGER := transactions_infinity,
626 write_trace IN BOOLEAN := FALSE
627 ) RETURN BINARY_INTEGER;
628
629 -- Purge pushed transactions from the queue
630 --
631 -- Parameters:
632 -- purge_method
633 -- a value controlling cost-precision tradeoff; either
634 -- purge_method_quick or purge_method_precise
635 -- rollback_segment
636 -- rollback segment to use while purging the queue
637 -- startup_seconds
638 -- max secs to wait for another instance of push
639 -- (pushing to the same destination) to finish
640 -- execution_seconds
641 -- shutdown cleanly after this many seconds of real time
642 -- delay_seconds
643 -- shutdown cleanly if queue is empty for this long
644 -- transaction_count
645 -- shutdown cleanly after purging this many transactions
646 -- write_trace
647 -- record result value in trace file
648 --
649 -- Result:
650 -- a value from the constants
651 -- dbms_defer_sys.result_%
652 -- indicating how the purge completed
653 --
654 -- Exception:
655 -- argoutofrange(-23427): "argument '%s' is out of range"
656 ----------
657
658 PROCEDURE schedule_purge(
659 interval IN VARCHAR2,
660 next_date IN DATE,
661 reset IN BOOLEAN := FALSE,
662 purge_method IN BINARY_INTEGER := NULL,
663 rollback_segment IN VARCHAR2 := NULL,
664 startup_seconds IN BINARY_INTEGER := NULL,
665 execution_seconds IN BINARY_INTEGER := NULL,
666 delay_seconds IN BINARY_INTEGER := NULL,
667 transaction_count IN BINARY_INTEGER := NULL,
668 write_trace IN BOOLEAN := NULL
669 );
670 --
671 -- Schedule a job to invoke purge
672 --
673 -- Parameters:
674 -- interval
675 -- used to calculate the next next_date, via
676 -- select _interval_ into next_date from dual;
677 -- next_date
678 -- the next date that the queue will be pushed
679 -- to the specified destination
680 -- reset
681 -- if TRUE then last_txn_count, last_error, and last_msg
682 -- are nulled in the "purge" def$_destination row, i.e.,
683 -- the row for this site's unqualified global name.
684 --
685 -- other parameters as for purge
686 --
687
688 -------------------------------------------------------------------------
689
690 PROCEDURE unschedule_purge;
691 --
692 -- Delete defschedule entry for purge.
693 -- Signal to background process to stop servicing purge.
694 --
695
696 -------------------------------------------------------------------------
697
698 PROCEDURE clear_prop_statistics(dblink in VARCHAR2);
699 --
700 -- Clear the statistics of a destination in defschdule. This procedure
701 -- will clear the following information from defschedule:
702 --
703 -- total_txn_count
704 -- avg_throughput
705 -- avg_latency
706 -- total_bytes_sent
707 -- total_bytes_received
708 -- total_round_trips
709 -- total_admin_count
710 -- total_error_count
711 -- total_sleep_time
712 --
713 -- Parameters :
714 -- dblink
715 -- The destination whose statistics in defschedule are to be cleared.
716 --
717
718 -------------------------------------------------------------------------
719
720 PROCEDURE nullify_trans_to_destination(dblink IN VARCHAR2,
721 catchup IN RAW := NULL);
722 -- For internal use only.
723
724 -------------------------------------------------------------------------
725
726 PROCEDURE nullify_all_trans;
727 -- For internal use only.
728
729 PROCEDURE execute_error_call_as_user(deferred_tran_id IN VARCHAR2,
730 callno IN NUMBER);
731 -- For internal use only.
732
733 PROCEDURE execute_error_call(deferred_tran_id IN VARCHAR2,
734 callno IN NUMBER);
735 -- For internal use only.
736
737 FUNCTION push_with_catchup(
738 destination IN VARCHAR2,
739 parallelism IN BINARY_INTEGER := 0,
740 heap_size IN BINARY_INTEGER := 0,
741 stop_on_error IN BOOLEAN := FALSE,
742 write_trace IN BOOLEAN := FALSE,
743 startup_seconds IN BINARY_INTEGER := 0,
744 execution_seconds IN BINARY_INTEGER := seconds_infinity,
745 delay_seconds IN BINARY_INTEGER := 0,
746 transaction_count IN BINARY_INTEGER := transactions_infinity,
747 delivery_order_limit IN NUMBER := delivery_order_infinity,
751
748 catchup IN RAW := NULL
749 ) RETURN BINARY_INTEGER;
750 -- For internal use only.
752 END dbms_defer_sys;