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 procedures in different sessions at the same time fail with an appropriate message.

Table 12-1 summarizes the available DBMS_RA subprograms.

Table 12-1 DBMS_RA 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 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 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. 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.
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.
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 SBT destination.
MOVE_BACKUP_PIECE	This procedure moves a single long-term archival backup piece from the Recovery Appliance to a user-specified 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.
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 jobs) that have started but not completed. When the Recovery Appliance restarts, it automatically resumes or restarts backup operations. You must manually restart 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 adding the protected database with ADD_DB, granting access to this database to a Recovery Appliance user account (GRANT_DB_ACCESS), and 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

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.

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

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 `14` 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 reordering 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 `14` 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 if `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 default is `50` percent. `network_chunksize` The message size that the Recovery Appliance uses for transferring backups between itself and protected databases. 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 more quickly if a failure occurs.
`p_value`	The new value for the parameter.

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 14 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 reordering 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 14 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 if 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 default is 50 percent.
network_chunksize

The message size that the Recovery Appliance uses for transferring backups between itself and protected databases. 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 more quickly 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 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);

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. 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`	The compression algorithm to use for this copy backup operation. Use one of the following to override the compression algorithm specified in the SBT job template: `BASIC`: Good compression ratios with potentially lower speed than `MEDIUM`. `LOW`: Optimized for speed with potentially lower compression ratios 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 tape throughput. `OFF`: No compression. `NULL` (the default) indicates that the algorithm defined in the SBT job template should be used. `LOW`, `MEDIUM`, and `HIGH` are Advanced Compression Options which require additional licensing on the protected database for restore operations. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

12.7 COPY_BACKUP_PIECE

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

Syntax

PROCEDURE copy_backup_piece (
   bp_key IN NUMBER,
   format IN VARCHAR2,
   template_name IN VARCHAR2,
   compression_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. 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`	The compression algorithm to use for this copy backup operation. Use one of the following to override the compression algorithm specified in the SBT job template: `BASIC`: Good compression ratios with potentially lower speed than `MEDIUM`. `LOW`: Optimized for speed with potentially lower compression ratios 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 tape throughput. `OFF`: No compression. `NULL` (the default) indicates that the algorithm defined in the SBT job template should be used. `LOW`, `MEDIUM`, and `HIGH` are Advanced Compression Options which require additional licensing on the protected database for restore operations. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

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`	The setting that controls whether RMAN backups for databases that use this protection policy can be deleted. Specifying `NO` means that the Recovery Appliance does not allow deletion of these backups. The default is `YES`. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.7 and later.
`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 alternate 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 default is `NO`. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later. See the “Managing Temporary Outages with a Backup and Redo Failover Strategy” section for information about the Backup and Redo Failover feature.

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.
`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. Each replication task processes a single backup piece. 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`	Always specify `RASYS`.
`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).
`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);

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 full backup, if it has not already been copied to tape. The backup can be either the most recent level 0 backup received, or a virtual full backup 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. See Also: Oracle Database Backup and Recovery Reference for the correct format for TAG strings
`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`	The compression algorithm to use for this SBT job: `BASIC`: Good compression ratios with potentially lower speed than `MEDIUM`. `LOW`: Optimized for speed with potentially lower compression ratios 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 tape throughput. `NULL`: No compression. `LOW`, `MEDIUM`, and `HIGH` are Advanced Compression Options which require additional licensing on the protected database for restore operations. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

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

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

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

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.

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 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-24 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.26 MOVE_BACKUP

This procedure moves one or more long-term archival backup pieces, that is, backups created using the RMAN BACKUP ... KEEP command, from the Recovery Appliance to a user-specified 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);

Parameters

Table 12-25 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. 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`	The compression algorithm to use for this move backup operation. Use one of the following to override the compression algorithm specified in the SBT job template: `BASIC`: Good compression ratios with potentially lower speed than `MEDIUM`. `LOW`: Optimized for speed with potentially lower compression ratios 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 tape throughput. `OFF`: No compression. `NULL` (the default) indicates that the algorithm defined in the SBT job template should be used. `LOW`, `MEDIUM`, and `HIGH` are Advanced Compression Options which require additional licensing on the protected database for restore operations. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

12.27 MOVE_BACKUP_PIECE

This procedure moves a single long-term archival backup piece from the Recovery Appliance to a user-specified 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);

Parameters

