DBMS_DG

The DBMS_DG package gives you tools to manage Oracle Data Guard broker configurations programmatically.

With procedures for creating, modifying, and removing configurations, handling failover and switchover, setting properties, and monitoring health, you can automate routine Data Guard tasks using scripts and custom tools.

In addition, there is also functionality to allow applications to notify the primary database or the fast-start failover target database in an Oracle Data Guard broker environment to initiate a fast-start failover when the application encounters a condition that warrants a failover.

This chapter contains the following topics:

• Security Model

• Summary of the DBMS_DG Subprogram

Note: A multitenant container database is the only supported architecture in Oracle Database 21c and later releases. While the documentation is being revised, legacy terminology may persist. In most cases, “database” and “non-CDB” refer to a CDB or PDB, depending on context. In some contexts, such as upgrades, “non-CDB” refers to a non-CDB from a previous release.

Note: If you are working in a multitenant container database (CDB), then functions within DBMS_DG are only executed at the root level. Ensure you are connected at the root level, not at the individual pluggable database (PDB) level.

See Also: Oracle Data Guard Broker

DBMS_DG Security Model

The DBMS_DG package runs with invoker’s rights and requires the SYSDBA privilege.

Oracle Data Guard DBMS_DG API Summary

The Oracle Data Guard DBMS_DG APIs allow you to manage a broker configuration.

Table 1 DBMS_DG API Summary

API	Effect
ADD_DATABASE	Adds a standby database to the Data Guard broker configuration.
ADD_FAR_SYNC	Adds a far sync instance to the Data Guard broker configuration.
ADD_RECOVERY_APPLIANCE	Adds a Zero Data Loss Recovery Appliance to the Data Guard broker configuration.
CONVERT_TO_PHYSICAL	Used to convert a snapshot standby database to a physical standby database.
CONVERT_TO_SNAPSHOT	Converts a snapshot standby database to a physical standby database.
CREATE_CONFIGURATION	Used to create a Data Guard broker configuration.
DISABLE	Used to disable a configuration member.
DISABLE_CONFIGURATION	This function is used to disable broker management of a configuration.
DISABLE_FS_FAILOVER	Used to to disable fast-start failover.
DISABLE_FS_FAILOVER_CONDITION	Used to remove conditions for which a fast-start failover should be performed.
ENABLE	This function is used to to enable broker management of the specified member.
ENABLE_CONFIGURATION	Enables broker management of a configuration..
ENABLE_FS_FAILOVER	Is used to enable fast-start failover..
ENABLE_FS_FAILOVER_CONDITION	Can be used to specify additional conditions for which a fast-start failover should be performed.
FAILOVER	This function can be used to perform a database failover.
GET_CONFIGURATION_PROPERTY	Is used to get the value of a configuration property.
GET_CONFIGURATION_TAG	Retrieves the value of a configuration tag.
GET_MEMBER_TAG	Retrieves the value of a member tag.
GET_PROPERTY	Is used to get the value of a member property.
HEALTH_CHECK	Is used to get the broker to evaluate the health of all configuration members.
INITIATE_FS_FAILOVER	Is used to specify a condition string that, when encountered by an application, allows the application to request that a fast-start failover be invoked.
REINSTATE	Can be used to reinstate a database after a failover operation.
REMOVE	Is used to remove a member the Data Guard broker configuration.
REMOVE_CONFIGURATION	Is used to remove the Data Guard broker configuration.
REMOVE_CONFIGURATION_TAG	Removes a configuration tag.
REMOVE_CONFIGURATION_TAG_ALL	Removes all configuration tags.
REMOVE_MEMBER_TAG	Removes a member tag.
REMOVE_MEMBER_TAG_ALL	Removes all member tags.
REMOVE_INSTANCE	Can be used to remove an instance from a member the Data Guard broker configuration.
RESET_CONFIGURATION_PROPERTY	Is used to reset a configuration property to its default value.
RESET_PROPERTY	Can be used to reset a member configurable property to its default value.
SET_CONFIGURATION_PROPERTY	Can be used to set a value for a configuration property.
SET_CONFIGURATION_TAG	Sets a value of a configuration tag.
SET_MEMBER_TAG	Sets a value of a member tag. If the key doesn’t exist, a new key is created.
SET_PROPERTY	Can be used to set a value for a member configurable property.
SET_PROTECTION_MODE	Can be used to set the configuration protection mode.
SET_STATE_APPLY_OFF	Is used to set the apply state to off for a logical or physical standby database.
SET_STATE_APPLY_ON	Is used to set the apply state to onfor a logical or physical standby database..
SET_STATE_TRANSPORT_OFF	Used to set the redo transport state to off for a primary database.
SET_STATE_TRANSPORT_ON	Can be used to set the redo transport state to on for a primary database.
STOP_OBSERVER	used to stop fast-start failover observers in a Data Guard broker configuration.
SWITCHOVER	Is used to perform a database switchover.
WAIT	Is used to wait for various Data Guard broker events to occur.

ADD_DATABASE

The ADD_DATABASE function can be used to add a standby database to the Data Guard broker configuration.

ADD_DATABASE Function

Format

