12 DBMS_RA Package Reference

This chapter provides details on the DBMS_RA PL/SQL package. You use DBMS_RA subprograms to perform all Recovery Appliance administration functions.

One DBMS_RA procedure may execute at a given time. With the exception of ABORT_RECOVERY_APPLIANCE, attempts to run multiple DBMS_RA procedure in different sessions at the same time fail with an appropriate message.

The following table summarizes the available DBMS_RA subprograms.

Table 12-1 DBMS_RS Package Subprograms

Subprogram	Description
ABORT	Synonymous with ABORT_RECOVERY_APPLIANCE.
ABORT_RECOVERY_APPLIANCE	This procedure shuts down the Recovery Appliance without waiting for in-progress operations to complete.
ADD_DB	This procedure adds the specified database to the Recovery Appliance, and assigns a protection policy to the database. This procedure enables a non-protected database to attain the status of a protected database.
ADD_REPLICATION_SERVER	This procedure adds the specified replication server configuration to the specified protection policy. After the operation succeeds, the Recovery Appliance replicates backups of databases protected by this policy to the downstream Recovery Appliance.
CONFIG	This procedure updates a value in the config table.
COPY_BACKUP	This procedure copies one or more backup pieces from the Recovery Appliance to a user-specified disk or SBT destination. The Recovery Appliance copies all backup pieces matching the specified tag to the location specified with the format and template_name parameters.
COPY_BACKUP_PIECE	This procedure copies a single backup piece from the Recovery Appliance to a user-specified disk or SBT destination.
CREATE_POLLING_POLICY	This procedure creates a backup polling policy.
CREATE_PROTECTION_POLICY	This procedure creates a protection policy.
CREATE_REPLICATION_SERVER	This procedure defines a configuration for a downstream Recovery Appliance that forms part of a Recovery Appliance replication scheme.
CREATE_SBT_ATTRIBUTE_SET	This procedure creates an SBT attribute set that SBT jobs can use.
CREATE_SBT_JOB_TEMPLATE	This procedure creates an SBT job that describes how the Recovery Appliance chooses backups for copying to tape. This form of this overloaded procedure applies to backups for all protected databases assigned to the specified protection policy.
CREATE_SBT_JOB_TEMPLATE	This procedure creates a new SBT backup job. The job describes how the Recovery Appliance chooses backups for copying to tape/cloud. This form of this overloaded procedure applies to backups for a single protected database only, whereas the previous form applies to backups of all databases assigned to a specific protection policy. With the exception of this difference, this procedure and its parameters are identical to the alternative form of this procedure.
CREATE_SBT_LIBRARY	This procedure creates metadata describing an installed media management software library. The Recovery Appliance uses the specified library to copy backups from internal storage either to tape or to other tertiary storage supported by this media manager.
CREATE_STORAGE_LOCATION	This procedure creates Recovery Appliance storage location, which is an object that describes storage to be used by the Recovery Appliance. Recovery Appliance stores all backups in named storage locations.
DELETE_DB	This procedure removes the specified protected database from the Recovery Appliance. The Recovery Appliance deletes all metadata and backups associated with this database, both from disk and SBT. Backups on tape are not affected.
DELETE_POLLING_POLICY	This procedure deletes the specified backup polling policy.
DELETE_PROTECTION_POLICY	This procedure deletes the specified protection policy.
DELETE_REPLICATION_SERVER	This procedure deletes a replication server configuration. The Recovery Appliance removes all metadata relating to the downstream Recovery Appliance.
DELETE_SBT_ATTRIBUTE_SET	This procedure deletes the specified SBT attribute set.
DELETE_SBT_JOB_TEMPLATE	This procedure deletes the specified SBT job template.
DELETE_SBT_LIBRARY	This procedure deletes the metadata describing the specified SBT library.
DELETE_STORAGE_LOCATION	This procedure deletes the specified Recovery Appliance storage location.
GRANT_DB_ACCESS	This procedure grants the necessary privileges to the specified recovery Appliance user account to enable this account to back up, restore, and access recovery catalog metadata for the specified protected database.
KEY_REKEY	This procedure rekeys encryption keys for all databases with existing encryption keys.
KEY_REKEY	This procedure rekeys encryption keys for the specified database with an existing encryption key.
KEY_REKEY	This procedure rekeys encryption keys for all databases with existing encryption keys in the specified protection_policy
MIGRATE_TAPE_BACKUP	This procedure makes pre-migration tape backups accessible to the Recovery Appliance through the specified SBT library. You must first import metadata about the tape backups into the Recovery Appliance catalog using the RMAN IMPORT CATALOG command.
MOVE_BACKUP	This procedure moves one or more long-term archival backup pieces from the Recovery Appliance to a user-specified disk or SBT destination.
MOVE_BACKUP_PIECE	This procedure moves a single long-term archival backup piece from the Recovery Appliance to a user-specified disk or SBT destination.
PAUSE_REPLICATION_SERVER	This procedure pauses replication to the specified downstream Recovery Appliance.
PAUSE_SBT_LIBRARY	This procedure pauses the specified SBT library. The Recovery Appliance allows in-progress copies of backup pieces to complete. However, if backup pieces were queued for copy through this SBT library but not yet copied, then the Recovery Appliance holds them until you resume the SBT library. No new SBT jobs that run against this library can execute until you resume the library (RESUME_SBT_LIBRARY).
POPULATE_BACKUP_PIECE	This procedure pushes the specified backup piece into the delta store.
QUEUE_SBT_BACKUP_TASK	This procedure queues the backup pieces selected by the specified SBT job template for copying to tape. Typically, a scheduling utility such as Oracle Scheduler calls this procedure.
REMOVE_REPLICATION_SERVER	This procedure removes the specified replication server configuration from the specified protection policy. After the operation succeeds, the Recovery Appliance no longer replicates backups of databases protected by this policy to the downstream Recovery Appliance.
RENAME_DB	This procedure changes the name of the specified protected database in the Recovery Appliance metadata.
RESET_ERROR	This procedure modifies the specified error log entry to have the status RESET. Errors marked in this fashion do not cause Oracle Enterprise Manager to raise alerts. If the Recovery Appliance determines that the problem is still occurring, then errors that have been reset change to ACTIVE status. The primary use of this API is to reset the error status for nonrecurring errors, such as transient media failures.
RESUME_REPLICATION_SERVER	This procedure resumes replication to the specified downstream Recovery Appliance, after a previous call to PAUSE_REPLICATION_SERVER.
RESUME_SBT_LIBRARY	This procedure resumes a paused SBT library.
REVOKE_DB_ACCESS	This procedure revokes privileges on one protected database from the specified Recovery Appliance user account.
SET_SYSTEM_DESCRIPTION	This procedure sets a descriptive name for users to apply to their Recovery Appliance. The name provided here will be seen in the RA_SERVER view.
SHUTDOWN	Synonymous with SHUTDOWN_RECOVERY_APPLIANCE.
SHUTDOWN_RECOVERY_APPLIANCE	This procedure performs a clean shutdown of the Recovery Appliance.
STARTUP	Synonymous with STARTUP_RECOVERY_APPLIANCE.
STARTUP_RECOVERY_APPLIANCE	This procedure starts the Recovery Appliance after it has been shut down or terminated.
UPDATE_DB	This procedure changes the attributes that are assigned to the specified protected database.
UPDATE_POLLING_POLICY	This procedure modifies the parameters for an existing backup polling policy.
UPDATE_PROTECTION_POLICY	This procedure modifies the parameters for an existing protection policy.
UPDATE_REPLICATION_SERVER	This procedure changes the settings for a replication server configuration.
UPDATE_SBT_ATTRIBUTE_SET	This procedure updates the parameters for the specified SBT attribute set.
UPDATE_SBT_JOB_TEMPLATE	This procedure updates the parameters for the specified SBT job.
UPDATE_SBT_LIBRARY	This procedure modifies the parameters for the specified SBT library.
UPDATE_STORAGE_LOCATION	This procedure allocates additional space for the specified storage location. You cannot reduce the amount of space used by a storage location.

12.1 ABORT

Synonymous with ABORT_RECOVERY_APPLIANCE.

Syntax

PROCEDURE abort;