Table 12-26 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. 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`	The compression algorithm to use for this move backup operation. Use one of the following to override the compression algorithm specified in the SBT job template: `BASIC`: Good compression ratios with potentially lower speed than `MEDIUM`. `LOW`: Optimized for speed with potentially lower compression ratios 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 tape throughput. `OFF`: No compression. `LOW`, `MEDIUM`, and `HIGH` are Advanced Compression Options which require additional licensing on the protected database for restore operations. `NULL` (the default) indicates that the algorithm defined in the SBT job template should be used. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

12.28 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-27 PAUSE_REPLICATION_SERVER Parameters

Parameter	Description
`replication_server_name`	The name of the downstream Recovery Appliance.

12.29 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-28 PAUSE_SBT_LIBRARY Parameters

Parameter	Description
`lib_name`	Name of the SBT library to pause.

12.30 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-29 POPULATE_BACKUP_PIECE Parameters

Parameter Description

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.

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

Parameters

Table 12-30 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. See `CREATE_SBT_JOB_TEMPLATE`.

12.32 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-31 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.33 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-32 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.34 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-33 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.35 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-34 RESUME_REPLICATION_SERVER Parameters

Parameter	Description
`replication_server_name`	The name of the downstream Recovery Appliance.

12.36 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-35 RESUME_SBT_LIBRARY Parameters

Parameter	Description
`lib_name`	Name of the SBT library to resume.

12.37 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-36 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.38 SHUTDOWN

Synonymous with SHUTDOWN_RECOVERY_APPLIANCE.

Syntax

PROCEDURE shutdown;

12.39 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. See Zero Data Loss Recovery Appliance Administrator's Guide to learn how to shut down the Recovery Appliance.

Syntax

PROCEDURE shutdown_recovery_appliance;

12.40 STARTUP

Synonymous with STARTUP_RECOVERY_APPLIANCE.

Syntax

PROCEDURE startup;

12.41 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. See Zero Data Loss Recovery Appliance Owner's Guide to learn how to start up the Recovery Appliance.

Syntax

PROCEDURE startup_recovery_appliance;

12.42 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-37 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.43 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-38 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.44 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_int.varchar2null('p1'),
   recovery_window_goal IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   max_retention_window IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_int.intervalnull('p3'),
   recovery_window_sbt IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_int.intervalnull('p2'),
   unprotected_window IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_int.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-39 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`. 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. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.7 and later.
`store_and_forward`	See `CREATE_PROTECTION_POLICY`. If you do not specify this parameter (or if you specify null), then the policy retains the existing value. If you specify a value, then the Recovery Appliance sets the new value. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

12.45 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_int.number2null('p4'),
   catalog_user_name IN VARCHAR2 DEFAULT NULL,
   wallet_alias IN VARCHAR2 DEFAULT NULL,
   wallet_path IN VARCHAR2 DEFAULT dbms_ra_int.varchar2null('p1'),
   proxy_url IN VARCHAR2 DEFAULT dbms_ra_int.varchar2null('p2'),
   proxy_port IN NUMBER DEFAULT dbms_ra_int.number2null('p3'),
   http_timeout IN NUMBER DEFAULT NULL);

Parameters

Table 12-40 UPDATE_REPLICATION_SERVER Parameters

Parameter	Description
`replication_server_name`	The name of the replication server configuration to update.
`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.
`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.46 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_int.number2null('p1'),
   poolid IN NUMBER DEFAULT NULL,
   parms IN VARCHAR2 DEFAULT dbms_ra_int.varchar2null('p2'),
   send IN VARCHAR2 DEFAULT dbms_ra_int.varchar2null('p3'));

Parameters

Table 12-41 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.47 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_int.varchar2null('p1'),
   priority IN NUMBER DEFAULT NULL,
   copies IN NUMBER DEFAULT NULL,
   window IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_int.intervalnull('p2'),
   compression_algorithm IN VARCHAR2 DEFAULT NULL);

Parameters

Table 12-42 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 specify a value, then the Recovery Appliance sets the new value. Specify `OFF` to remove the compression algorithm from this template. This changes the value of `COMPRESSION_ALGORITHM` to `NONE`. Note that this parameter is available only with Zero Data Loss Recovery Appliance software update 12.1.1.1.8 and later.

12.48 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_int.varchar2null('p1'),
   send IN VARCHAR2 DEFAULT dbms_ra_int.varchar2null('p2'));

Parameters

Table 12-43 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.49 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-44 UPDATE_STORAGE_LOCATION Parameters

Parameter Description

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 re-examines 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.

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 re-examines 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.