Oracle DBMS_DRS
Version 18.3.0.1

General Information
Library Note Morgan's Library Page Header
Coming to OpenWorld 2018? Be sure to visit the TidalScale booth in Moscone South and learn how to solve performance problems and lower costs with Software Defined Servers. Before you visit the booth, or if you can't make it this year, check out TidalScale at www.tidalscale.com. Be sure to click on the Solutions link and look through the Oracle resources.
Purpose This package contains procedures used in the DR Server (Hot Standby). There are two forms of each major function; one is a blocking procedure, which does not return until the command is completed. The other is a non-blocking function which returns with a request identifier which may be used to return the result of the command.
AUTHID DEFINER
Constants
Name Data Type Value
Pre-Defined Wait Events
WAIT_START_DMON PLS_INTEGER 1
WAIT_STOP_DMON PLS_INTEGER 2
WAIT_BOOT PLS_INTEGER 3
WAIT_BOOT_ENABLED PLS_INTEGER 4
WAIT_PREDEFINED_MAX PLS_INTEGER 4
Flag Based Wait Events
WAIT_RFMP_FLAGS PLS_INTEGER 100
WAIT_BROKER_STATE_FLAGS PLS_INTEGER 101
 Wait For Flags To Be Set Or Cleared
WAIT_FLAGS_CLR PLS_INTEGER 0
WAIT_FLAGS_SET PLS_INTEGER 1
Status Values Returned By DBMS_DRS.WAIT
RFC_DRSF_STATUS_TOUT NUMBER 16509
RFC_DRSF_STATUS_NODRC NUMBER 16532
RFC_DRSF_STATUS_BADARG NUMBER 16540
RFC_DRSF_STATUS_ILLPRMYOP NUMBER 16585
RFC_DRSF_STATUS_NOTMEMBER NUMBER 16596
Dependencies
DBMS_DG DBMS_GSM_FIXED  
Documented No
Exceptions
Error Code Reason
ORA-16508 bad_request
First Available 9.0.1
Security Model Owned by SYS with EXECUTE granted to the SYSDG and OEM_MONITOR roles
Source $ORACLE_HOME/rdbms/admin/dbmsdrs.sql
Subprograms
 
 
ADD_DATABASE (new 18.1)
Add a standby database to a broker configuration. database_ci is the connection identifier dbms_drs.add_database(
database_name IN VARCHAR2,
database_ci   IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
ADD_FAR_SYNC (new 18.1)
Add a far sync instance to a broker configuration. far_sync_ci is the connection identifier dbms_drs.add_far_sync(
far_sync_name IN VARCHAR2,
far_sync_ci   IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
CANCEL_REQUEST
Cancel Request (blocking) dbms_drs.cancel_request(rid IN INTEGER);
See Demos Below
 
CHECK_CONNECT (new 18.1)
Check network connectivity to the specified member dbms_drs.check_connect(
member_name   IN VARCHAR2,
instance_name IN VARCHAR2);
exec dbms_drs.check_connect('ORABASE_DR', 'ORABASE1');
 
CREATE_CONFIGURATION (new 18.1)
Creates a broker configuration. The primary database will be automatically added to the configuration by this procedure. Must be called on a primary database. dbms_drs.create_configuration(
config_name IN VARCHAR2,
primary_ci  IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
DELETE_REQUEST
Delete Request (blocking) dbms_drs.delete_request(rid IN INTEGER);
See Demos Below
 
DG_BROKER_INFO
Returns Data Guard Broker Information dbms_drs.dg_broker_info(info_name IN VARCHAR2) RETURN VARCHAR2;
SELECT dbms_drs.dg_broker_info('DMONREADY')
FROM dual;

SELECT dbms_drs.dg_broker_info('VERSION')
FROM dual;
 
DISABLE_FS_FAILOVER (new 18.1)
Disables Fast Start Failover dbms_drs.disable_fs_failover(force IN BOOLEAN DEFAULT FALSE)
RETURN BINARY_INTEGER;
SELECT dbms_drs.disable_fs_failover(TRUE)
FROM dual;
 
DO_CONTROL
Control blocking API
Obsolete: Use DO_CONTROL_RAW

Overload 1
dbms_drs.do_control(
indoc      IN     VARCHAR2,
outdoc        OUT VARCHAR2,
request_id IN OUT INTEGER,
piece      IN     INTEGER,
context    IN     VARCHAR2 DEFAULT NULL);
See Demos Below
Obsolete: For test use only
Overload 2
dbms_drs.do_control(indoc IN VARCHAR2) RETURN INTEGER;
See Demos Below
 
DO_CONTROL_RAW
Control blocking API designed for solving NLS problems. Is a blocking call that sends a DG Broker control request.

Overload 1
dbms_drs.do_control_raw(
indoc      IN     RAW,
outdoc        OUT RAW,
request_id IN OUT INTEGER,
piece      IN     INTEGER,
context    IN     VARCHAR2 DEFAULT NULL,
client_id  IN     INTEGER  DEFAULT 0);
TBD
Overload 2 dbms_drs.do_control_raw(indoc IN RAW) RETURN INTEGER;
TBD
 
DO_OBSERVE (new 18.1)
Observer operation API - observer's operation to control FSFO since 12.2. (replaces Ping, ReadyToFailover, and StateChangeRecorded) dbms_drs.do_observe (
indoc  IN  RAW,
outdoc OUT RAW);
TBD
 
DUMP_BROKER (new 18.1)
Dumps critical internal data of the broker process to a file dbms_drs.dump_broker(
dump_type IN  BINARY_INTEGER,
oStatus   OUT VARCHAR2);
DECLARE
 outVal VARCHAR2(60);
BEGIN
  dbms_drs.dump_broker('RFRDM_DO_CURRENT', outVal);
  dbms_output.put_line(outVal);
END;
/
DUMP_META
DUMP data guard broker metadata file content into a readable text file dbms_drs.dump_meta(
options  IN INTEGER,
metafile IN VARCHAR2,
dumpfile IN VARCHAR2);
DECLARE
 outVal VARCHAR2(120);
BEGIN
  dbms_drs.dump_meta(1, NULL, '/home/oracle/dump_meta.log');
END;
/
 
DUMP_OBSERVER (new 18.1)
Dumps critical internal data of client-side observer process to a file dbms_drs.dump_observer(
all_ob  IN  BOOLEAN,
ob_name IN  VARCHAR2,
oStatus OUT VARCHAR2);
DECLARE
 outVal VARCHAR2(60);
BEGIN
  dbms_drs.dump_observer(TRUE, 'ORABASE_OBS1', outVal);
  dbms_output.put_line(outVal);
END;
/
 
ENABLE_CONFIGURATION (new 18.1)
Enables broker management of a Data Guard configuration. It must be called on the primary database. Return 0 means enable was successful, otherwise returns an error number. dbms_drs.enable_configuration RETURN BINARY_INTEGER;
SELECT dbms_drs.enable_configuration
FROM dual;
 
ENABLE_DATABASE (new 18.1)
Used to enable broker management of a database within the broker configuration. It must be called on the primary database. dbms_drs.enable_database(database_name in VARCHAR2)
RETURN BINARY_INTEGER;
SELECT dbms_drs.enable_database('ORABASE')
FROM dual;
 
ENABLE_FAR_SYNC (new 18.1)
Enable broker management of a far sync instance within the broker configuration. It must be called on the primary database. dbms_drs.enable_far_sync(far_sync_name in VARCHAR2)
RETURN BINARY_INTEGER;
SELECT dbms_drs.enable_database('ORABASE_FS')
FROM dual;
 
ENABLE_FS_FAILOVER (new 18.1)
Used to enable fast-start failover dbms_drs.enable_fs_failover RETURN BINARY_INTEGER;
SELECT dbms_drs.enable_fs_failover
FROM dual;
 
FS_FAILOVER_FOR_HC_COND
Undocumented
Overload 1
dbms_drs.fs_failover_for_hc_cond(
hc_cond IN  BINARY_INTEGER,
status  OUT BINARY_INTEGER);
TBD
Overload 2 dbms_drs.fs_failover_for_hc_cond(hc_cond IN BINARY_INTEGER)
RETURN BOOLEAN;
TBD
 
GET_PROPERTY
Get a named property. This function is equivalent to using getid to return the object id, followed by a <do_monitor><property> request. dbms_drs.get_property(
site_name     IN VARCHAR2,
resource_name IN VARCHAR2,
property_name IN VARCHAR2)
RETURN VARCHAR2;
TBD
 
GET_PROPERTY_OBJ
Get a named property. Equivalent to a <DO_MONITOR><PROPERTY> request and parsing the resulting string. dbms_drs.get_property_obj(
object_id     IN INTEGER,
property_name IN VARCHAR2)
RETURN VARCHAR2;
TBD
 
GET_RESPONSE
Get Result (non-blocking) - OBSOLETE, for test use only dbms_drs.get_response(
rid   IN INTEGER,
piece IN INTEGER)
RETURN VARCHAR2;
See Demos Below
 
GET_RESPONSE_RAW
Returns the result of a non-blocking command. If the command hasn't finished or the piece is beyond the end of the document returns NULL. dbms_drs.get_response_raw(
rid   IN INTEGER,
piece IN INTEGER)
RETURN RAW;
TBD
 
INITIATE_FS_FAILOVER
Initiate Fast Start Failover dbms_drs.initiate_fs_failover(
condstr IN  VARCHAR2,
status  OUT BINARY_INTEGER);
TBD
 
PING
The old ping procedure that was used in 12.1.0.1 and prior to 11.2.0.4

Overload 1
dbms_drs.ping(
iObid    IN  BINARY_INTEGER,
iVersion IN  BINARY_INTEGER,
iFlags   IN  BINARY_INTEGER,
iMiv     IN  BINARY_INTEGER,
oVersion OUT BINARY_INTEGER,
oFlags   OUT BINARY_INTEGER,
oFoCond  OUT VARCHAR2,
oStatus  OUT BINARY_INTEGER);
TBD
Ping procedure since 12.1.0.2 (and 11.2.0.4) and now obsolete as of 12.2

Overload 2k
dbms_drs.ping(
iObid     IN  BINARY_INTEGER,
iVersion  IN  BINARY_INTEGER,
iFlags    IN  BINARY_INTEGER,
iMiv      IN  BINARY_INTEGER,
iWaitStat IN  BINARY_INTEGER,
oVersion  OUT BINARY_INTEGER,
oFlags    OUT BINARY_INTEGER,
oFoCond   OUT VARCHAR2,
oStatus   OUT BINARY_INTEGER);
TBD
 
READYTOFAILOVER
Undocumented dbms_drs.ReadyToFailover(
iObid    IN  BINARY_INTEGER,
iVersion IN  BINARY_INTEGER,
iFlags   IN  BINARY_INTEGER,
iMiv     IN  BINARY_INTEGER,
iFoCond  IN  VARCHAR2,
oStatus  OUT BINARY_INTEGER);
TBD
 
REMOVE_CONFIGURATION (new 18.1)
Removes a broker configuration. It must be called on the primary database. dbms_drs.remove_configuration(preserve_destinations IN BOOLEAN DEFAULT FALSE)
RETURN BINARY_INTEGER;
SELECT dbms_drs.remove_configuration(FALSE)
FROM dual;
 
REMOVE_DATABASE (new 18.1)
Used to remove a database from the broker configuration. It must be called on the primary database. dbms_drs.emove_database(
database_name        IN VARCHAR2,
preserve_destination IN BOOLEAN DEFAULT FALSE)
RETURN BINARY_INTEGER;
SELECT dbms_drs.remove_database('ORABASE2', TRUE)
FROM dual;
 
REMOVE_FAR_SYNC (new 18.1)
Removes a far sync instance from the broker configuration. It must be called on the primary database. dbms_drs.remove_far_sync(
far_sync_name        IN VARCHAR2,
preserve_destination IN BOOLEAN DEFAULT FALSE)
RETURN BINARY_INTEGER;
SELECT dbms_drs.remove_far_sync('ORADATA_FS', FALSE)
FROM dual;
 
REPLACE_MEMBER_NAME_IN_PROPS  (new 18.1)
Replaces a member name with another member name in all broker properties dbms_drs.replace_member_name_in_props(
old_member_name IN VARCHAR2,
new_member_name IN VARCHAR2)
RETURN BINARY_INTEGER;
SELECT dbms_drs.remove_far_sync('ORCL', 'ORABASE')
FROM dual;
 
RESET_CONFIGURATION_PROPERTY (new 18.1)
Resets configuration-level property, not database or far sync instance property, to its default value dbms_drs.reset_configuration_property(property_name IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
RESET_DATABASE_PROPERTY (new 18.1)
Resets a database configurable property to its default value dbms_drs.reset_database_property(
database_name IN VARCHAR2,
property_name IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
RESET_FAR_SYNC_PROPERTY (new 18.1)
Resets a far sync instance configurable property to its default value dbms_drs.reset_far_sync_property(
far_sync_name IN VARCHAR2,
property_name IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
SET_CONFIGURATION_PROPERTY (new 18.1)
Used to set configuration-level property (not a database or far sync property ). Can be used to set both integer and character string properties. dbms_drs.set_configuration_property(
property_name IN VARCHAR2,
value         IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
SET_DATABASE_PROPERTY (new 18.1)
Used to set a database configurable property. Can be used to set both integer and character string properties. dbms_drs.set_database_property(
database_name IN VARCHAR2,
property_name IN VARCHAR2,
value in VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
SET_FAR_SYNC_PROPERTY (new 18.1)
Used to set a far sync instance's configurable property. Can be used to set both integer and character string properties. dbms_drs.set_far_sync_property(
far_sync_name IN VARCHAR2,
property_name IN VARCHAR2,
value         IN VARCHAR2)
RETURN BINARY_INTEGER;
TBD
 
SET_PROTECTION_MODE (new 18.1)
Changes the protection mode to the mode specified. To prevent including database restart logic this procedure does not support the promotion of the protection mode from maximum performance to maximum protection. dbms_drs.set_protection_mode(protection_mode IN VARCHAR2)
RETURN BINARY_INTEGER;
SELECT dbms_drs.set_protection_mode('MaxPerformance')
FROM dual;

SELECT dbms_drs.set_protection_mode('MaxAvailability')
FROM dual;

SELECT dbms_drs.set_protection_mode('MaxProtection')
FROM dual;
 
SLEEP
Suspends the session for a given period of time. Appears identical to DBMS_LOCK.SLEEP. dbms_drs.sleep(seconds IN INTEGER);
BEGIN
  dbms_drs.sleep(10);
END;
/
 
STARTUP_FOR_RELOCATE
Called when an instance is being started by a relocate operation. The other instance will be stopped in short order. If this is a standby database, this is the opportunity to gracefully relocate the apply services to the new instance that is being started up. In the event this is the standby that is supporting Maximum Protection mode, deregister the other instance as the critical instance and register this instance so that the subsequent shutdown can proceed smoothly while ensuring the primary continues to be protected. dbms_drs.startup_for_relocate;
exec dbms_drs.startup_for_relocate;
 
STATECHANGERECORDED
Undocumented (obsolete as of 12.2) dbms_drs.statechangerecorded(
iObid    IN BINARY_INTEGER,
iVersion IN BINARY_INTEGER);
TBD
 
 
STOP_OBSERVER (new 18.1)
Stops the fast-start failover observers in a data guard broker configuration dbms_drs.stop_observer(ob_name IN VARCHAR2)
RETURN BINARY_INTEGER;
SELECT dbms_drs.stop_observer('UWObserver')
FROM dual;
 
WAIT (new 18.1)
Waits up to the number of seconds specified by the max_wait_time argument for the event specified by the event_type parameter to prevail

Overload 1
dbms_drs.wait(
event_type    IN BINARY_INTEGER,
max_wait_time IN BINARY_INTEGER)
RETURN BINARY_INTEGER;
TBD
Overload 2 dbms_drs.wait(
event_type    IN BINARY_INTEGER,
max_wait_time IN BINARY_INTEGER,
flags         IN BINARY_INTEGER,
set_or_clear  IN BINARY_INTEGER)
RETURN BINARY_INTEGER;
TBD
Overload 3 dbms_drs.wait(
event_type    IN BINARY_INTEGER,
max_wait_time IN BINARY_INTEGER);
TBD
Overload 4 dbms_drs.wait(
event_type    IN BINARY_INTEGER,
max_wait_time IN BINARY_INTEGER,
flags         IN BINARY_INTEGER,
set_or_clear  IN BINARY_INTEGER);
TBD
 
 
WAIT_SYNC (new 18.1)
Used to wait for the specified member to be synchronized. If the keyword ANY is specified, this routine will wait for any destination to be synchronized. This function calls the rfs_wait_sync() ICD to perform the work.

Overload 1
dbms_drs.wait_sync(
member_name   IN VARCHAR2,
affirm        IN BOOLEAN,
max_wait_time IN BINARY_INTEGER)
RETURN BINARY_INTEGER;
TBD
Overload 2 dbms_drs.wait_sync(
member_name   IN VARCHAR2,
affirm        IN BOOLEAN,
max_wait_time IN BINARY_INTEGER);
TBD
Demos
Non-Blocking Demo set serveroutput on

DECLARE
 rid    INTEGER;
 indoc  VARCHAR2(4000);
 outdoc VARCHAR2(4000);
 p      INTEGER;
BEGIN
  indoc:='<dummy>foo</dummy>';
  rid := dbms_drs.do_control(indoc);
  dbms_output.put_line('Request_id = '|| rid);

  outdoc := NULL;
  p := 1;
  WHILE (outdoc is null) LOOP
    dbms_drs.sleep(0.2);

    outdoc := dbms_drs.get_response(rid, p);
  END LOOP;

  dbms_output.put_line(outdoc);

  BEGIN
    WHILE (outdoc IS NOT NULL)  LOOP
      p := p+1;
      outdoc := dbms_drs.get_response(rid,p);

      dbms_output.put_line(outdoc);
    END LOOP;
  EXCEPTION
    WHEN NO_DATA_FOUND THEN
      NULL;
  END;
  dbms_drs.delete_cancel(rid);
  dbms_drs.delete_request(rid);
END;
/
Blocking Demo set serveroutput on

DECLARE
 rid    INTEGER;
 indoc  VARCHAR2(4000);
 outdoc VARCHAR2(4000);
 p      INTEGER;
BEGIN
  p:=1;
  indoc:='<dummy>foo</dummy>';
  dbms_drs.do_control(indoc, outdoc, rid, p);
  dbms_output.put_line(outdoc);

  p := 2;
  WHILE (rid IS NOT NULL) LOOP
    dbms_drs.do_control(indoc, outdoc, rid, p);
    dbms_output.put_line(outdoc);
    p := p+1;
  END LOOP;
END;
/

Related Topics
Data Guard
DBMS_DG
DGMGRL
Packages
What's New In 12cR2
What's New In 18cR3

Morgan's Library Page Footer
This site is maintained by Dan Morgan. Last Updated: This site is protected by copyright and trademark laws under U.S. and International law. © 1998-2017 Daniel A. Morgan All Rights Reserved