12.2 ABORT_RECOVERY_APPLIANCE

This procedure shuts down the Recovery Appliance without waiting for in-progress operations to complete.

When you use this procedure, the Recovery Appliance terminates backup, restore, and background operations (such as validations, data moves, and copy-to-tape/cloud jobs) that have started but not completed. When the Recovery Appliance restarts, it automatically resumes or restarts backup operations. You must manually restart any terminated backup and restore operations. To perform a clean shutdown, use SHUTDOWN_RECOVERY_APPLIANCE.

Syntax

PROCEDURE abort_recovery_appliance;

12.3 ADD_DB

This procedure adds the specified database to the Recovery Appliance, and assigns a protection policy to the database. This procedure enables a non-protected database to attain the status of a protected database.

Enrolling a database with the Recovery Appliance involves (1) adding the protected database with ADD_DB, (2) granting access to this database to a Recovery Appliance user account (GRANT_DB_ACCESS), and (3) registering this database in the virtual private catalog (RMAN REGISTER DATABASE command). The protected database must be enrolled before Recovery Appliance can process backup and restore operations.

You cannot use this procedure to add additional databases in a physical standby configuration. Such databases will be automatically recognized as they perform recovery catalog resynchronizations.

Syntax

PROCEDURE add_db (
   db_unique_name IN VARCHAR2,
   protection_policy_name IN VARCHAR2,
   reserved_space IN VARCHAR2);

Parameters

Table 12-2 ADD_DB Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the database to add.
protection_policy_name	The name of the protection policy to assign to the database. The protection policy must exist.
reserved_space	The amount of disk space that is guaranteed to be available for the protected database. The format of this value is a character string that must contain a number consisting only of the characters 0-9, followed optionally by one of the following unit specifiers: K: Kilobytes M: Megabytes G: Gigabytes T: Terabytes P: Petabytes E: Exabytes Z: Zettabytes Y: Yottabytes If no unit is specified, then Recovery Appliance interprets the value as a number of bytes.

12.4 ADD_REPLICATION_SERVER

This procedure adds the specified replication server configuration to the specified protection policy. After the operation succeeds, the Recovery Appliance replicates backups of databases protected by this policy to the downstream Recovery Appliance.

See CREATE_REPLICATION_SERVER.

Syntax

PROCEDURE add_replication_server (
   replication_server_name IN VARCHAR2,
   protection_policy_name IN VARCHAR2);

Parameters

Table 12-3 ADD_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the replication server configuration to associate with the protection policy.
protection_policy_name	The name of the protection policy to associate with the replication server configuration.

12.5 CONFIG

This procedure updates a value in the config table.

Syntax

PROCEDURE config(
   p_name VARCHAR2,
   p_value VARCHAR2);

Parameters

Table 12-4 CONFIG Parameters

Parameter	Description
p_name	The parameter to update. Possible parameters are: check_file_days The frequency with which the Recovery Appliance runs the metadata consistency check in the background. The default frequency is 3 days. crosscheck_db_days The frequency with which the Recovery Appliance performs background updates of the recovery catalog to reflect actions in tape libraries or downstream Recovery Appliances. Examples include deletions of backup pieces. The default frequency is 1 day. optimize_chunks_days The frequency with which the Recovery Appliance performs background re-ordering of blocks in the delta store to reduce disk reads required for restore operations. The default frequency is 7 days. validate_db_days The frequency with which the Recovery Appliance performs background validation of backup pieces. The default frequency is 7 days. percent_late_for_warning The percent threshold at which the Recovery Appliance posts warnings for incomplete background operations. For example, if validate_db_days is 7 and the percent_late_for_warning is 50, then the Recovery Appliance records a warning in the incident log when a database has gone 10.5 (or 7 + ((50/100)*7)) days without being validated. The fault is 100 percent. network_chunksize The message size that the Recovery Appliance uses for transferring backups between itself and protected databases. Also used for replication. The default is 128 MB. All protected databases use this value to determine the unit size in which to send or read backups. For example, if a protected database backup is 1 TB, then the SBT library sends the backup data to the Recovery Appliance in units of network_chunksize. This technique is an optimization that enables the Recovery Appliance to restart the data transfer faster if a failure occurs.
p_value	The new value for the parameter.

12.6 COPY_BACKUP

This procedure copies one or more backup pieces from the Recovery Appliance to a user-specified disk or SBT destination. The Recovery Appliance copies all backup pieces matching the specified tag to the location specified with the format and template_name parameters.

Syntax