DBMS_DG.ADD_DATABASE (
     database_name          IN VARCHAR2,
     database_ci            IN VARCHAR2,
     severity               OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
database_name	The name that will be used by the broker to refer to this standby database. It must match (case-insensitive) the value of the corresponding database DB_UNIQUE_NAME initialization parameter.
database_ci	A fully specified connect descriptor or a name to be resolved by an Oracle Net Services naming method (for example, TNS). The value you specify is also used as the initial value of the DGConnectIdentifier database property.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can only be called while connected to a primary database or an enabled standby database or far sync instance.

Return Values

Error	Description
ORA-00000: normal, successful completion	The standby database was successfully added to the Data Guard broker configuration.
Other	The Data Guard broker was unable to add the standby database to the configuration and the return value will indicate the reason for this failure.

ADD_FAR_SYNC

The ADD_FAR_SYNC function can be used to add a far sync instance to the Data Guard broker configuration. To use this command, Oracle wallet-based authentication must be configured and you must connect with SYSDBA privilege.

ADD_FAR_SYNC Function

Format

DBMS_DG.ADD_FAR_SYNC (
     far_sync_name          IN VARCHAR2,
     far_sync_ci            IN VARCHAR2,
     severity               OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
far_sync_name	The name that will be used by the broker to refer to this far sync instance. It must match (case-insensitive) the value of the corresponding database DB_UNIQUE_NAME initialization parameter.
far_sync_ci	A fully specified connect descriptor or a name to be resolved by an Oracle Net Services naming method (for example, TNS). The value you specify is also used as the initial value of the DGConnectIdentifier database property.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can only be called while connected to a primary database or an enabled standby database or far sync instance.

Return Values

Error	Description
ORA-00000: normal, successful completion	The far sync instance was successfully added to the Data Guard broker configuration.
Other	The Data Guard broker was unable to add the far sync instance to the configuration and the return value will indicate the reason for this failure.

ADD_RECOVERY_APPLIANCE

The ADD_FAR_SYNC function can be used to add a Zero Data Loss Recovery Appliance to the Data Guard broker configuration.

ADD_RECOVERY_APPLIANCE Function

Format

DBMS_DG.ADD_RECOVERY_APPLIANCE (
     ra_name          IN VARCHAR2,
     ra_ci            IN VARCHAR2,
     severity         OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
ra_name	The name that will be used by the broker to refer to this Zero Data Loss Recovery Appliance. It must match (case-insensitive) the value of the corresponding database DB_UNIQUE_NAME initialization parameter.
ra_ci	A fully specified connect descriptor or a name to be resolved by an Oracle Net Services naming method (for example, TNS). The value you specify is also used as the initial value of the DGConnectIdentifier property.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can only be called while connected to a primary database or an enabled standby database or far sync instance.

Return Values

Error	Description
ORA-00000: normal, successful completion	The Zero Data Loss Recovery Appliance was successfully added to the Data Guard broker configuration.
Other	The Data Guard broker was unable to add the Zero Data Loss Recovery Appliance to the configuration and the return value will indicate the reason for this failure.

CONVERT_TO_PHYSICAL

The CONVERT_TO_PHYSICAL function can be used to convert a snapshot standby database to a physical standby database.

CONVERT_TO_PHYSICAL Function

Format

DBMS_DG.CONVERT_TO_PHYSICAL (
     db_name          IN VARCHAR2,
     severity         OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
db_name	The DB_UNIQUE_NAME initialization parameter value of the snapshot standby database to be converted to a physical standby database.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The client must be connected to the primary database to call this function.

• The snapshot standby database must be running in mount mode for the conversion to physical standby to complete.

Return Values

Error	Description
ORA-00000: normal, successful completion	The snapshot standby database was successfully converted to a physical standby database.
ORA-16540: invalid argument	The name specified for the database was not a valid DB_UNIQUE_NAME value.
ORA-16732: Oracle Clusterware is restarting the database instance	Oracle Clusterware is restarting the database to the mode required by the broker to convert the snapshot standby database to a physical standby database. Wait for the database to complete restarting and then retry this function call.
ORA-16897: start database to mount mode	The conversion to physical standby could not be performed because the snapshot standby database was not running in mount mode. Restart the database to mount mode and retry this function call.
ORA-16899: Operation requires a connection to the primary database.	This function must be called while connected to the primary database to complete. Reconnect to the primary database and retry this function call.
Other	The Data Guard broker was unable to convert the database and the return value will indicate the reason for this failure.

CONVERT_TO_SNAPSHOT

The CONVERT_TO_SNAPSHOT function can be used to convert a snapshot standby database to a physical standby database.

CONVERT_TO_SNAPSHOT Function

Format

DBMS_DG.CONVERT_TO_SNAPSHOT (
     db_name          IN VARCHAR2,
     severity         OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
db_name	The DB_UNIQUE_NAME initialization parameter value of the physical standby database to be converted to a snapshot standby database.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The database was successfully converted to a snapshot standby database.
ORA-16540: invalid argument	The name specified for the database was not a valid DB_UNIQUE_NAME value.
Other	The Data Guard broker was unable to convert the database and the return value will indicate the reason for this failure.

CREATE_CONFIGURATION

The CREATE_CONFIGURATION function can be used to create a Data Guard broker configuration. The primary database will be automatically added to the configuration. The value of the primary database’s DB_UNIQUE_NAME initialization parameter value will be fetched from the database.

CREATE_CONFIGURATION Function

DBMS_DG.CREATE_CONFIGURATION (
     config_name          IN VARCHAR2,
     primary_ci           IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	A user-friendly name for the configuration you are creating. Valid names contain any alphanumeric characters. If spaces are included in the name, the name must be enclosed in double or single quotation marks. The name must consist of 30 or fewer bytes.
primary_ci	A fully specified connect descriptor or a name to be resolved by an Oracle Net Services naming method (for example, TNS). The value you specify is also used as the initial value of the DGConnectIdentifier database property.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can only be called while connected to a primary database.

Return Values

Error	Description
ORA-00000: normal, successful completion	The Data Guard broker configuration was created and the primary database has been added to the configuration.
Other	The Data Guard broker was unable to convert the database and the return value will indicate the reason for this failure.

DISABLE

The DISABLE function can be used to convert a snapshot standby database to a physical standby database.

DISABLE Function

DBMS_DG.DISABLE (
     member_name          IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the member to be disabled.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can only be called while connected to a primary database.

Error	Description
ORA-00000: normal, successful completion	The member was successfully disabled.
ORA-16540: invalid argument	The name specified for the member was not a valid DB_UNIQUE_NAME value.
Other	The Data Guard broker was unable to disable the member and the return value will indicate the reason for this failure.

DISABLE_CONFIGURATIO N

The DISABLE_CONFIGURATION function can be used to disable broker management of a configuration so that the so that the configuration and all of its databases are no longer managed by the broker.

DISABLE Function

DBMS_DG.DISABLE_CONFIGURATION (
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can only be called while connected to a primary database.

Return Values

Error	Description
ORA-00000: normal, successful completion	The member was successfully disabled.
Other	The Data Guard broker was unable to disable the member and the return value will indicate the reason for this failure.

DISABLE_FS_FAILOVER

The DISABLE_FS_FAILOVER function can be used to to disable fast-start failover. Using this function will prevent the observer from initiating a failover to the target standby.

DISABLE_FS_FAILOVER Function

DBMS_DG.DISABLE_FS_FAILOVER (
     force           IN BOOLEAN DEFAULT FALSE,
     severity        OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
force	A boolean value to indicate whether fast-start failover should be disabled with the FORCE option. A value of TRUE will cause this function to disable fast-start failover on the member the session is connected. A value of FALSE will cause this function to disable fast-start failover on the primary and current target standby. If both databases cannot disable fast-start failover, it will remain enabled.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• If the primary and target standby database have a network connection, specify FALSE for the force parameter to disable fast-start failover on all databases in the broker configuration. If errors occur during the disable operation, the broker returns an error message and stops the disable operation. You may need to reissue the call with a value of TRUE for the force parameter to override the error conditions and disable fast-start failover on the database to which you are connected.

• Use a value of TRUE for the force parameter when the network between the primary and target standby databases is disconnected or when the database upon which the function is called does not have a connection with the primary database. A value of TRUE for the force parameter disables fast-start failover on the database to which you are connected, even when errors occur.

• Calling this function using a value of TRUE for the force parameter on a primary database that is disconnected from the observer and the target standby database does not prevent the observer from initiating a fast-start failover to the target standby database.

• You can call this function with a value of FALSE for the force parameter while connected to any database in the broker configuration so long as connectivity exists between that database and the primary.

• If this function is called with a value of TRUE for the force parameter at the target standby database and the connection subsequently resumes with the primary database, fast-start failover is disabled on all databases in the configuration.

• Calling this function with a value of TRUE for the force parameter while connected to the primary will disable fast-start failover on the target standby database if there is network connectivity between both databases

Errors	Description
ORA-00000: normal, successful completion	Fast-start failover was disabled according to the value specified by the force parameter.
Other	The Data Guard broker was unable to disable fast-start failover.

DISABLE_FS_FAILOVER_CONDITION

The DISABLE_FS_FAILOVER_CONDITION function can be used to remove conditions for which a fast-start failover should be performed.

DISABLE_FS_FAILOVER_CONDITION Function

DBMS_DG.DISABLE_FS_FAILOVER_CONDITION (
     condition            IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
condition	A fast-start failover condition to disable.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Health Condition	Description
“Datafile Write Errors”	If fast-start failover is enabled and the Datafile Write Errors condition is specified, then a fast-start failover is initiated if write errors are encountered in any data files, including temp files, system data files, and undo files.
“Corrupted Controlfile”	Corrupted controlfile. This condition is enabled by default.
“Corrupted Dictionary”	Dictionary corruption of a critical database object. This condition is enabled by default.
“Inaccessible Logfile”	LGWR is unable to write to any member of a log group due to an I/O error.
“Stuck Archiver”	Archiver is unable to archive a redo log because device is full or unavailable.

Error	Description
ORA-00000: normal, successful completion	Fast-start failover condition was disabled.
Other	The Data Guard broker was unable to disable fast-start failover condition.

ENABLE

The ENABLE function can be used to to enable broker management of the specified member..

ENABLE Function

DBMS_DG.ENABLE (
     member_name          IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the member to be enabled.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The member was successfully disabled.
ORA-16540: invalid argument	The name specified for the member was not a validDB_UNIQUE_NAME value.
Other	The Data Guard broker was unable to enable the member and the return value will indicate the reason for this failure.

ENABLE_CONFIGURATION

The ENABLE_CONFIGURATION function can be used to to enable broker management of a configuration.

ENABLE_CONFIGURATION Function

DBMS_DG.ENABLE_CONFIGURATION (
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• If the configuration is disabled, connect to the database whose control file role is PRIMARY and call this function to enable the configuration.

Return Values

Error	Description
ORA-00000: normal, successful completion	The configuration was successfully enabled.
Other	The Data Guard broker was unable to enable the configuration and the return value will indicate the reason for this failure.

ENABLE_FS_FAILOVER

The ENABLE_FS_FAILOVER function can be used to enable fast-start failover. This enables the broker to fail over to a specifically-chosen standby database in the event of loss of the primary database, without requiring any manual steps..

ENABLE_FS_FAILOVER Function

DBMS_DG.ENABLE_FS_FAILOVER (
     observe_only    IN BOOLEAN DEFAULT FALSE,
     severity        OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
observe_only	A boolean value to indicate whether fast-start failover should be enabled in observer-only mode. A value of TRUE will cause this function to enable fast-start failover in observe-only mode. A value of FALSE will cause this function to enable fast-start failover without observe-only mode. In observe-only mode, the observer will print information about when a fast-failover would have been initiated without actually doing a failover to the target standby database.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The prerequisites described in Prerequisites for Enabling Fast-Start Failover must be met before you issue this command to enable fast-start failover.

• Issuing the ENABLE FAST_START FAILOVER command does not trigger a failover, it only allows the observer that is monitoring the configuration to initiate a fast-start failover if conditions warrant a failover.

• You can enable fast-start failover while connected to any database in the broker configuration.

• If you do not start the observer after you have enabled fast-start failover, the ORA-16819 warning is displayed for the primary and target standby databases.

• To enable fast-start failover for a broker configuration with multiple standby databases, the FastStartFailoverTarget configuration property on the primary database must specify one or more viable target standby databases. Both the primary database and the target standby databases must have:

  • Standby redo logs configured

  • Redo transport must be properly configured at both databases for the configured protection mode

Note: Oracle also recommends Flashback Database be enabled on both the primary and standby databases to allow for reinstatement of the old primary database after a failover.

• Once you have enabled fast-start failover, you must comply with the restrictions described in Restrictions When Fast-Start Failover is Enabled.

Return Values

Error	Description
ORA-00000: normal, successful completion	Fast-start failover was disabled according to the value specified by the force parameter.
Other	If the severity returned was ORA-16501, the Data Guard broker was unable to enable fast-start failover and the return value will indicate the reason. If the severity returned was ORA-16501, the Data Guard broker was able to enable fast-start failover and the return value will indicate information about how fast-start failover was enabled.

ENABLE_FS_FAILOVER_CONDITION

The ENABLE_FS_FAILOVER_CONDITION function can be used to specify additional conditions for which a fast-start failover should be performed.

ENABLE_FS_FAILOVER_CONDITION Function

DBMS_DG.ENABLE_FS_FAILOVER_CONDITION (
     condition            IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
condition	A fast-start failover condition to enable.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• This function can also be used to enable initiating a fast-start failover when there is an ORA-240 error.

Health Condition	Description
“Datafile Write Errors”	If fast-start failover is enabled and the Datafile Write Errors condition is specified, then a fast-start failover is initiated if write errors are encountered in any data files, including temp files, system data files, and undo files.
“Corrupted Controlfile”	Corrupted controlfile. This condition is enabled by default.
“Corrupted Dictionary”	Dictionary corruption of a critical database object. This condition is enabled by default.
“Inaccessible Logfile”	LGWR is unable to write to any member of a log group due to an I/O error.
“Stuck Archiver”	Archiver is unable to archive a redo log because device is full or unavailable.

Return Values

Error	Description
ORA-00000: normal, successful completion	Fast-start failover condition was enabled.
Other	The Data Guard broker was unable to enable the fast-start failover condition and the return value will indicate the reason for this failure.

FAILOVER

The FAILOVER function can be used to perform a database failover.

FAILOVER Function

DBMS_DG.FAILOVER (
     db_name              IN VARCHAR2,
     failover_type,       IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
db_name	The DB_UNIQUE_NAME initialization parameter value of the standby database to be fail over to.
failover_type	The type of failover to perform. Accepted keywords are: COMPLETE: complete failover where the target standby database applies all redo data it has received from the primary database before performing the failover operation. IMMEDIATE: the failover operation is performed immediately without first applying any unapplied redo data. This option will most likely result in a data loss failover operation
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• Always try to perform a complete failover first unless Redo Apply has stopped at the failover target due to an ORA-752 or ORA-600 [3020] error. If one of these errors has occurred, then before proceeding follow the guidelines in “Resolving ORA-752 or ORA-600 [3020] During Standby Recovery” in My Oracle Support Note 1265884.1 at https://support.oracle.com. An immediate failover should only be performed when a complete failover is unsuccessful or in the error case just noted.

• The specified standby database must be enabled before the primary database fails. However, an enabled standby database that was shut down can be a candidate for the failover operation. In this case, restart the standby database, then retry this call.

• Before you call this function, verify that you are connected to the standby database that will become the new primary database. If necessary, issue a CONNECT command to connect to the standby database to which you want to failover.

• If the broker configuration is operating in maximum protection mode, a manual failover operation will force the protection mode to be maximum performance. The redo transport service settings are unaffected. You need to restore the desired protection mode for the resulting configuration after the failover operation.

  Note: With fast-start failover, the broker preserves the protection mode that was in effect prior to the failover.

• If this function is called with the failover_type keyword of IMMEDIATE, no attempt is made to apply any unapplied redo that has been received. This option more likely results in lost application data even when standby redo log files are configured on the standby database. Additionally, any remaining standby databases in the configuration cannot function as such until they are reinstated or re-created. See Reenabling Disabled Databases After a Role Change for more information.Once you have enabled fast-start failover, you must comply with the restrictions described in Restrictions When Fast-Start Failover is Enabled.

• You can perform a manual failover or set up the broker to perform a fast-start failover. See the ENABLE FAST_START FAILOVER command for information about allowing the broker to automatically invoke failover, when conditions warrant a failover.

• If fast-start failover is enabled, you can perform a complete manual failover only to the fast-start failover target standby database and only if the fast-start failover target standby database is synchronized with, or within the lag limit of, the primary database, and only when the observer is started. You cannot perform an immediate manual failover when fast-start failover is enabled. If Flashback Database was enabled on the former (failed) primary database prior to the failover, the former primary database can be reinstated using the broker’s REINSTATE command. If failover was performed to a physical standby database, any other physical standby databases that were disabled by the failover can be reinstated if Flashback Database was enabled on the standby database and there are sufficient flashback logs available.

• The original primary database can only participate in the configuration as a standby database after it is reinstated or re-created. Caution: You should shut down the original primary database if it still has any active instances running prior to failing over.

Error	Description
ORA-00000: normal, successful completion	The failover completed successfully.
Other	The Data Guard broker was unable to complete the failover operation and the return value will indicate the reason for this failure.

GET_CONFIGURATION_PROPERTY

The GET_CONFIGURATION_PROPERTY function can be used to get the value of a configuration property.

GET_CONFIGURATION_PROPERTY Function

DBMS_DG.GET_CONFIGURATION_PROPERTY (
     property_name        IN VARCHAR2,
     value                OUT VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
property_name	The name of the configuration property whose value is to be fetched.
value	The value of the specified configuration property is returned in this output parameter.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The value of the property was successfully fetched.
Other	The Data Guard broker was unable to fetch the configuration property value and the return value will indicate the reason for this failure.

GET_CONFIGURATION_TAG

The GET_CONFIGURATION_TAG function retrieves the value of a configuration tag.

GET_CONFIGURATION_TAG Function

DBMS_DG.GET_CONFIGURATION_TAG (
     config_name          IN VARCHAR2,
     tag_name             IN VARCHAR2,
     value                OUT VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
tag_name	The name of a tag.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
value	The value of the tag.
severity	The severity associated with the status returned by this function.

GET_MEMBER_TAG

The GET_MEMBER_TAG function retrieves the value of a member tag.

GET_MEMBER_TAG Function

DBMS_DG.GET_MEMBER_TAG (
     config_name          IN VARCHAR2,
     member_name          IN VARCHAR2,
     tag_name             IN VARCHAR2,
     value                OUT VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
member_name	The name of a member configuration file.
tag_name	The name of a tag.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
value	The value of the tag.
severity	The severity associated with the status returned by this function.

GET_PROPERTY

The GET_PROPERTY function can be used to get the value of a member property.

GET_PROPERTY Function

DBMS_DG.GET_PROPERTY (
     member_name          IN VARCHAR2,
     property_name        IN VARCHAR2,
     value                OUT CLOB,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the member to be whose property value is to be fetched.
property_name	The name of the configuration property whose value is to be fetched.
value	The value of the specified configuration property is returned in this output parameter.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Error	Description
ORA-00000: normal, successful completion	The value of the property was successfully fetched.
Other	The Data Guard broker was unable to fetch the property value and the return value will indicate the reason for this failure.

HEALTH_CHECK

The HEALTH_CHECK function can be used to get the broker to evaluate the health of all configuration members..

HEALTH_CHECK Function

DBMS_DG.HEALTH_CHECK
RETURN BINARY_INTEGER;

Parameters

None

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The health check was successfully initiated.
Other	The Data Guard broker was unable to perform the health check and the return value will indicate the reason for this failure.

INITIATE_FS_FAILOVER Procedure

Use this procedure to specify a condition string that, when encountered by an application, allows the application to request that a fast-start failover be invoked.

Syntax

DBMS_DG.INITIATE_FS_FAILOVER (
     condstr          IN VARCHAR2)
RETURN BINARY_INTEGER;

Parameters

Table 2 INITIATE_FS_FAILOVER Procedure Parameters

Parameter	Description
condstr	Specifies the condition string for which a fast-start failover should be requested. If no condition string argument is supplied, the default string of “Application Failover Requested” will be logged in the broker log file and in the database alert log of the database on which the procedure was called.

Usage Notes

• This procedure returns a binary integer.

• Query the V$FS_FAILOVER_STATS view to see the time of the last fast-start failover and the reason it was performed.

• This procedure can only be called while connected to a primary database or a fast-start failover standby database.

There are conditions detectable by applications running outside of the Oracle database that may warrant the Oracle Data Guard broker to perform a fast-start failover. Because the range of possible conditions is virtually unlimited, it is left to the applications to determine which conditions warrant a fast-start failover.

When such conditions occur, the application calls the DBMS_DG.INITIATE_FS_FAILOVER procedure to alert either the primary or fast-start failover target standby database that the application wants a fast-start failover to occur immediately. The database on which the procedure was called then notifies the observer, which immediately initiates a fast-start failover as long as the standby database is in a valid fast-start failover state (“observed” and either “synchronized” or “within lag”) to accept a failover.If the configuration is not in a valid fast-start failover state, the INITIATE_FS_FAILOVER subprogram returns an ORA error message (it will not signal an exception) to inform the calling application that a fast-start failover could not be performed.

Errors

Table 3 INITIATE_FS_FAILOVER Procedure Errors

Error	Description
ORA-00000: normal, successful completion	The request to initiate a fast-start failover has been posted to the observer.
ORA-16646: fast-start failover is disabled	Either a broker configuration does not exist or fast-start failover has not been enabled.
ORA-16666: unable to initiate fast-start failover on a bystander standby database	DBMS_DG.INITIATE_FS_FAILOVER was invoked on a bystander standby database. That is, it was not invoked on the primary or on the fast-start failover target standby database.
ORA-16817: unsynchronized fast-start failover configuration	DBMS_DG.INITIATE_FS_FAILOVER was invoked in a maximum available fast-start failover configuration when the configuration was not synchronized.
ORA-16819: fast-start failover observer not started	DBMS_DG.INITIATE_FS_FAILOVER was invoked but an observer had not yet been started.
ORA-16820: fast-start failover observer is no longer observing this database	DBMS_DG.INITIATE_FS_FAILOVER was invoked but the configuration detects that the observer may not be running.
ORA-16829: lagging fast-start failover configuration	DBMS_DG.INITIATE_FS_FAILOVER was invoked in a maximum performance fast-start failover configuration when the configuration was not in the user-specified redo lag limit.

Example

In this example, the program attempts to initiate a fast-start failover when fast-start failover is disabled. To use this example, connect as user SYS with SYDDBA privileges.

set serveroutput on

declare
status integer;

begin
status := dbms_dg.initiate_fs_failover(''Failover Requested'');

dbms_output.put_line(''Fast-Start Failover is disabled: Expected status = ORA-16646'');
dbms_output.put_line(''                  Actual Status = ORA-'' || status);

end;
/
exit;

REINSTATE

The REINSTATE function can be used to reinstate a database after a failover operation.

REINSTATE Function

DBMS_DG.REINSTATE (
     db_name              IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
db_name	The DB_UNIQUE_NAME initialization parameter value of the database to be reinstated.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• If the conditions for reinstatement described in Reinstating the Former Primary Database in the Broker Configuration are not satisfied, the reinstatement will fail with an appropriate error status and the specified database will remain disabled.

• If the database name specified is that of the old primary and fast-start failover is enabled, the old primary database will be reinstated as a standby to the new primary, and the fast-start failover environment will be updated to reflect the availability of the new standby database. It will accept redo data from the new primary database and be the target of a fast-start failover should the new primary database fail. Reinstatement occurs automatically if the observer is running unless the FastStartFailoverAutoReinstate configuration property is set to FALSE.

• This function does not require that fast-start failover be enabled. It can be used to reinstate an old primary database after a complete manual failover has been performed. It can also be used to reinstate a bystander standby database that had been disabled after either a complete or immediate failover.

• Call this function while connected to any database in the broker configuration, except the database that is to be reinstated.

Return Values

Error	Description
ORA-00000: normal, successful completion	The database was successfully reinstated.
ORA-16540: invalid argument	The name specified for the database was not a valid DB_UNIQUE_NAME value.
ORA-16732: Oracle Clusterware is restarting the database instance	Oracle Clusterware is restarting the database to the mode required by the broker. Once the database has been restarted, retry this function call.
ORA-16897: start database to mount mode	Reinstatement was not performed because the database was not running in mount mode. Restart the database to mount mode and retry this function call.
ORA-16899: Operation requires a connection to the primary database.	A connection to the primary database is required to call this function.
Other	The Data Guard broker was unable to reinstate the specified database and the return value will indicate the reason for this failure.

REMOVE

The REMOVE function can be used to remove a member the Data Guard broker configuration.

REMOVE Function

DBMS_DG.REMOVE (
     member_name          IN VARCHAR2,
     preserve_destination IN BOOLEAN DEFAULT FALSE,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the database to be reinstated.
preserve_destination	A boolean value to indicate whether the log_archive_dest initialization parameter setting should be preserved or clear when removing member from the configuration. A value of TRUE indicates that the parameter setting will not be cleared. A value of FALSE indicates the parameter setting will be cleared.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• An error is returned if you specify the name of the primary database in the broker configuration.

• By default, this function will cause all references to the specified member to be removed from all redo transport initialization parameters at each member of the configuration. To preserve these settings, specify TRUE for the preserve_destination parameter.

• This function cannot be called if fast-start failover is enabled and database-name specifies the name of the target standby database.

Return Values

Error	Description
ORA-00000: normal, successful completion	The member was successfully removed.
Other	The Data Guard broker was unable to remove the member from the configuration and the return value will indicate the reason for this failure.

REMOVE_CONFIGURATION

The REMOVE_CONFIGURATION function can be used to remove the Data Guard broker configuration.

REMOVE_CONFIGURATION Function

DBMS_DG.REMOVE_CONFIGURATION (
     preserve_destinations IN BOOLEAN DEFAULT FALSE,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
preserve_destination	A boolean value to indicate whether the log_archive_dest initialization parameter setting should be preserved or clear when removing member from the configuration. A value of TRUE indicates that the parameter setting will not be cleared. A value of FALSE indicates the parameter setting will be cleared.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• When you remove a broker configuration, management of all the members associated with that configuration is disabled.

• By default, this function causes the corresponding broker settings of the LOG_ARCHIVE_DEST_n initialization parameter on the primary database and the LOG_ARCHIVE_CONFIG initialization parameters on all members of the configuration to be removed. To preserve these settings, specify a value of true for the preserve_destinations parameter.

• This command does not remove or affect the actual primary or standby database instances, databases, far sync instances, data files, control files, initialization parameter files, server parameter files, or log files of the underlying Oracle Data Guard configuration.

• You cannot remove the configuration when fast-start failover is enabled.

Return Values

Error	Description
ORA-00000: normal, successful completion	The configuration was successfully removed.
Other	The Data Guard broker was unable to remove the configuration and the return value will indicate the reason for this failure.

REMOVE_CONFIGURATION_TAG

The REMOVE_CONFIGURATION_TAG function removes a configuration tag.

REMOVE_CONFIGURATION_TAG Function

DBMS_DG.REMOVE_CONFIGURATION_TAG (
     config_name          IN VARCHAR2,
     tag_name             IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
tag_name	The name of a tag.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
severity	The severity associated with the status returned by this function.

REMOVE_CONFIGURATION_TAG_ALL

The REMOVE_CONFIGURATION_TAG_ALL function removes all configuration tags.

REMOVE_CONFIGURATION_TAG_ALL Function

DBMS_DG.REMOVE_CONFIGURATION_TAG_ALL (
     config_name          IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
severity	The severity associated with the status returned by this function.

REMOVE_INSTANCE

The REMOVE_INSTANCE function can be used to remove an instance from a member the Data Guard broker configuration.

REMOVE_INSTANCE Function

DBMS_DG.REMOVE_INSTANCE (
     member_name           IN VARCHAR2,
     instance_name         IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the member whose instance is to be removed.
instance_name	The name of the instance (SID) that you want to remove the broker configuration.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The broker automatically adds started instances to the broker configuration. However, the broker does not automatically remove instances from the database. This function can be used to manually remove any instance that no longer exists from the configuration.

• This function returns an error for an instance that is currently active in the broker configuration.

• This function returns an error if this is the only instance currently associated with a database for far sync instance.

Return Values

Error	Description
ORA-00000: normal, successful completion	The configuration was successfully removed.
Other	The Data Guard broker was unable to remove the configuration and the return value will indicate the reason for this failure.

REMOVE_MEMBER_TAG

The REMOVE_MEMBER_TAG function removes a member tag.

REMOVE_MEMBER_TAG Function

DBMS_DG.REMOVE_MEMBER_TAG(
     config_name          IN VARCHAR2,
     member_name          IN VARCHAR2,
     tag_name             IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
member_name	The name of a member configuration file.
tag_name	The name of a tag.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
severity	The severity associated with the status returned by this function.

REMOVE_MEMBER_TAG_ALL

The REMOVE_MEMBER_TAG_ALL function removes all member tags.

REMOVE_MEMBER_TAG_ALL Function

DBMS_DG.REMOVE_MEMBER_TAG_ALL(
     config_name          IN VARCHAR2,
     member_name          IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
member_name	The name of a member configuration file.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
severity	The severity associated with the status returned by this function.

RESET_CONFIGURATION_PROPERTY

The RESET_CONFIGURATION_PROPERTY function can be used to reset a configuration property to its default value.

RESET_CONFIGURATION_PROPERTY Function

DBMS_DG.RESET_CONFIGURATION_PROPERTY (
     property_name         IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
property_name	The name of the configuration property whose value is to be reset to its default value.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The configuration was successfully removed.
Other	The Data Guard broker was unable to remove the configuration and the return value will indicate the reason for this failure.

RESET_PROPERTY

The RESET_PROPERTY function can be used to reset a member configurable property to its default value.

RESET_PROPERTY Function

DBMS_DG.RESET_PROPERTY (
     member_name           IN VARCHAR2,
     property_name         IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the member whose configurable property value is to be reset to its default value.
property_name	The name of the configuration property whose value is to be reset to its default value.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The specified configurable property’s value was successfully reset to its default value.
Other	The Data Guard broker was unable to reset the specified configurable property to its default value and the return value will indicate the reason for this failure.

SET_CONFIGURATION_PROPERTY

The SET_CONFIGURATION_PROPERTY function can be used to set a value for a configuration property.

SET_CONFIGURATION_PROPERTY Function

DBMS_DG.SET_CONFIGURATION_PROPERTY (
     property_name IN VARCHAR2,
     value         IN VARCHAR2,
     severity      OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
property_name	The name of the configuration property whose value is to be set.
value	The value to set the specified configuration property to.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The specified configurable property’s value was successfully reset to its default value.
Other	The Data Guard broker was unable to reset the specified configurable property to its default value and the return value will indicate the reason for this failure.

SET_CONFIGURATION_TAG

The SET_CONFIGURATION_TAG function sets a value of a configuration tag. If the tag doesn’t exist, a new tag is created.

SET_CONFIGURATION_TAG Function

DBMS_DG.SET_CONFIGURATION_TAG (
     config_name          IN VARCHAR2,
     tag_name             IN VARCHAR2,
     value                IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
tag_name	The name of a tag.
value	The value for the tag.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
severity	The severity associated with the status returned by this function.

SET_MEMBER_TAG

The SET_MEMBER_TAG function sets a value of a member tag. If the key doesn’t exist, a new key is created.

SET_MEMBER_TAG Function

DBMS_DG.SET_MEMBER_TAG (
     config_name          IN VARCHAR2,
     member_name          IN VARCHAR2,
     tag_name             IN VARCHAR2,
     value                IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
config_name	The name of a configuration file. NULL for local configuration.
member_name	The name of a member.
tag_name	The name of a tag.
value	The value for the tag.

Usage Notes

• This function returns a binary integer, an Oracle error number indicating whether the operation was successful.

Return Values

Error	Description
severity	The severity associated with the status returned by this function.

SET_PROPERTY

The SET_CONFIGURATION_PROPERTY function can be used to set a value for a member configurable property.

SET_PROPERTY Function

DBMS_DG.SET_PROPERTY (
     member_name           IN VARCHAR2,
     property_name         IN VARCHAR2,
     value                 IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the member whose configurable property value is to be set.
property_name	The name of the configurable property whose value is to be set.
value	The value to set the specified configurable property to.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The specified configurable property’s value was successfully reset to its default value.
Other	The Data Guard broker was unable to reset the specified configurable property to its default value and the return value will indicate the reason for this failure.

SET_PROTECTION_MODE

The SET_PROTECTION_MODE function can be used to set the configuration protection mode.

SET_PROTECTION_MODE Function

DBMS_DG.SET_PROTECTION_MODE (
     protection_mode IN VARCHAR2,
     severity        OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
protection_mode	A character string containing the protection mode to be set. Valid values include: MAXPERFORMANCE MAXAVAILABILITY MAXPROTECTION
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• Before you use the this function to set the protection mode, ensure that at least one standby is configured to receive redo via SYNC or FASTSYNC mode if it receives redo directly from the primary. If the standby receives redo via a far sync instance, the far sync instance must be configured to receive redo via SYNC or FASTSYNC mode and the standby must be configured to receive redo via ASYNC mode.

• The following table shows the configuration protection modes and the minimum corresponding settings for redo transport services:

  Protection Mode	Redo Transport	Standby Redo Log FIles Needed?	Useable with Fast-Start Failover?
  MAXPROTECTION	SYNC	Yes	Yes
  MAXAVAILABILITY	SYNC or FASTSYNC	Yes	Yes
  MAXPERFORMANCE	ASYNC	Yes	Yes

  The default protection mode for the configuration is MAXPERFORMANCE.

• This function cannot be called if fast-start failover is enabled.

• Upgrading from MAXPERFORMANCE to MAXPROTECTION is not allowed. You must first go to MAXAVAILABILITY and then to MAXPROTECTION.

Return Values

Error	Description
ORA-00000: normal, successful completion	The configuration protection mode was successfully changed.
Other	The Data Guard broker was unable to change the protection mode and the return value will indicate the reason for this failure.

SET_STATE_APPLY_OFF

The SET_STATE_APPLY_OFF function can be used to set the apply state to off for a logical or physical standby database.

SET_STATE_APPLY_OFF Function

DBMS_DG.SET_STATE_APPLY_OFF (
     member_name           IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the standby database whose apply state should be set to OFF.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The apply state for a snapshot standby database cannot be set to OFF.

• All instances of an Oracle RAC database are affected by this database state change.

Error	Description
ORA-00000: normal, successful completion	The apply state for the specified standby database was successfully set to OFF.
Other	The Data Guard broker was unable to set the apply state to OFF for the specified standby database and the return value will indicate the reason for this failure.

SET_STATE_APPLY_ON

The SET_STATE_APPLY_ON function can be used to set the apply state to on for a logical or physical standby database.

SET_STATE_APPLY_ON Function

DBMS_DG.SET_STATE_APPLY_ON (
     member_name           IN VARCHAR2,
     apply_instance        IN VARCHAR2 DEFAULT NULL,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the standby database whose apply state should be set to ON.
apply_instance	A character string containing the SID of the instance you want to become the apply instance if this is an Oracle RAC standby database.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The apply state for a snapshot standby database cannot be set to ON.

• If the apply_instance argument is specified, that instance will become the apply instance.

• All instances of an Oracle RAC database are affected by this database state change.

Return Values

Error	Description
ORA-00000: normal, successful completion	The apply state for the specified standby database was successfully set to ON.
Other	The Data Guard broker was unable to set the apply state to ON for the specified standby database and the return value will indicate the reason for this failure.

SET_STATE_TRANSPORT_OFF

The SET_STATE_TRANSPORT_OFF function can be used to set the redo transport state to off for a primary database.

SET_STATE_TRANSPORT_OFF Function

DBMS_DG.SET_STATE_TRANSPORT_OFF (
     member_name           IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the primary database.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The transport state can only be set to off for a primary database.

• All instances of an Oracle RAC database are affected by this database state change.

Return Values

Error	Description
ORA-00000: normal, successful completion	The transport state for the primary database was successfully set to OFF.
Other	The Data Guard broker was unable to set the transport state to OFF and the return value will indicate the reason for this failure.

SET_STATE_TRANSPORT_ON

The SET_STATE_TRANSPORT_ON function can be used to set the redo transport state to on for a primary database.

SET_STATE_TRANSPORT_ON Function

DBMS_DG.SET_STATE_TRANSPORT_ON (
     member_name           IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
member_name	The DB_UNIQUE_NAME initialization parameter value of the primary database.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• The transport state can only be set to ON for a primary database.

• All instances of an Oracle RAC database are affected by this database state change.

Return Values

Error	Description
ORA-00000: normal, successful completion	The transport state for the primary database was successfully set to ON.
Other	The Data Guard broker was unable to set the transport state to ON and the return value will indicate the reason for this failure.

STOP_OBSERVER

The STOP_OBSERVER function can be used to stop fast-start failover observers in a Data Guard broker configuration.

STOP_OBSERVER Function

DBMS_DG.STOP_OBSERVER (
     ob_name               IN VARCHAR2,
     severity              OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
ob_name	A character string containing the name of the observer to be stopped. Valid values are: An observer name. See V$FS_FAILOVER_OBSERVERS for a list of all registered observers. NULL or the empty string if only one observer is registered. ALL to stop all registered observers.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• You can call this function while connected to any database in the broker configuration.

• This command does not disable fast-start failover, but a fast-start failover cannot be initiated in the absence of an observer.

• Fast-start failover does not need to be enabled when you issue this command.

• If fast-start failover is enabled when you call this function, then the primary and standby databases must be connected and communicating with each other. Otherwise the following error is returned:

  ORA-16636 fast-start failover target standby in error state, cannot stop observer

  If connectivity does not exist between the primary and standby databases, you can issue the disable fast-start failover with the FORCE option on the primary database and then call this function. Note that disabling fast-start failover with the FORCE option on a primary database that is disconnected from the observer and the target standby database does not prevent the observer from initiating a fast-start failover to the target standby database.

• If fast-start failover is not enabled when you issue call this function, then only the primary database must be running when you stop the observer.

• The observer does not stop immediately when you call this function. The observer does not discover it has been stopped until the next time the observer contacts the broker. As soon as you have called this function successfully, you can start an observer again on any computer. You can start a new observer right away, even if the old observer has not yet discovered it was stopped. Any attempt to restart the old observer will fail, because a new observer has been started for the broker configuration.

• This function will return an error if a switch to a new fast-start failover target or new master observer is in progress.

• This function will return an error if there are two or more registered observers and you attempt to stop only the master.

Return Values

Error	Description
ORA-00000: normal, successful completion	The specified observer was successfully stopped.
Other	The Data Guard broker was unable to stop the specified observer and the return value will indicate the reason for this failure.

SWITCHOVER

The SWITCHOVER function can be used to perform a database switchover.

SWITCHOVER Function

DBMS_DG.SWITCHOVER (
     db_name              IN VARCHAR2,
     severity             OUT BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
db_name	The DB_UNIQUE_NAME initialization parameter value of the standby database to switch over to.
severity	The severity associated with the status returned by this function. Severity will be one of the following Oracle error numbers: ORA-0: normal, successful completion ORA-16501: The Oracle Data Guard broker operation failed. ORA-16502: The Oracle Data Guard broker operation succeeded with warnings.

Usage Notes

• This function returns a binary integer.

• If fast-start failover is enabled, you may switch over only to the fast-start failover target standby database.

• The broker verifies that the primary and standby databases are in the following states before starting the switchover:

  • The primary database must be enabled and in the TRANSPORT-ON state so redo transport services are started.

  • The standby database must be enabled and in the APPLY-ON state, with log apply services started.

• The broker allows the switchover to proceed as long as there are no redo transport services errors for the standby database that you selected to participate in the switchover. However, errors occurring for any other bystander standby database will not prevent the switchover from proceeding.

• Switchover to a logical standby database is not allowed when the configuration is operating in maximum protection mode.

• If the broker configuration is operating in either maximum protection mode or maximum availability mode, the switchover maintains the protection mode even after the operation (described in Before You Perform a Switchover Operation). The switchover will not be allowed if the mode cannot be maintained because the target standby database of the switchover was the only standby that satisfied the protection mode requirement.

• If the standby database that is assuming the primary role is a physical standby database, then the old primary database will be restarted after the switchover completes. If the standby database is a logical standby database, then neither the primary database nor the logical standby database is restarted.

• If the standby database that is assuming the primary role is a physical standby database, then the original primary becomes a physical standby database.

• If the standby database that is assuming the primary role is a logical standby database, then the original primary becomes a logical standby database.

• If an Oracle RAC primary database is becoming a physical standby database, all but one instance of the primary database will be shut down before performing the switchover. See Switchover for details.

• You cannot switchover to a snapshot standby database.

• If the standby database that is assuming the primary role is a logical standby database and there are physical standby databases in the configuration, after the switchover, the physical standby databases will be disabled.

  Caution: For this reason, Oracle generally recommends that you specify your physical standby database for switchover instead of your logical standby database. If you must switch over to your logical standby database, see Reenabling Disabled Databases After a Role Change to re-create your physical standby database.

  If you intend to switch back to the original primary database relatively soon, you may allow the physical and snapshot standbys to remain disabled. Once you have completed the switchover back to the original primary, you may then reenable the physical and snapshot standby databases since they are still viable standbys for the original primary database.

Return Values

Error	Description
ORA-00000: normal, successful completion	The switchover completed successfully.
ORA-16540: invalid argument	The name specified for the database was not a valid DB_UNIQUE_NAME value.
ORA-16600: not connected to target standby database	This function cannot be called when connected to the primary database. Call this function while connected to the target standby database.
ORA-16732: Oracle Clusterware is restarting the database instance	Oracle Clusterware is restarting the database to the mode required by the broker. Once the database has been restarted, retry this function call.
ORA-16897: start database to mount mode	The switchover was completed successfully and the client must restart the old primary database to the mount mode.
ORA-16897: start database to open mode	The switchover was completed successfully and the client must restart the old primary database to the open mode.
Other	The Data Guard broker unable to complete the switchover and the return value will indicate the reason for this failure.

WAIT

The WAIT function can be used to wait for various Data Guard broker events to occur.

WAIT Function

DBMS_DG.WAIT (
     wait_event            IN BINARY_INTEGER
     wait_time             IN BINARY_INTEGER)
RETURN BINARY_INTEGER;

Parameters

Parameter	Description
wait_event	A Data Guard broker wait event. This can be one of: DBMS_DG.WAIT_START_BROKER: Wait for Data Guard broker to start and finish initialization. Specifying this wait event will also cause the DG_BROKER_START initialization parameter to be set to TRUE. DBMS_DG.WAIT_STOP_BROKER: Wait for Data Guard broker to stop. Specifying this wait event will also cause the DG_BROKER_START initialization parameter to be set to FALSE.
wait_time	The number of seconds to wait for the specified wait event to occur.

Usage Notes

• This function returns a binary integer.

Return Values

Error	Description
ORA-00000: normal, successful completion	The event for which to wait on occurred within the number of seconds specified by the wait_time parameter.
ORA-16509: request timed out	The event for which to wait on did not occur within the number of seconds specified by the wait_time parameter.
Other	The Data Guard broker unable to wait for the specified wait event and the return value will indicate the reason for this failure.