32
DBMS_REFRESH

DBMS_REFRESH enables you to create groups of snapshots that can be refreshed together to a transactionally consistent point in time.

Summary of Subprograms

Table 32-1 DBMS_REFRESH Package Subprograms

Subprogram	Description
ADD procedure	Adds snapshots to a refresh group.
CHANGE procedure	Changes the refresh interval for a snapshot group.
DESTROY procedure	Removes all of the snapshots from a refresh group and deletes the refresh group.
MAKE procedure	Specifies the members of a refresh group and the time interval used to determine when the members of this group should be refreshed.
REFRESH procedure	Manually refreshes a refresh group.
SUBTRACT procedure	Removes snapshots from a refresh group.

ADD procedure

This procedure adds snapshots to a refresh group.

See Also:
For additional information, see "Add Objects To Refresh Group" in the Oracle8i Replication API Reference. Also see "Snapshot Concepts & see "Snapshot Concepts & Architecture" in the Oracle8i Replication manual.

Syntax

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.

Parameters

Table 32-2 ADD Procedures Parameters

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, then 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.

CHANGE procedure

This procedure changes the refresh interval for a snapshot group.

See Also:
For additional information, see "Snapshot Concepts & Architecture" in the Oracle8i Replication manual.

Syntax

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);

Parameters

Table 32-3 CHANGE Procedures Parameters

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, then 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), then 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, then 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.

DESTROY procedure

This procedure removes all of the snapshots from a refresh group and delete the refresh group.

See Also:
For additional information, see "Snapshot Concepts & Architecture" in the Oracle8i Replication manual.

Syntax

DBMS_REFRESH.DESTROY (
   name   IN   VARCHAR2);

Parameters

Table 32-4 DESTROY Procedure Parameters

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

MAKE procedure

This procedure specifies the members of a refresh group and the time interval used to determine when the members of this group should be refreshed.

See Also:
For additional information, see "Create Refresh Group" in Oracle8i Replication API Reference. Also see "Snapshot Concepts & Architecture" in the Oracle8i Replication manual.

Syntax

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 32-5 MAKE Procedure Parameters

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, then 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 if your `NEXT_DATE` evaluates to Monday, then Oracle refreshes 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.
implicit_destroy	Set this 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, then you must set this 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	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 to 0 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), then 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, then 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 this unless so directed by Oracle Worldwide Support.

REFRESH procedure

This procedure manually refreshes a refresh group.

See Also:
For additional information, see "Snapshot Concepts & Architecture" in the Oracle8i Replication manual.

Syntax

DBMS_REFRESH.REFRESH (
   name   IN    VARCHAR2);

Table 32-6 REFRESH Procedure Parameters

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

SUBTRACT procedure

This procedure removes snapshots from a refresh group.

See Also:
For additional information, see "Snapshot Concepts & Architecture" in the Oracle8i Replication manual.

Syntax

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.

Parameters

Table 32-7 SUBTRACT Procedure Parameters

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, then the first snapshot should be in position 1 and the N+1 position should be set to `NULL`.
lax	Set this 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.

32DBMS_REFRESH

Summary of Subprograms

Table 32-1 DBMS_REFRESH Package Subprograms

ADD procedure

Syntax

Parameters

Table 32-2 ADD Procedures Parameters

CHANGE procedure

Syntax

Parameters

Table 32-3 CHANGE Procedures Parameters

DESTROY procedure

Syntax

Parameters

Table 32-4 DESTROY Procedure Parameters

MAKE procedure

Syntax

Table 32-5 MAKE Procedure Parameters

REFRESH procedure

Syntax

Table 32-6 REFRESH Procedure Parameters

SUBTRACT procedure

Syntax

Parameters

Table 32-7 SUBTRACT Procedure Parameters

32
DBMS_REFRESH