PROCEDURE copy_backup (
   tag IN VARCHAR2,
   format IN VARCHAR2,
   template_name IN VARCHAR2,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-5 COPY_BACKUP Parameters

Parameter	Description
tag	The tag of the backups to copy. The Recovery Appliance copies all backups matching this tag.
format	The naming format of the backup pieces to create. This parameter follows the same rules as the RMAN FORMAT parameter.
template_name	The media management library template. If null, then format points to a disk location. If not null, then the Recovery Appliance copies the backup piece to tape (or cloud), using the media pool referenced in the SBT template name as the copy destination.
compression_algorithm	Specifies the compression algorithm. If compression_algorithm is specified, it will override the compression algorithm defined in template_name for this single operation. If template_name is NULL, it defines the compression algorithm for this operation. BASIC: Good compression ratios with potentially lower speed than MEDIUM. LOW: Optimized for speed with potentially lower compression raios than BASIC. MEDIUM: Recommended for most environments. Good combination of compression ratios and speed. HIGH: Best suited for operations over slower networks where the limiting factor is maximum network throughput. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used. 'LOW', 'MEDIUM', and 'HIGH' are Advanced Compression Options (ACO) which require additional licensing on the protected database for restore operations. OSB licenses are needed to restore backups directly from tape to DB client. OSB licenses include compression, so no ACO is needed. If 3P MMLs are used with compression, then ACO is needed on the target DB.
encryption_algorithm	Specifies the encryption algorithm If encryption_algorithm is specified, it will override the encryption algorithm defined in template_name for this single operation. If template_name is NULL, it defines the encryption algorithm for this operation. Valid value are 'AES128', 'AES192', 'AES256', 'OFF' or the constant equivalents ENC_OFF, ENC_AES128, ENC_AES192, ENC_AES256.

12.7 COPY_BACKUP_PIECE

This procedure copies a single backup piece from the Recovery Appliance to a user-specified disk or SBT destination.

Syntax

PROCEDURE copy_backup_piece (
   bp_key IN NUMBER,
   format IN VARCHAR2,
   template_name IN VARCHAR2,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-6 COPY_BACKUP_PIECE Parameters

Parameter	Description
bp_key	The unique key of the backup piece to copy. Obtain this key from the RC_BACKUP_PIECE view.
format	The naming format of the backup piece to create. This parameter follows the same rules as the RMAN FORMAT parameter.
template_name	A media management library template. If null, then format points to a disk location. If not null, then the Recovery Appliance copies the backup piece to tape, using the media pool referenced in the SBT template name as the copy destination.
compression_algorithm	Specifies the compression algorithm. If compression_algorithm is specified, it will override the compression algorithm defined in template_name for this single operation. If template_name is NULL, it defines the compression algorithm for this operation. BASIC: Good compression ratios with potentially lower speed than MEDIUM. LOW: Optimized for speed with potentially lower compression raios than BASIC. MEDIUM: Recommended for most environments. Good combination of compression ratios and speed. HIGH: Best suited for operations over slower networks where the limiting factor is maximum network throughput. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used. 'LOW', 'MEDIUM', and 'HIGH' are Advanced Compression Options (ACO) which require additional licensing on the protected database for restore operations. OSB licenses are needed to restore backups directly from tape to DB client. OSB licenses include compression, so no ACO is needed. If 3P MMLs are used with compression, then ACO is needed on the target DB.
encryption_algorithm	Specifies the encryption algorithm If encryption_algorithm is specified, it will override the encryption algorithm defined in template_name for this single operation. If template_name is NULL, it defines the encryption algorithm for this operation. Valid value are 'AES128', 'AES192', 'AES256', 'OFF' or the constant equivalents ENC_OFF, ENC_AES128, ENC_AES192, ENC_AES256

12.8 CREATE_POLLING_POLICY

This procedure creates a backup polling policy.

A backup polling policy specifies a directory where a protected database places incoming backups or archived redo log files. The policy also specifies the frequency with which the Recovery Appliance looks for backups in the polling location.

When the Recovery Appliance discovers a file through polling, the Recovery Appliance examines the file, and then uses its contents to associate it with a protected database that is registered with the Recovery Appliance. If the Recovery Appliance cannot associate the file with any registered protected database, then the Recovery Appliance logs a warning message and ceases to process the file.

Syntax

PROCEDURE create_polling_policy(
   polling_policy_name IN VARCHAR2,
   polling_location IN VARCHAR2,
   polling_frequency IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   delete_input IN BOOLEAN DEFAULT FALSE);

Parameters

Table 12-7 CREATE_POLLING_POLICY Parameters

Parameter	Description
polling_policy_name	The user-assigned name of the polling policy.
polling_location	The directory that the Recovery Appliance periodically examines for new backups. Do not specify this directory name in multiple polling policies.
polling_frequency	The frequency with which the Recovery Appliance examines the specified directory for new backups. System load may cause backup polling to occur less frequently. Specify the window as any valid INTERVAL DAY TO SECOND expression, such as INTERVAL '2' DAY (2 days), INTERVAL '4' HOUR (4 hours), and so on.
delete_input	The setting that controls deletion behavior. If TRUE, then the Recovery Appliance deletes files in the specified directory after copying them to a storage location. If FALSE, then the Recovery Appliance does not delete files that it discovers in the polling location.

12.9 CREATE_PROTECTION_POLICY

This procedure creates a protection policy.

Syntax

PROCEDURE create_protection_policy (
   protection_policy_name IN VARCHAR2,
   description IN VARCHAR2 DEFAULT NULL,
   storage_location_name IN VARCHAR2,
   polling_policy_name IN VARCHAR2 DEFAULT NULL,
   recovery_window_goal IN DSINTERVAL_UNCONSTRAINED,
   max_retention_window IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   recovery_window_sbt IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   unprotected_window IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   guaranteed_copy IN VARCHAR2 DEFAULT 'NO',
   allow_backup_deletion IN VARCHAR2 DEFAULT 'YES',
   store_and_forward IN VARCHAR2 DEFAULT 'NO');

Parameters

Table 12-8 CREATE_PROTECTION_POLICY Parameters

Parameter	Description
protection_policy_name	The user-assigned name of the protection policy.
description	An optional description of the usage for the policy.
storage_location_name	The name of the storage location. The Recovery Appliance uses this location for actively received incoming backups, and for newly created backup files for all databases sharing this protection policy.
polling_policy_name	The name of the backup polling policy. The polling policy specifies the rules for how the Recovery Appliance polls for backups of protected databases that use this protection policy. If null, then no backup polling occurs for databases that use this protection policy.
recovery_window_goal	The recovery window goal for databases that use this protection policy. For each protected database, the Recovery Appliance attempts to ensure that the oldest backup on disk can support a point-in-time recovery to any time within the specified interval, counting backward from the current time. Specify the goal as any valid INTERVAL DAY TO SECOND expression, such as INTERVAL '2' DAY (2 days), INTERVAL '4' HOUR (4 hours), and so on.
max_retention_window	The maximum length of time that the Recovery Appliance must retain backups for databases that use this protection policy. Recovery Appliance only holds backups longer than the specified period when they are required to preserve the recovery window goal for a database. If null, then the Recovery Appliance does not purge backups unless caused by explicit user actions or space pressures within a storage location.
recovery_window_sbt	The recovery window for SBT backups of databases that use this protection policy. For each protected database, the Recovery Appliance keeps backups long enough on tape to guarantee that a recovery is possible to any time within the specified interval, counting backward from the current time. If this parameter is not null, then you must also create an SBT job for this protection policy, and then schedule it using a scheduling facility such as Oracle Scheduler. See CREATE_SBT_JOB_TEMPLATE. Specify the window as any valid INTERVAL DAY TO SECOND expression, such as INTERVAL '2' DAY (2 days), INTERVAL '4' HOUR (4 hours), and so on.
unprotected_window	The maximum amount of data loss that is tolerable for databases using this protection policy. When a protected database exceeds the specified amount of data loss, the Recovery Appliance posts a warning to RA_INCIDENT_LOG. The most recent time to which each protected database is recoverable is shown in the HIGH_TIME column of RA_RESTORE_RANGE. Specify the window as any valid INTERVAL DAY TO SECOND expression, such as INTERVAL '2' DAY (2 days), INTERVAL '4' HOUR (4 hours), and so on.
guaranteed_copy	The setting of the guaranteed copy feature. Specifying NO means that the Recovery Appliance always accepts new backups, even if it must delete old backups when space is low. This option prioritizes the ability to successfully process the backup currently being received over the ability to restore older backups. Specifying YES ensures that the Recovery Appliance replicates backup data or copies it to tape before removing it from Recovery Appliance storage. This option prioritizes the ability to restore older backups over the ability to successfully process the backup currently being received. If set to YES, then for each protected database the Recovery Appliance can only hold up to disk_reserve_space bytes of backup data that is not yet copied or replicated. If hardware or network errors prevent timely copying or replication, then future attempts to create new backups will fail when the Recovery Appliance reaches the disk_reserve_space limit.
allow_backup_deletion	Setting this to NO will prevent RMAN users from deleting backups on the Recovery Appliance. The default value is set to YES. NO means that the Recovery Appliance will prevent backups from being deleted by RMAN users for the databases using this protection policy. YES means that the Recovery Appliance will allow for backups to be deleted by RMAN users for the databases using this protection policy.
store_and_forward	The setting of the Backup and Redo Failover feature. This setting is used only in a protection policy defined on the alternate Recovery Appliance where the protected databases associated with this policy will redirect backups and redo in the event of an outage on the primary Recovery Appliance. Specifying YES means that the alterate Recovery Appliance does not index these redirected backups. Instead, the backups are stored as-is, and are sent to the primary Recovery Appliance when the outage is over. The backup pieces are deleted once they are replicated on the primary; support for incremental forever is turned off for this alternate ZDLRA only. The downstream ZDLRA resumes the incremental forever strategry once it receives these backups. The default is NO.

12.10 CREATE_REPLICATION_SERVER

This procedure defines a configuration for a downstream Recovery Appliance that forms part of a Recovery Appliance replication scheme.

This procedure creates metadata for the downstream Recovery Appliance, but does not replicate any backups. Use the ADD_REPLICATION_SERVER procedure to link the downstream Recovery Appliance to one or more protection policies, so that the Recovery Appliance sends backups for protected databases assigned to these policies to the downstream Recovery Appliance.

Syntax

PROCEDURE create_replication_server (
   replication_server_name IN VARCHAR2,
   sbt_so_name IN VARCHAR2,
   sbt_parms IN VARCHAR2 DEFAULT NULL,
   max_streams IN NUMBER DEFAULT NULL,
   catalog_user_name IN VARCHAR2,
   wallet_alias IN VARCHAR2,
   wallet_path IN VARCHAR2,
   proxy_url IN VARCHAR2 DEFAULT NULL,
   proxy_port IN NUMBER DEFAULT NULL,
   http_timeout IN NUMBER DEFAULT NULL);

Parameters

Table 12-9 CREATE_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The user-assigned name of the downstream Recovery Appliance. This value is converted to upper-case before storing.
sbt_so_name	The name and path to the Recovery Appliance Backup Module. The module is an Oracle-supplied media library that simulates an SBT device. The Recovery Appliance uses this library to communicate with the downstream Recovery Appliance.
sbt_parms	The name and path of a client configuration file in the form (RA_CLIENT_CONFIG_FILE=file_system_location). The parentheses are mandatory. The client configuration file is a text file that must contain at a minimum the following parameters: ra_host - The host name and port of the remote Recovery Appliance in the format host:port. ra_wallet - The location of an Oracle wallet to use for authentication, and the credential to use. The following shows the sample contents of a client configuration file: ra_host=oam2.example.com:6498 ra_wallet='location=file:/u01/oracle/wallets credential_alias=repcred1'
max_streams	The maximum number of simultaneous replication tasks. If null, which is the recommended setting, then the upstream Recovery Appliance determines the number of streams to use for replication based on the number of its nodes.
catalog_user_name	The name of the replication user account on the downstream Recovery Appliance. The replication user account is a database user account on the downstream Recovery Appliance that upstream Recovery Appliances use to authenticate with this downstream Recovery Appliance.
wallet_alias	The alias that identifies the credential within the wallet that the upstream Recovery Appliances uses to authenticate with the downstream Recovery Appliance.
wallet_path	The path to the local Oracle wallet (excluding the wallet file name). Path must start with file: .
proxy_url	The URL of any required proxy server, in the format host.
proxy_port	The port number of the proxy server.
http_timeout	The HTTP timeout interval, in seconds. Usually you leave this parameter set to null, to accept the system default HTTP timeout, unless directed to set it to a different value by Oracle Support.

12.11 CREATE_SBT_ATTRIBUTE_SET

This procedure creates an SBT attribute set that SBT jobs can use.

An SBT attribute set provides a grouping of attributes that control the execution of an SBT job. These attributes enable you to specify settings for the media management library, including destination media pool or media family. You can define multiple SBT attribute sets. Multiple jobs can reference a single attribute set.

Syntax

PROCEDURE create_sbt_attribute_set(
   lib_name IN VARCHAR2,
   attribute_set_name IN VARCHAR2,
   streams IN NUMBER DEFAULT NULL,
   poolid IN NUMBER DEFAULT NULL,
   parms IN VARCHAR2 DEFAULT NULL,
   send IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-10 CREATE_SBT_ATTRIBUTE_SET Parameters

Parameter	Description
lib_name	The name of the SBT library to associate with the attribute set.
attribute_set_name	User-assigned name of the attribute set. Attribute set names must be unique.
streams	The maximum number of concurrent streams that the Recovery Appliance uses for automated backups. The number of concurrent streams never exceeds the limits set by the drives and restore_drives attributes of the SBT library. If streams is null, then the Recovery Appliance uses all available drives.
poolid	The media pool number to use as the destination for backup copies. This parameter accepts a value in the same format as the POOL parameter of the RMAN BACKUP command.
parms	The media management library-specific parameter string for the backup copy operation. The string has the same format as the PARMS option of the RMAN ALLOCATE CHANNEL command. During SBT backup operations for this attribute, the Recovery Appliance merges the value of this parameter with the PARMS parameter specified in the CREATE_SBT_LIBRARY procedure.
send	The string that the Recovery Appliance uses to send additional media management library-specific parameters for the backup copy operation. The string has the same format as the SEND option of the RMAN ALLOCATE CHANNEL command. During backup operations for this attribute, the Recovery Appliance merges the value of this parameter with the SEND parameter specified in the CREATE_SBT_LIBRARY procedure.

12.12 CREATE_SBT_JOB_TEMPLATE

This procedure creates an SBT job that describes how the Recovery Appliance chooses backups for copying to tape. This form of this overloaded procedure applies to backups for all protected databases assigned to the specified protection policy.

After you create an SBT backup job, you must schedule it with a scheduling facility such as Oracle Scheduler. See QUEUE_SBT_BACKUP_TASK.

Syntax

PROCEDURE create_sbt_job_template (
   template_name IN VARCHAR2,
   protection_policy_name IN VARCHAR2,
   attribute_set_name IN VARCHAR2,
   backup_type IN VARCHAR2,
   full_template_name IN VARCHAR2 DEFAULT NULL,
   from_tag IN VARCHAR2 DEFAULT NULL,
   priority IN NUMBER DEFAULT SBT_PRIORITY_MEDIUM,
   copies IN NUMBER DEFAULT 1,
   window IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-11 CREATE_SBT_JOB_TEMPLATE Parameters

Parameter	Description
template_name	The user-assigned name of this SBT job template.
protection_policy_name	The name of the protection policy to which this SBT job applies. Backups for all protected databases assigned to this protection policy are eligible for copying.
attribute_set_name	The name of the SBT attribute set to use for this SBT job.
backup_type	The types of backups that this SBT job chooses for copying to tape. The string must be a comma-separated list of the following types: ALL: Shorthand for FULL, INCR, ARCH INCR: Copies all incremental logs that have not yet been copied to tape, since the most recent full backup. ARCH: Copies all archived redo log backups that have not yet been copied to tape, since the most recent full backup. FULL: Copies the most recent virtual level 0 backup, if it has not already been copied, to tape. The backup can either be a virtual level 0 backup that is based on the most recent level 0 backup received or a virtual level 0 backup that is based on the most recent level 1 backup received, whichever is more recent.
full_template_name	The full name of this SBT job template. This applies only to INCR and ARCH backup types. The full name links full backups with the incremental backups and archived redo log files needed to recover them. If only one full backup template exists for the specified tape library, then this parameter defaults to the name of this template, which means it does not need to be specified. If multiple full backup templates exist, then you must specify the full template name. The specified FULL template name must belong to the same SBT library as the INCR or ARCH job. If backup_type is set to FULL or ALL, then full_template_name is the same as template_name.
from_tag	The tag name. If specified, then the Recovery Appliance only considers backups using this tag for copying to tape. Refer to "Oracle Database Backup and Recovery Reference" for the correct format for TAG string.
priority	The priority of this job for tape resource usage. Lower priority values take precedence over higher values. 0 is the highest possible priority. You can use any number that is greater than or equal to 0. The pre-defined values are as follows: SBT_PRIORITY_LOW maps to 1000 SBT_PRIORITY_MEDIUM maps to 100 SBT_PRIORITY_HIGH maps to 10 SBT_PRIORITY_CRITICAL maps to 1 The default priority is SBT_PRIORITY_MEDIUM. Restore jobs by default have SBT_PRIORITY_CRITICAL priority.
copies	The number of distinct copies of each backup that this SBT job creates. Valid values range from 1 (default) to 4.
window	The window of time in which this job can copy backups to tape. Copy tasks that are not able to start within the specified window must wait until the next scheduled job execution.
compression_algorithm	Specifies the compression algorithm. If compression_algorithm is specified, it will override the compression algorithm defined in template_name for this single operation. If template_name is NULL, it defines the compression algorithm for this operation. BASIC: Good compression ratios with potentially lower speed than MEDIUM. LOW: Optimized for speed with potentially lower compression raios than BASIC. MEDIUM: Recommended for most environments. Good combination of compression ratios and speed. HIGH: Best suited for operations over slower networks where the limiting factor is maximum network throughput. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used. 'LOW', 'MEDIUM', and 'HIGH' are Advanced Compression Options (ACO) which require additional licensing on the protected database for restore operations. OSB licenses are needed to restore backups directly from tape to DB client. OSB licenses include compression, so no ACO is needed. If 3P MMLs are used with compression, then ACO is needed on the target DB.
encryption_algorithm	Encryption algorithm to use for tape jobs. Valid value are 'AES128', 'AES192', 'AES256', 'OFF', or the constant equivalents ENC_OFF, ENC_AES128, ENC_AES192, ENC_AES256

12.13 CREATE_SBT_JOB_TEMPLATE

This procedure creates a new SBT backup job. The job describes how the Recovery Appliance chooses backups for copying to tape/cloud. This form of this overloaded procedure applies to backups for a single protected database only, whereas the previous form applies to backups of all databases assigned to a specific protection policy. With the exception of this difference, this procedure and its parameters are identical to the alternative form of this procedure.

Syntax

PROCEDURE create_sbt_job_template (
   template_name IN VARCHAR2,
   db_unique_name IN VARCHAR2,
   attribute_set_name IN VARCHAR2,
   backup_type IN VARCHAR2,
   full_template_name IN VARCHAR2 DEFAULT NULL,
   from_tag IN VARCHAR2 DEFAULT NULL,
   priority IN NUMBER DEFAULT SBT_PRIORITY_MEDIUM,
   copies IN NUMBER DEFAULT 1,
   window IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-12 CREATE_SBT_JOB_TEMPLATE Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the protected database to which this SBT job applies. This SBT job copies only backups that belong to the specified database.

12.14 CREATE_SBT_LIBRARY

This procedure creates metadata describing an installed media management software library. The Recovery Appliance uses the specified library to copy backups from internal storage either to tape or to other tertiary storage supported by this media manager.

Syntax

PROCEDURE create_sbt_library (
   lib_name IN VARCHAR2,
   drives IN NUMBER,
   restore_drives IN NUMBER DEFAULT 0,
   parms IN VARCHAR2 DEFAULT NULL,
   send IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-13 CREATE_SBT_LIBRARY Parameters

Parameter	Description
lib_name	The user-specified name that the Recovery Appliance uses to refer to this SBT library.
drives	The maximum number of tape drives that this SBT library can access. The Recovery Appliance never uses more than the specified number of concurrent streams when accessing this library.
restore_drives	The number of tape drives that the Recovery Appliance reserves for restore operations. If specified, then the Recovery Appliance uses a maximum of drives - restore_drives drives for backup operations, which ensures that the Recovery Appliance always has the specified number of drives available for restore operations. If not specified, then the Recovery Appliance can use all available drives for backups, which means that a restore operation might have to wait for a drive to become free.
parms	The library-specific parameter string that the Recovery Appliance uses to access this SBT library. This string has the same format as the PARMS option of the RMAN ALLOCATE CHANNEL command. The string usually contains the SBT_LIBRARY parameter.
send	The parameter string that the Recovery Appliance uses to send additional library-specific parameters to this SBT library. This string has the same format as the SEND option of the RMAN ALLOCATE CHANNEL command.

12.15 CREATE_STORAGE_LOCATION

This procedure creates Recovery Appliance storage location, which is an object that describes storage to be used by the Recovery Appliance. Recovery Appliance stores all backups in named storage locations.

The Recovery Appliance allocates storage locations from the Oracle ASM disk groups that reside in the Recovery Appliance.

The newly created storage location does not store any files until you use a protection policy to associate the location with a protected database.

Syntax

PROCEDURE create_storage_location (
   storage_location_name IN VARCHAR2,
   storage_location_dests IN VARCHAR2);

Parameters

Table 12-14 CREATE_STORAGE_LOCATION Parameters

Parameter	Description
storage_location_name	The user-assigned name of this storage location.
storage_location_dests	A comma-delimited list of Oracle ASM disk groups from which space is to be allocated for this storage location. The disk groups must exist. The specified disk groups must have the same allocation unit size. Multiple storage locations cannot use the same Oracle ASM disk group. This parameter accepts a string in the following format: storage_location_spec [ , storage_location_spec ... ] Each storage_location_spec has the following format: storage_location_name [ ( size [ K | M | G | T | P | E | Z | Y ] ) ] storage_location_name is the name of an Oracle ASM disk group. Optionally, you can follow the disk group name with the amount of space to be allocated from this disk group for this storage location. If no size is specified, then the Recovery Appliance allocates all of the free space in the disk group to this storage location. The following example specifies a storage location that uses all the free space in disk group DG1: +DG1 The following example specifies a storage location that uses 20 terabytes of space from disk group DG1, all free space in disk group DG2, and 30 terabytes of space from disk group DG3: +DG1(20T),+DG2,+DG3(30T)

12.16 DELETE_DB

This procedure removes the specified protected database from the Recovery Appliance. The Recovery Appliance deletes all metadata and backups associated with this database, both from disk and SBT. Backups on tape are not affected.

If the Recovery Appliance cannot delete the SBT backups owned by this database because of errors, then the DELETE_DB operation fails. If SBT errors occur, then the specified database is not completely removed from the Recovery Appliance. The Recovery Appliance logs errors that occur during the DELETE_DB procedure in the RA_INCIDENT_LOG view. If the wait parameter is specified as TRUE, then the Recovery Appliance also raises these errors in the session in which DELETE_DB is called. If you diagnose the SBT errors and fix the problem, then you can run DELETE_DB again.

Syntax

PROCEDURE delete_db (
   db_unique_name IN VARCHAR2,
   wait IN BOOLEAN DEFAULT TRUE);

Parameters

Table 12-15 DELETE_DB Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the database to be removed.
wait	The wait behavior of the procedure. If TRUE, then the procedure will not return until the backups and metadata for the specified database are completely removed from the Recovery Appliance. If FALSE, then the procedure returns immediately, and the database deletion operation continues in the background.

12.17 DELETE_POLLING_POLICY

This procedure deletes the specified backup polling policy.

Syntax

PROCEDURE delete_polling_policy (
   polling_policy_name IN VARCHAR2);

Parameters

Table 12-16 DELETE_POLLING_POLICY Parameters

Parameter	Description
polling_policy_name	The name of the backup polling policy to delete.

12.18 DELETE_PROTECTION_POLICY

This procedure deletes the specified protection policy.

The specified policy must not be associated with any database.

Syntax

PROCEDURE delete_protection_policy (
   protection_policy_name IN VARCHAR2);

Parameters

Table 12-17 DELETE_PROTECTION_POLICY Parameters

Parameter	Description
protection_policy_name	The name of the protection policy to delete.

12.19 DELETE_REPLICATION_SERVER

This procedure deletes a replication server configuration. The Recovery Appliance removes all metadata relating to the downstream Recovery Appliance.

Syntax

PROCEDURE delete_replication_server (
   replication_server_name IN VARCHAR2,
   force IN BOOLEAN DEFAULT FALSE);

Parameters

Table 12-18 DELETE_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the replication server configuration to delete.
force	The deletion behavior when a protection policy is associated with the configuration. If FALSE, and if the replication server configuration is still associated with a protection policy, then the deletion fails. In this case, you must first call REMOVE_REPLICATION_SERVER. If TRUE, then delete_replication_server first removes the replication server configuration from the protection policy.

12.20 DELETE_SBT_ATTRIBUTE_SET

This procedure deletes the specified SBT attribute set.

Syntax

PROCEDURE delete_sbt_attribute_set(
   attribute_set_name IN VARCHAR2);

Parameters

Table 12-19 DELETE_SBT_ATTRIBUTE_SET Parameters

Parameter	Description
attribute_set_name	The name of the SBT attribute set to delete.

12.21 DELETE_SBT_JOB_TEMPLATE

This procedure deletes the specified SBT job template.

Syntax

PROCEDURE delete_sbt_job_template (
   template_name IN VARCHAR2);

Parameters

Table 12-20 DELETE_SBT_JOB_TEMPLATE Parameters

Parameter	Description
template_name	The name of the SBT job to delete. The Recovery Appliance removes tasks belonging to this job from the task queue but does not terminate any executing task.

12.22 DELETE_SBT_LIBRARY

This procedure deletes the metadata describing the specified SBT library.

The Recovery Appliance only removes the SBT library object, and does not uninstall the media management software.

This procedure deletes any SBT jobs and attributes created for this SBT library.

Syntax

PROCEDURE delete_sbt_library (
   lib_name IN VARCHAR2);

Parameters

Table 12-21 DELETE_SBT_LIBRARY Parameters

Parameter	Description
lib_name	The name of the SBT library to delete.

12.23 DELETE_STORAGE_LOCATION

This procedure deletes the specified Recovery Appliance storage location.

The specified storage location must be empty and must not be associated with any protection policy. No storage movement may be in progress for this storage location. If any storage movement is in progress, or if any files exist in this storage location, then this procedure fails with an error.

Syntax

PROCEDURE delete_storage_location (
   storage_location_name IN VARCHAR2);

Parameters

Table 12-22 DELETE_STORAGE_LOCATION Parameters

Parameter	Description
storage_location_name	The name of the Recovery Appliance storage location to delete.

12.24 GRANT_DB_ACCESS

This procedure grants the necessary privileges to the specified recovery Appliance user account to enable this account to back up, restore, and access recovery catalog metadata for the specified protected database.

Syntax

PROCEDURE grant_db_access (
   username IN VARCHAR2,
   db_unique_name IN VARCHAR2);

Parameters

Table 12-23 GRANT_DB_ACCESS Parameters

Parameter	Description
username	The name of the Recovery Appliance user account.
db_unique_name	The protected database for which the privilege is being granted.

12.25 KEY_REKEY

This procedure rekeys encryption keys for all databases with existing encryption keys.

Syntax

PROCEDURE key_rekey;

12.26 KEY_REKEY

This procedure rekeys encryption keys for the specified database with an existing encryption key.

Syntax

PROCEDURE key_rekey (
   db_unique_name IN VARCHAR2);

Parameters

Table 12-24 KEY_REKEY Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the database to generate a new encryption key. Note: this routine will not create a new key, only rekey an existing key

12.27 KEY_REKEY

This procedure rekeys encryption keys for all databases with existing encryption keys in the specified protection_policy

Syntax

PROCEDURE key_rekey (
   protection_policy_name IN VARCHAR2);

Parameters

Table 12-25 KEY_REKEY Parameters

Parameter	Description
protection_policy_name	Generate new encryption keys for databases that are part of this protection policy.

12.28 MIGRATE_TAPE_BACKUP

This procedure makes pre-migration tape backups accessible to the Recovery Appliance through the specified SBT library. You must first import metadata about the tape backups into the Recovery Appliance catalog using the RMAN IMPORT CATALOG command.

This procedure performs the metadata adjustments required to access pre-existing tape backups, but does not physically move backups. The pre-existing backups must already be accessible by the specified SBT library.

Syntax

PROCEDURE migrate_tape_backup(
   db_unique_name IN VARCHAR2,
   sbt_lib_name IN VARCHAR2);

Parameters

Table 12-26 MIGRATE_TAPE_BACKUP Parameters

Parameter	Description
db_unique_name	The comma-delimited list of protected databases whose backups are to be migrated. You must already have registered each db_unique_name with the Recovery Appliance catalog, and have added it to the Recovery Appliance with ADD_DB.
sbt_lib_name	The SBT library that the Recovery Appliance uses to access existing tape backups for the specified protected database. See CREATE_SBT_LIBRARY.

12.29 MOVE_BACKUP

This procedure moves one or more long-term archival backup pieces from the Recovery Appliance to a user-specified disk or SBT destination.

The Recovery Appliance copies all backup pieces matching the specified tag to the location specified with the format and template_name parameters. After the Recovery Appliance copies each backup piece successfully, the Recovery Appliance deletes the backup piece from its original location.

Syntax

PROCEDURE move_backup (
   tag IN VARCHAR2,
   format IN VARCHAR2,
   template_name IN VARCHAR2,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-27 MOVE_BACKUP Parameters

Parameter	Description
tag	The tag of backups to copy. The Recovery Appliance removes all backups matching this tag.
format	The naming format of the backup pieces to create. This parameter follows the same rules as the RMAN FORMAT parameter.
template_name	A media management library template. If null, then format points to a disk location. If not null, then the Recovery Appliance copies the backup piece to tape, using the media pool referenced in the SBT template name as the copy destination.
compression_algorithm	Specifies the compression algorithm If compression_algorithm is specified, it will override the compression algorithm defined in template_name for this single operation. If template_name is NULL, it defines the compression algorithm for this operation. Valid value are 'BASIC', 'LOW', 'MEDIUM', 'HIGH', 'OFF'
encryption_algorithm	Specifies the encryption algorithm If encryption_algorithm is specified, it will override the encryption algorithm defined in template_name for this single operation. If template_name is NULL, it defines the encryption algorithm for this operation. Valid value are 'AES128', 'AES192', 'AES256', 'OFF' or the constant equivalents ENC_OFF, ENC_AES128, ENC_AES192, ENC_AES256

12.30 MOVE_BACKUP_PIECE

This procedure moves a single long-term archival backup piece from the Recovery Appliance to a user-specified disk or SBT destination.

The Recovery Appliance copies the specified backup piece to the location specified with the format and template_name parameters. After the Recovery Appliance copies the backup piece successfully, the Recovery Appliance deletes the backup piece from its original location.

Syntax

PROCEDURE move_backup_piece (
   bp_key IN NUMBER,
   format IN VARCHAR2,
   template_name IN VARCHAR2,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-28 MOVE_BACKUP_PIECE Parameters

Parameter	Description
bp_key	The unique key of the backup piece to move. Obtain this key from the RC_BACKUP_PIECE view.
format	The naming format of the backup pieces to create. This parameter follows the same rules as the RMAN FORMAT parameter.
template_name	A media management library template. If null, then format points to a disk location. If not null, then the Recovery Appliance copies the backup piece to tape, using the media pool referenced in the SBT template name as the copy destination.
compression_algorithm	Specifies the compression algorithm. If compression_algorithm is specified, it will override the compression algorithm defined in template_name for this single operation. If template_name is NULL, it defines the compression algorithm for this operation. BASIC: Good compression ratios with potentially lower speed than MEDIUM. LOW: Optimized for speed with potentially lower compression raios than BASIC. MEDIUM: Recommended for most environments. Good combination of compression ratios and speed. HIGH: Best suited for operations over slower networks where the limiting factor is maximum network throughput. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used. 'LOW', 'MEDIUM', and 'HIGH' are Advanced Compression Options (ACO) which require additional licensing on the protected database for restore operations. OSB licenses are needed to restore backups directly from tape to DB client. OSB licenses include compression, so no ACO is needed. If 3P MMLs are used with compression, then ACO is needed on the target DB.
encryption_algorithm	Specifies the encryption algorithm If encryption_algorithm is specified, it will override the encryption algorithm defined in template_name for this single operation. If template_name is NULL, it defines the encryption algorithm for this operation. Valid value are 'AES128', 'AES192', 'AES256', 'OFF' or the constant equivalents ENC_OFF, ENC_AES128, ENC_AES192, ENC_AES256

12.31 PAUSE_REPLICATION_SERVER

This procedure pauses replication to the specified downstream Recovery Appliance.

The Recovery Appliance permits in-progress replication of backup pieces to complete. If the Recovery Appliance queued backup pieces for replication through this replication server configuration but did not replicate them, then the Recovery Appliance holds the backup pieces until you call RESUME_REPLICATION_SERVER. No replication tasks that run against this Recovery Appliance can execute until you resume replication to the downstream Recovery Appliance.

Syntax

PROCEDURE pause_replication_server  (
   replication_server_name IN VARCHAR2);

Parameters

Table 12-29 PAUSE_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the downstream Recovery Appliance.

12.32 PAUSE_SBT_LIBRARY

This procedure pauses the specified SBT library. The Recovery Appliance allows in-progress copies of backup pieces to complete. However, if backup pieces were queued for copy through this SBT library but not yet copied, then the Recovery Appliance holds them until you resume the SBT library. No new SBT jobs that run against this library can execute until you resume the library (RESUME_SBT_LIBRARY).

Query the RA_SBT_LIBRARY view for a list of existing SBT libraries.

Syntax

PROCEDURE pause_sbt_library(
   lib_name IN VARCHAR2);

Parameters

Table 12-30 PAUSE_SBT_LIBRARY Parameters

Parameter	Description
lib_name	Name of the SBT library to pause.

12.33 POPULATE_BACKUP_PIECE

This procedure pushes the specified backup piece into the delta store.

Use this procedure to initially populate the delta store or to correct corruption in the delta store. The delta store is backup data that supports an incremental-forever backup solution. Only incremental backups (not KEEP backups) can become part of the delta store.

Syntax

PROCEDURE populate_backup_piece(
   backup_piece_key IN NUMBER);

Parameters

Table 12-31 POPULATE_BACKUP_PIECE Parameters

Parameter

Description

backup_piece_key

Either the backup piece key provided by the Recovery Appliance when it detected a corruption, or the backup piece to insert into the delta store. If the key represents a virtual backup piece, then the Recovery Appliance searches for a backup piece to resolve corruption in the delta store. If the key does not represent a virtual backup, then the Recovery Appliance inserts this backup piece into the delta store. This backup must be an incremental backup that is not a KEEP backup.

12.34 QUEUE_SBT_BACKUP_TASK

This procedure queues the backup pieces selected by the specified SBT job template for copying to tape. Typically, a scheduling utility such as Oracle Scheduler calls this procedure.

Syntax

PROCEDURE queue_sbt_backup_task(
   template_name IN VARCHAR2,
   format IN VARCHAR2 DEFAULT NULL,
   autobackup_prefix IN VARCHAR2 DEFAULT NULL,
   tag IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-32 QUEUE_SBT_BACKUP_TASK Parameters

Parameter	Description
template_name	The name of the SBT job template that specifies the backup pieces to copy to tape.
format	The naming format of the backup pieces to create. This parameter follows the same rules as the RMAN FORMAT parameter
autobackup_prefix	The original autobackup names will be prefixed with this autobackup_prefix.
tag	User specified tag for backups to be copied See CREATE_SBT_JOB_TEMPLATE.

12.35 REMOVE_REPLICATION_SERVER

This procedure removes the specified replication server configuration from the specified protection policy. After the operation succeeds, the Recovery Appliance no longer replicates backups of databases protected by this policy to the downstream Recovery Appliance.

Syntax

PROCEDURE remove_replication_server (
   replication_server_name IN VARCHAR2,
   protection_policy_name IN VARCHAR2);

Parameters

Table 12-33 REMOVE_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the replication server configuration to remove.
protection_policy_name	The name of the protection policy from which the specified replication server configuration is to be removed.

12.36 RENAME_DB

This procedure changes the name of the specified protected database in the Recovery Appliance metadata.

Use this procedure when the DB_UNIQUE_NAME for a protected database changes, so that the Recovery Appliance metadata reflects the correct name.

Syntax

PROCEDURE rename_db (
   db_unique_name_old IN VARCHAR2,
   db_unique_name_new IN VARCHAR2);

Parameters

Table 12-34 RENAME_DB Parameters

Parameter	Description
db_unique_name_old	The DB_UNIQUE_NAME to change.
db_unique_name_new	The new DB_UNIQUE_NAME.

12.37 RESET_ERROR

This procedure modifies the specified error log entry to have the status RESET. Errors marked in this fashion do not cause Oracle Enterprise Manager to raise alerts. If the Recovery Appliance determines that the problem is still occurring, then errors that have been reset change to ACTIVE status. The primary use of this API is to reset the error status for nonrecurring errors, such as transient media failures.

Syntax

PROCEDURE reset_error(
   incident# IN NUMBER);

Parameters

Table 12-35 RESET_ERROR Parameters

Parameter	Description
incident#	The unique identifier of the error log entry to reset. Obtain the identifier from the RA_INCIDENT_LOG view.

12.38 RESUME_REPLICATION_SERVER

This procedure resumes replication to the specified downstream Recovery Appliance, after a previous call to PAUSE_REPLICATION_SERVER.

Syntax

PROCEDURE resume_replication_server (
   replication_server_name IN VARCHAR2);

Parameters

Table 12-36 RESUME_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the downstream Recovery Appliance.

12.39 RESUME_SBT_LIBRARY

This procedure resumes a paused SBT library.

Query the RA_SBT_LIBRARY to determine which SBT libraries are paused (see PAUSE_SBT_LIBRARY).

Syntax

PROCEDURE resume_sbt_library(
   lib_name IN VARCHAR2);

Parameters

Table 12-37 RESUME_SBT_LIBRARY Parameters

Parameter	Description
lib_name	Name of the SBT library to resume.

12.40 REVOKE_DB_ACCESS

This procedure revokes privileges on one protected database from the specified Recovery Appliance user account.

Syntax

PROCEDURE revoke_db_access (
   username IN VARCHAR2,
   db_unique_name IN VARCHAR2);

Parameters

Table 12-38 REVOKE_DB_ACCESS Parameters

Parameter	Description
username	The name of the user account from which to revoke the privilege.
db_unique_name	The protected database for which the privilege is being revoked.

12.41 SET_SYSTEM_DESCRIPTION

This procedure sets a descriptive name for users to apply to their Recovery Appliance. The name provided here will be seen in the RA_SERVER view.

Syntax

PROCEDURE set_system_description(
   sys_desc VARCHAR2);

Parameters

Table 12-39 SET_SYSTEM_DESCRIPTION Parameters

Parameter	Description
sys_desc	A descriptive name for this Recovery Applicance.

12.42 SHUTDOWN

Synonymous with SHUTDOWN_RECOVERY_APPLIANCE.

Syntax

PROCEDURE shutdown;

12.43 SHUTDOWN_RECOVERY_APPLIANCE

This procedure performs a clean shutdown of the Recovery Appliance.

This procedure permits in-progress operations to complete before shutting down. The shutdown can take some time. If an immediate shutdown is required, then use ABORT_RECOVERY_APPLIANCE.

Syntax

PROCEDURE shutdown_recovery_appliance;

12.44 STARTUP

Synonymous with STARTUP_RECOVERY_APPLIANCE.

Syntax

PROCEDURE startup;

12.45 STARTUP_RECOVERY_APPLIANCE

This procedure starts the Recovery Appliance after it has been shut down or terminated.

The Recovery Appliance can process backup and restore requests only when it is started.

If the Recovery Appliance was started with STARTUP_RECOVERY_APPLIANCE, and if any instance of the Recovery Appliance metadata database is restarted, then a database startup trigger automatically restarts the Recovery Appliance. The only exception is when the metadata database is restarted with the RESETLOGS option, which requires you to run the startup_recovery_appliance procedure to repair corrupt metadata.

Syntax

PROCEDURE startup_recovery_appliance;

12.46 UPDATE_DB

This procedure changes the attributes that are assigned to the specified protected database.

Syntax

PROCEDURE update_db (
   db_unique_name IN VARCHAR2,
   protection_policy_name IN VARCHAR2 DEFAULT NULL,
   reserved_space IN VARCHAR2 DEFAULT NULL,
   db_timezone IN VARCHAR2 DEFAULT NULL,
   incarnations IN VARCHAR2 DEFAULT 'CURRENT');

Parameters

Table 12-40 UPDATE_DB Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the database.
protection_policy_name	The name of the protection policy to assign to the database. The protection policy must exist. The new protection policy controls new storage operations. If the old and new protection policies specify different storage locations, the Recovery Appliance starts a background task to move data from the old storage location to the new location. Recovery Appliance only moves backups that are not obsolete. If a move between storage locations is required, then the RA_DATABASE view does not show the new protection policy until the move has started. If the Recovery Appliance must perform higher priority work, then the Recovery Appliance may not start the move for several hours.
reserved_space	See ADD_DB.
db_timezone	The time zone where this database is located. By default, protected databases are assigned to the same time zone as the Recovery Appliance. If the protected database is in a different time zone, then use this procedure to assign the database to the correct time zone.
incarnations	Comma-delimited list of keys for all previous database incarnations to update. By default, this procedure updates the current incarnation. If this list contains the current incarnation key, then the procedure updates the row corresponding to the current incarnation in the dbinc and node tables only if the protected database administrator has not specified the time zone in the parameter file. If their entries in the dbinc table are valid, then this procedure updates the entries for all other incarnations in the list.

12.47 UPDATE_POLLING_POLICY

This procedure modifies the parameters for an existing backup polling policy.

Parameters that are NULL retain their existing values.

Syntax

PROCEDURE update_polling_policy (
   polling_policy_name IN VARCHAR2,
   polling_location IN VARCHAR2 DEFAULT NULL,
   polling_frequency IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   delete_input IN BOOLEAN DEFAULT NULL);

Parameters

Table 12-41 UPDATE_POLLING_POLICY Parameters

Parameter	Description
polling_policy_name	The name of the backup polling policy to update.
polling_location	See CREATE_POLLING_POLICY.
polling_frequency	See CREATE_POLLING_POLICY.
delete_input	See CREATE_POLLING_POLICY.

12.48 UPDATE_PROTECTION_POLICY

This procedure modifies the parameters for an existing protection policy.

If a parameter is NULL, its value remains unchanged, except as noted below.

Syntax

PROCEDURE update_protection_policy (
   protection_policy_name IN VARCHAR2,
   description IN VARCHAR2 DEFAULT NULL,
   storage_location_name IN VARCHAR2 DEFAULT NULL,
   polling_policy_name IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p1'),
   recovery_window_goal IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   max_retention_window IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_misc.intervalnull('p3'),
   recovery_window_sbt IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_misc.intervalnull('p2'),
   unprotected_window IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_misc.intervalnull('p4'),
   guaranteed_copy IN VARCHAR2 DEFAULT NULL,
   allow_backup_deletion IN VARCHAR2 DEFAULT NULL,
   store_and_forward IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-42 UPDATE_PROTECTION_POLICY Parameters

Parameter	Description
protection_policy_name	The name of the protection policy to update.
description	See CREATE_PROTECTION_POLICY.
storage_location_name	See CREATE_PROTECTION_POLICY. If you change the storage location for this protection policy, then the Recovery Appliance starts background jobs to move data from the old storage location to the new storage location.
polling_policy_name	See CREATE_PROTECTION_POLICY. If you do not specify this parameter, then the policy retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
recovery_window_goal	See CREATE_PROTECTION_POLICY.
max_retention_window	See CREATE_PROTECTION_POLICY. If this parameter is not specified, its old value is retained. If specified, including being specified as NULL, the new value is set.
recovery_window_sbt	See CREATE_PROTECTION_POLICY. If you do not specify this parameter, then the policy retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
unprotected_window	If you do not specify this parameter, then the policy retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value. See CREATE_PROTECTION_POLICY.
guaranteed_copy	See CREATE_PROTECTION_POLICY.
allow_backup_deletion	See CREATE_PROTECTION_POLICY.
store_and_forward	See CREATE_PROTECTION_POLICY.

12.49 UPDATE_REPLICATION_SERVER

This procedure changes the settings for a replication server configuration.

Note the following restrictions for changing replication server parameters:

The configuration does not retain the sbt_parms string from the original CREATE_REPLICATION_SERVER call. If you change any parameter other than max_streams, then you must pass in this value.

Changing any setting other than max_streams requires replication to be paused, which you can achieve by calling PAUSE_REPLICATION_SERVER.

Parameters other than sbt_parms whose values are null remain unchanged, except as noted in the following parameter descriptions.

Syntax

PROCEDURE update_replication_server (
   replication_server_name IN VARCHAR2,
   sbt_so_name IN VARCHAR2 DEFAULT NULL,
   sbt_parms IN VARCHAR2 DEFAULT NULL,
   max_streams IN NUMBER DEFAULT dbms_ra_misc.number2null('p4'),
   catalog_user_name IN VARCHAR2 DEFAULT NULL,
   wallet_alias IN VARCHAR2 DEFAULT NULL,
   wallet_path IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p1'),
   proxy_url IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p2'),
   proxy_port IN NUMBER DEFAULT dbms_ra_misc.number2null('p3'),
   http_timeout IN NUMBER DEFAULT NULL);

Parameters

Table 12-43 UPDATE_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the replication server configuration to update. This value is converted to upper-case before storing.
sbt_so_name	See CREATE_REPLICATION_SERVER.
sbt_parms	See CREATE_REPLICATION_SERVER.
max_streams	See CREATE_REPLICATION_SERVER. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
catalog_user_name	See CREATE_REPLICATION_SERVER.
wallet_alias	See CREATE_REPLICATION_SERVER.
wallet_path	See CREATE_REPLICATION_SERVER. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value. Path must start with file: .
proxy_url	See CREATE_REPLICATION_SERVER. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
proxy_port	See CREATE_REPLICATION_SERVER. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
http_timeout	See CREATE_REPLICATION_SERVER.

12.50 UPDATE_SBT_ATTRIBUTE_SET

This procedure updates the parameters for the specified SBT attribute set.

If a parameter is null, then its value remains unchanged, except as noted in the following parameter descriptions.

Syntax

PROCEDURE update_sbt_attribute_set(
   attribute_set_name IN VARCHAR2,
   streams IN NUMBER DEFAULT dbms_ra_misc.number2null('p1'),
   poolid IN NUMBER DEFAULT NULL,
   parms IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p2'),
   send IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p3'));

Parameters

Table 12-44 UPDATE_SBT_ATTRIBUTE_SET Parameters

Parameter	Description
attribute_set_name	The name of the SBT attribute set to update.
streams	See CREATE_SBT_ATTRIBUTE_SET. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
poolid	See CREATE_SBT_ATTRIBUTE_SET.
parms	See CREATE_SBT_ATTRIBUTE_SET. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
send	See CREATE_SBT_ATTRIBUTE_SET. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.

12.51 UPDATE_SBT_JOB_TEMPLATE

This procedure updates the parameters for the specified SBT job.

If a parameter is null, then its value remains unchanged, except as noted in the following parameter descriptions.

Syntax

PROCEDURE update_sbt_job_template (
   template_name IN VARCHAR2,
   attribute_set_name IN VARCHAR2 DEFAULT NULL,
   backup_type IN VARCHAR2 DEFAULT NULL,
   from_tag IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p1'),
   priority IN NUMBER DEFAULT NULL,
   copies IN NUMBER DEFAULT NULL,
   window IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_misc.intervalnull('p2'),
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-45 UPDATE_SBT_JOB_TEMPLATE Parameters

Parameter	Description
template_name	The name of the SBT job template to update.
attribute_set_name	See CREATE_SBT_JOB_TEMPLATE.
backup_type	See CREATE_SBT_JOB_TEMPLATE.
from_tag	See CREATE_SBT_JOB_TEMPLATE. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
priority	See CREATE_SBT_JOB_TEMPLATE.
copies	See CREATE_SBT_JOB_TEMPLATE.
window	See CREATE_SBT_JOB_TEMPLATE. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
compression_algorithm	see CREATE_SBT_JOB_TEMPLATE. If you do not specify this parameter or if you specify NULL, then the Recovery Appliance retains the existing value. If you specficy a value, then that becomes the new setting. Specify OFF to remove the compression algorithm from this template. This changes the value of COMPRESSION_ALGORITHM to NONE.
encryption_algorithm	see CREATE_SBT_JOB_TEMPLATE.

12.52 UPDATE_SBT_LIBRARY

This procedure modifies the parameters for the specified SBT library.

If a parameter is null, then its value remains unchanged, except as noted in the parms and send descriptions.

Syntax

PROCEDURE update_sbt_library (
   lib_name IN VARCHAR2,
   drives IN NUMBER DEFAULT NULL,
   restore_drives IN NUMBER DEFAULT NULL,
   parms IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p1'),
   send IN VARCHAR2 DEFAULT dbms_ra_misc.varchar2null('p2'));

Parameters

Table 12-46 UPDATE_SBT_LIBRARY Parameters

Parameter	Description
lib_name	The name of the SBT library whose parameters are to be modified.
drives	See CREATE_SBT_LIBRARY.
restore_drives	See CREATE_SBT_LIBRARY.
parms	See CREATE_SBT_LIBRARY. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.
send	See CREATE_SBT_LIBRARY. If you do not specify this parameter, then the Recovery Appliance retains the existing value. If you specify a value (including null), then the Recovery Appliance sets the new value.

12.53 UPDATE_STORAGE_LOCATION

This procedure allocates additional space for the specified storage location. You cannot reduce the amount of space used by a storage location.

Syntax

PROCEDURE update_storage_location (
   storage_location_name IN VARCHAR2,
   storage_location_dests IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-47 UPDATE_STORAGE_LOCATION Parameters

Parameter	Description
storage_location_name	The name of the storage location to update.
storage_location_dests	This parameter accepts a string in the same format as the corresponding parameter to CREATE_STORAGE_LOCATION. This parameter is optional and can contain any or none of the original disk groups. For each disk group specified in the storage_location_dests parameter, this procedure adds the disk group to this storage location (unless it is already part of the location), and adds the requested amount of additional space to the storage location. If no size was specified, then the Recovery Appliance allocates all of the free space in the disk group to this storage location. If a size is specified, and if it is greater than the amount of space already allocated from this disk group, then the Recovery Appliance allocates the specified amount of space to this storage location. Any new disk groups that you add to this storage location must have the same allocation unit size as the disk groups already allocated to this storage location. All existing disk groups that were previously added to this storage location remain allocated to this location, even if you do not explicitly specify them while running this procedure. In addition to processing any change to storage destinations, this procedure reexamines any disk groups specified without an explicit size when the storage location was previously created or updated. If additional free space is available in any of the reexamined disk groups, then the Recovery Appliance allocates this space to the storage location.