ADD_NEW_MASTERS Procedure

This procedure adds the master sites in the DBA_REPSITES_NEW data dictionary view to the master groups specified when the SPECIFY_NEW_MASTERS procedure was run. Information about these new master sites are added to the replication catalog at all available master sites.

All master sites instantiated with object-level export/import must be accessible at this time. Their new replication groups are added in the quiesced state. Master sites instantiated through full database export/import or through changed-based recovery do not need to be accessible.

Run this procedure after you run the SPECIFY_NEW_MASTERS procedure.

Caution:

After running this procedure, do not disable or enable propagation of the deferred transactions queue until after the new master sites are added. The DBA_REPEXTENSIONS data dictionary view must be clear before you disable or enable propagation. You can use the Replication Management tool or the SET_DISABLED procedure in the DBMS_DEFER_SYS package to disable or enable propagation.

Note:

You can use either Data Pump export/import or original export/import to perform exports and imports in an Advanced Replication environment. General references to export/import in this document refer to both Data Pump and original export/import.

See Also:

"SPECIFY_NEW_MASTERS Procedure"
"Adding New Master Sites" for more information about adding master sites to a master group

Syntax

DBMS_REPCAT.ADD_NEW_MASTERS (
   export_required                IN    BOOLEAN,
   { available_master_list        IN    VARCHAR2, 
 | available_master_table       IN    DBMS_UTILITY.DBLINK_ARRAY,}
   masterdef_flashback_scn        OUT   NUMBER,   
   extension_id                   OUT   RAW,   
   break_trans_to_masterdef       IN    BOOLEAN   := false,    
   break_trans_to_new_masters     IN    BOOLEAN   := false,    
   percentage_for_catchup_mdef    IN    BINARY_INTEGER  := 100,    
   cycle_seconds_mdef             IN    BINARY_INTEGER  := 60,    
   percentage_for_catchup_new     IN    BINARY_INTEGER  := 100,    
   cycle_seconds_new              IN    BINARY_INTEGER  := 60);

Note:

This procedure is overloaded. The available_master_list and available_master_table parameters are mutually exclusive.

Parameters

Table 18-6 ADD_NEW_MASTERS Procedure Parameters

Parameter	Description
export_required	Set to `true` if either object-level or full database export is required for at least one of the new master sites. Set to `false` if you are using change-based recovery for all of the new master sites.
available_master_list	A comma-delimited list of the new master sites to be instantiated using object-level export/import. The sites listed must match the sites specified in the `SPECIFY_NEW_MASTERS` procedure. List only the new master sites, not the existing master sites. Do not put any spaces between site names. Specify `NULL` if all masters will be instantiated using full database export/import or change-based recovery.
available_master_table	A table that lists the new master sites to be instantiated using object-level export/import. The sites in the table must match the sites specified in the `SPECIFY_NEW_MASTERS` procedure. Do not specify masters that will be instantiated using full database export/import or change-based recovery. In the table that lists the master sites to be instantiated using object-level export/import, list only the new master sites for the master groups being extended. Do not list the existing master sites in the master groups being extended. The first master site should be at position 1, the second at position 2, and so on.
masterdef_flashback_scn	This `OUT` parameter returns a system change number (SCN) that must be used during export or change-based recovery. Use the value returned by this parameter for the `FLASHBACK_SCN` export parameter when you perform the export. You can find the `flashback_scn` value by querying the `DBA_REPEXTENSIONS` data dictionary view.
extension_id	This `OUT` parameter returns an identifier for the current pending request to add master databases without quiesce. You can find the `extension_id` by querying the `DBA_REPSITES_NEW` and `DBA_REPEXTENSIONS` data dictionary views.
break_trans_to_masterdef	This parameter is meaningful only if `export_required` is set to `true`. If `break_trans_to_masterdef` is set to `true`, then existing masters may continue to propagate their deferred transactions to the master definition site for replication groups that are not adding master sites. Deferred transactions for replication groups that are adding master sites cannot be propagated until the export completes. Each deferred transaction is composed of one or more remote procedure calls (RPCs). If set to `false` and a transaction occurs that references objects in both unaffected master groups and master groups that are being extended, then the transaction may be split into two parts and sent to a destination in two separate transactions at different times. Such transactions are called split-transactions. If split-transactions are possible, then you must disable integrity constraints that may be violated by this behavior until the new master sites are added. If `break_trans_to_masterdef` is set to `false`, then existing masters cannot propagate their deferred transactions to the master definition site.
break_trans_to_new_masters	If `break_trans_to_new_masters` is set to `true`, then existing master sites may continue to propagate deferred transactions to the new master sites for replication groups that are not adding master sites. Each deferred transaction is composed of one or more remote procedure calls (RPCs). If set to `true` and a transaction occurs that references objects in both unaffected master groups and master groups that are being extended, then the transaction may be split into two parts and sent to a destination in two separate transactions at different times. Such transactions are called split-transactions. If split-transactions are possible, then you must disable integrity constraints that may be violated by this behavior until the new master sites are added. If `break_trans_to_new_masters` is set to `false`, then propagation of deferred transaction queues to the new masters is disabled.
percentage_for_catchup_mdef	This parameter is meaningful only if `export_required` and `break_trans_to_masterdef` are both set to `true`. The percentage of propagation resources that should be used for catching up propagation to the master definition site. Must be a multiple of 10 and must be between 0 and 100.
cycle_seconds_mdef	This parameter is meaningful when `percentage_for_catchup_mdef` is both meaningful and set to a value between 10 and 90, inclusive. In this case, propagation to the masterdef alternates between replication groups that are not being extended and replication groups that are being extended, with one push to each during each cycle. This parameter indicates the length of the cycle in seconds.
percentage_for_catchup_new	This parameter is meaningful only if `break_trans_to_new_masters` is set to `true`. The percentage of propagation resources that should be used for catching up propagation to new master sites. Must be a multiple of 10 and must be between 0 and 100.
cycle_seconds_new	This parameter is meaningful when `percentage_for_catchup_new` is both meaningful and set to a value between 10 and 90, inclusive. In this case, propagation to a new master alternates between replication groups that are not being extended and replication groups that are being extended, with one push to each during each cycle. This parameter indicates the length of the cycle in seconds.

Exceptions

Table 18-7 ADD_NEW_MASTERS Procedure Exceptions

Exception	Description
nonmasterdef	Invocation site is not the master definition site.
typefailure	The parameter value specified for one of the parameters is not appropriate.
novalidextreq	No valid extension request. The `extension_id` is not valid.
nonewsites	No new master sites to be added for the specified extension request.
notanewsite	Not a new site for extension request. A site was specified that was not specified when you ran the `SPECIFY_NEW_MASTERS` procedure.
dbnotcompatible	Feature is incompatible with database version. All databases must be at 9.0.1 or higher compatibility level.

Usage Notes

For a new master site to be instantiated using change-based recovery or full database export/import, the following conditions apply:

The new master sites cannot have any existing replication groups.
The master definition site cannot have any materialized view groups.
The master definition site must be the same for all of the master groups. If one or more of these master groups have a different master definition site, then do not use change-based recovery or full database export/import. Use object-level export/import instead.
The new master site must include all of the replication groups in the master definition site when the extension process is complete. That is, you cannot add a subset of the master groups at the master definition site to the new master site; all of the groups must be added.

Note:
To use change-based recovery, the existing master site and the new master site must be running under the same operating system, although the release of the operating system can differ.

For object-level export/import, before importing ensure that all the requests in the DBA_REPCATLOG data dictionary view for the extended groups have been processed without any error.