21 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 21-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. Do not perform parameter changes unless so instructed by Oracle Support for ZDLRA.
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_ARCHIVAL_BACKUP	This procedure copies all backup pieces from Recovery Appliance as restricted by user inputs to TAPE with the ability to recover the protected database to a user specified point described by restore_until_scn or restore_until_time.
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.
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. Regarding replicated and cloud pieces: the meta data is deleted from the Recovery Appliance doing the delete, but the data is not deleted from the downstream or cloud storage.
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.
ESTIMATE_SPACE	This procedure estimates the amount of storage in GB required for recovery of a given database and a desired recovery window.
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_DATABASE	This procedure pauses replication for the specified database with all associated replication servers. If replication_server_name is specified, replication for the one database/one replication server is paused.
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 set of incident log entries to have the status RESET. It takes multiple optional input parameters to allow bulk resetting of errors. When two or more input parameters are specified in a single RESET_ERROR call, only records that match all the input parameters specified together are 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_DB	This procedure restores a suspended database to normal operation. Only suspended databases may be resumed.
RESUME_REPLICATION_DATABASE	This procedure resumes replication for the specified database after a previous call to pause_replication_database.
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.
SUSPEND_DB	This procedure suspends deleting all local disk backups associated with this database from the Recovery Appliance. Backups on tape, in the cloud, or replicated to other Recovery Appliances are not affected.
UPDATE_ARCHIVAL_BACKUP_KEEP	This procedure makes updates the retention time of archival backup with the specified keep_until_time. Archival backup is identified by user specified restore_tag and restore_point.
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.

ABORT

Synonymous with ABORT_RECOVERY_APPLIANCE.

Syntax

PROCEDURE abort(
  comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-2 ABORT Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

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 any terminated backup and restore operations. To perform a clean shutdown, use SHUTDOWN_RECOVERY_APPLIANCE.

Syntax

PROCEDURE abort_recovery_appliance(
  comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-3 ABORT_RECOVERY_APPLIANCE Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

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

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 DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-4 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 the Recovery Appliance interprets the value as a number of bytes. reserved_space may be specified as a NULL if the controlling protection policy supports the autotune_reserved_space feature.
comments	Optional user supplied comment describing reason for executing this command.

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
   skip_initial_replication IN BOOLEAN DEFAULT FALSE,
   read_only IN BOOLEAN DEFAULT FALSE,
   request_only IN BOOLEAN DEFAULT FALSE
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-5 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.
skip_initial_replication	If set to TRUE, initial replication is skipped.
read_only	The setting that controls replication behavior to a downstream Recovery Appliance. If TRUE, then the Recovery Appliance treats the downstream replication server as a read only device. Specifically, backups are not replicated to the downstream replication server. Backups that exist on the downstream are restorable through the upstream Recovery Appliance. If FALSE or not specified, then the Recovery Appliance does the normal initial replication.
request_only	When adding a replication server to a protection polity with request_only set to TRUE, backups are not replicated to the downstream replication server. At startup time of the local Recovery Appliance, a calculation is made to determine which backups exist on the remote Recover Appliance and not locally. Those backups that exist remotely are requested to be sent from the downstream to the local Recovery Appliance. This feature requires that the two Recovery Appliances are paired with each other. If FALSE or not specified, the Recovery Appliance does normal replication.
comments	Optional user supplied comment describing reason for executing this command.

CONFIG

This procedure updates a value in the config table.

In software release 21.1, changes made to the config table are tracked, as well as default values, which are the "best values" that the Recovery Appliance is shipped with.

Syntax

PROCEDURE config(
   p_name VARCHAR2,
   p_value VARCHAR2,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-6 CONFIG Parameters

Parameter	Description
p_name	The parameter to update. Possible parameters are: check_files_days The frequency with which the Recovery Appliance runs the metadata consistency check in the background. The default frequency is 7 days. crosscheck_db_days The frequency with which the Recovery Appliance performs crosschecks of the recovery catalog to reflect actions in tape libraries or downstream Recovery Appliances. 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. group_log_max_count These are the maximum number of archive logs that are grouped into a single backup before being written to tape. The default is 1, which is equivalent to turning it off. group_log_backup_size_gb This is the maximum size allowed for an archive log backup created with archive log grouping. the default is 256 GB. validate_metadata_days The frequency with which the Recovery Appliance performs background metadata validation. 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 default is 100 percent. network_chunksize The message size that the Recovery Appliance uses for transferring backups between itself and protected databases. It is 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.
comments	Optional user supplied comment describing reason for executing this command.

COPY_BACKUP

This procedure copies one or more backup pieces from the Recovery Appliance to a 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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-7 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. If not specified, default format is RA_SBT_%d_%I_<SBT_job_template_key>_%U_<bs_key>.
template_name	The name of the SBT job library template. 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. Provides the highest level of compression with the most negative impact on CPU performance. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used.
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.
comments	Optional user supplied comment describing reason for executing this command.

COPY_BACKUP_PIECE

This procedure copies a single backup piece from the Recovery Appliance to a 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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-8 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. If not specified, default format is RA_SBT_%d_%I_<SBT_job_template_key>_%U_<bs_key>.
template_name	The name of the SBT job 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	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. Provides the highest level of compression with the most negative impact on CPU performance. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used.
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
comments	Optional user supplied comment describing reason for executing this command.

CREATE_ARCHIVAL_BACKUP

This procedure copies all backup pieces from Recovery Appliance as restricted by user inputs to TAPE with the ability to recover the protected database to a user specified point described by restore_until_scn, restore_until_time, or restore_point.

Backups created on TAPE using this API are KEEP backups and preserved until user specified keep_until_time.

Archival backups are validated using restore_point and restore_tag. If restore_point is not specified, it is generated internally. If restore_tag is not specified, tag values for archival backups will be the same as restore_point name.

Format for internally generated restore_point name is: <KEEP_BACKUP_><yyyyMMddHH24miSS>

This API has the following restrictions for input options:

• If a restore_point is specified and it doesn’t exist, then a new restore_point is created with the specified restore_point name. In this case, an additional input can be specified: either restore_until_scn or restore_until_time but not both.

• If a restore_point is specified and that restore_point exists, then the user cannot specify any additional input parameters.

• If the specified restore_until_time is not within the low_time and the high_time for the database, then this API returns an error

• The restore_until_time is the time up to which backups are needed. You should specify the timezone of the database, because that's what is used to determine which backups are to be copied to tape. Similarly, the keep_until_time should also specify the timezone of the database.

• If none of restore_until_scn, restore_until_time, or restore_point is specified, then archival backup is created by selecting the newest restorable backup.

• If restore_tag is already used to create archival backup for the specified db_unique_name database, this API returns an error.

Syntax

PROCEDURE CREATE_ARCHIVAL_BACKUP(
   db_unique_name IN VARCHAR2,
   from_tag IN VARCHAR2 DEFAULT NULL,
   compression_algorithm IN VARCHAR2 DEFAULT NULL,
   encryption_algorithm IN VARCHAR2 DEFAULT NULL,
   restore_point IN VARCHAR2 DEFAULT NULL,
   restore_until_scn      IN VARCHAR2 DEFAULT NULL,
   restore_until_time     IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
   attribute_set_name     IN VARCHAR2,
   format                 IN VARCHAR2 DEFAULT NULL,
   autobackup_prefix      IN VARCHAR2 DEFAULT NULL,
   restore_tag            IN VARCHAR2 DEFAULT NULL,
   keep_until_time        IN TIMESTAMP WITH TIME ZONE DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-9 CREATE_ARCHIVAL_BACKUP Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the protected database. If this is not specified, or if the state of this database associated with this name is not valid, this API returns with an error.
from_tag	If specified, recovery appliance only considers backups using this tag for copying to tape. If invalid from_tag is specified, then API returns with an error.
compression_algorithm	If the backup is already compressed, this parameter is ignored, otherwise the output backup files will be compressed using specified algorithm. If invalid algorithm is specified, then API returns with an error. 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. Provides the highest level of compression with the most negative impact on CPU performance. OFF: No compression. NULL: (default) existing value of compression algorithm is retained.
encryption_algorithm	If the backup is already encrypted, this parameter is ignored. Otherwise the output backup files will be encrypted using specified algorithm. Valid values are 'AES128', 'AES192', 'AES256', 'OFF', 'CLIENT', or the constant equivalents ENC_OFF, ENC_AES128, ENC_AES192, ENC_AES256, ENC_CLIENT. Note: A value of CLIENT or ENC_CLIENT requires the client to generate encrypted backups. Failure to do so will result in cloud backup job failures on the Recovery Appliance.
restore_point	User generated restore point name for which archival backups are created. If invalid restore point name is specified, this API returns an error..
restore_until_scn	User specified recovery SCN for which archival backups are created.
restore_until_time	User specified recovery time for which archival backups are created. Specify the timezone of the database.
attributre_set_name	User specified attribute set name. If an invalid attribute_set_name is specified, this returns an error.
format	The naming format of the output backup pieces. This parameter follows the same rules as the RMAN FORMAT parameter. If null, the default is defined by the queue_sbt_backup_task API.
autobackup_prefix	The original autobackup names will be given this prefix.
restore_tag	User specified tag for archival backups. If null, then tag values for archival backups will be the same as restore_point name.
keep_until_time	User specified retention time for the archival backup. If not specified, then the archival backup will be KEEP FOREVER backup. Specify the timezone of the database.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-10 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.
comments	Optional user supplied comment describing reason for executing this command.

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',
   log_compression_algorithm IN VARCHAR2 DEFAULT 'BASIC',
   autotune_reserved_space IN VARCHAR2 DEFAULT 'NO',
   autotune_space_limit IN VARCHAR2 DEFAULT NULL,
   recovery_window_compliance IN DSINTERVAL_UNCONSTRAINED DEFAULT NULL,
   keep_compliance IN VARCHAR2 'NO',
   max_reserved_space IN VARCHAR2 DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-11 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. If this parameter is null, the purge backup automatically is never run and backups are kept beyond their expiration date. 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 copies backup data to tape or cloud 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 to all libraries with the guaranteed_copy=YES. If hardware or network errors prevent timely copying, 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 for 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. 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 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. NO is the default. Refer to Managing Temporary Outages with a Backup and Redo Failover Strategy for more information.
log_compression_algorithm	The setting for the archive log compression feature. This setting is used to adjust the compression level of NZDL/polled archive log backups. OFF means that the archive logs will not be compressed. BASIC means the BASIC compression algorithm will be used to compress the backups. LOW means the LOW compression algorithm will be used to compress the backups. MEDIUM means the MEDIUM compression algorithm will be used to compress the backups. HIGH means the HIGH compression algorithm will be used to compress the backups. Advanced Compression Option (ACO) license is not required on the protected database for use of LOW, MEDIUM, and HIGH log compression settings. For more details on log compression usage, see ZDLRA: Changes in the Protection Policy Compression Algorithms (Doc ID 2654539.1).
autotune_reserved_space	This setting is used to control whether the Recovery Appliance will automatically define and update the reserved_space settings for databases associated with this policy. Even when this feature is enabled, initial and updated settings for reserved_space may still be supplied under the update_db API to override the automatic modifications of reserved_space for a period specified by the recovery_window_goal parameter. YES means that the Recovery Appliance will supply an initial reserved_space setting for a database if none is supplied. The Recovery Appliance will also tune settings daily based upon database space usage. NO means that the Recovery Appliance administrator is responsible for specifying and maintaining the reserved_space settings for databases associated with this protection policy. Do not use autotune_reserved_space with any of the compliance parameters: recovery_window_compliance or keep_compliance.
autotune_space_limit	This parameter limits unconstrained growth of reserved_space by the autotune reserved space feature when a storage location begins to fill. Autotune will not restrict reserved space growth when the total reserved space usage is below this specified limit. When the total reserved space usage is above this specified limit, autotune will restrict subsequent reserved_space growth to 10% per week for each database in the storage location. 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 If no unit is specified, then Recovery Appliance interprets the value as a number of bytes. This value may be set to NULL if there should never be restrictions on on reserved space growth through the autotune_reserved_space option.
recovery_window_compliance	This setting specifies for each database a range of backups that will not be deleted. These backups must not use more than disk_reserved_space bytes of storage, and if they do, new backups will be rejected until those backups age out of the range. Specify the window as any valid INTERVAL DAY TO SECOND expression, such as INTERVAL '4' HOUR (4 hours).
keep_compliance	This setting prevents someone from using RMAN CHANGE command to shrink the "keep until time" specified for an archival backup. YES means the "keep until time" for an archival backup may not be modified by the RMAN CHANGE command. If KEEP_COMPLIANCE is active, KEEP FOREVER backups will never be deleted. NO means the "keep until time" for an archival backup may be modified by the RMAN CHANGE command. NO is the default.
max_reserved_space	This parameter is the maximum disk_reserved_space permitted for each database supported by the protection policy 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 If no unit is specified, then Recovery Appliance interprets the value as a number of bytes. If max_reserved_space is specified as NULL, the disk_reserved_space setting for databases will not be restricted except that the sum of the reserved spaces for all databases must fit within the storage location.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-12 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. 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' Note: The system parameters SBT_LIBRARY, RA_WALLET, CREDENTIAL_ALIAS, PROXY_ULR, and PROXY_PORT must be specified through the create_replication_server parameters and not through sbt_parms.
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	Ignored. Automatically populated with the Recovery Appliance Catalog Owner.
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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-13 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.
comments	Optional user supplied comment describing reason for executing this command.

CREATE_SBT_JOB_TEMPLATE

This procedure creates an SBT job that describes how the Recovery Appliance chooses backups for copying to tape/cloud. 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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-14 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 of the 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. Provides the highest level of compression with the most negative impact on CPU performance. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used.
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
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-15 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   guaranteed IN VARCHAR2 DEFAULT 'NO',
   immutable IN VARCHAR2 DEFAULT 'NO',
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-16 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.
guaranteed	If YES, this library may be used as a backing store to support the GUARANTEED_COPY protection policy attribute.
immutable	If YES, this library may be used as a backing store to support the KEEP_COMPLIANCE protection policy attribute.
comments	Optional user supplied comment describing reason for executing this command.

DELETE_DB

This procedure deletes all local backups associated with this database from the Recovery Appliance. Backups on tape, in the cloud, or replicated are not affected.

If the Recovery Appliance cannot delete the local backups owned by this database due to errors, then the DELETE_DB operation fails. If 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 the DELETE_DB is called. If you diagnose the 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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-17 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.
comments	Optional user supplied comment describing reason for executing this command.

DELETE_POLLING_POLICY

This procedure deletes the specified backup polling policy.

Syntax

PROCEDURE delete_polling_policy (
   polling_policy_name IN VARCHAR2,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-18 DELETE_POLLING_POLICY Parameters

Parameter	Description
polling_policy_name	The name of the backup polling policy to delete.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-19 DELETE_PROTECTION_POLICY Parameters

Parameter	Description
protection_policy_name	The name of the protection policy to delete.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-20 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.
comments	Optional user supplied comment describing reason for executing this command.

DELETE_SBT_ATTRIBUTE_SET

This procedure deletes the specified SBT attribute set.

Syntax

PROCEDURE delete_sbt_attribute_set(
   attribute_set_name IN VARCHAR2,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-21 DELETE_SBT_ATTRIBUTE_SET Parameters

Parameter	Description
attribute_set_name	The name of the SBT attribute set to delete.
comments	Optional user supplied comment describing reason for executing this command.

DELETE_SBT_JOB_TEMPLATE

This procedure deletes the specified SBT job template.

Syntax

PROCEDURE delete_sbt_job_template (
   template_name IN VARCHAR2,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-22 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-23 DELETE_SBT_LIBRARY Parameters

Parameter	Description
lib_name	The name of the SBT library to delete.
comments	Optional user supplied comment describing reason for executing this command.

ESTIMATE_SPACE

This procedure estimates the amount of storage in GB required for recovery of a given database and a desired recovery window. It requires a database name and a desired recovery window.

Syntax

FUNCTION estimate_space (
   db_unique_name IN VARCHAR2,
   target_window IN DSINTERVAL_UNCONSTRAINED,
   comments IN VARCHAR2 DEFAULT NULL)
RETURN NUMBER;

Parameters

Table 21-24 ESTIMATE_SPACE Parameters

Parameter	Description
db_unique_name	The name of the database needing the storage estimate.
target_window	The desired recovery window for the database. 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.
comments	Optional user supplied comment describing reason for executing this command.
RETURNS	Gigabytes of space needed to achieve recoverability across the target_window.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-25 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.
comments	Optional user supplied comment describing reason for executing this command.

KEY_REKEY

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

Syntax

PROCEDURE key_rekey(,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-26 KEY_REKEY Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-27 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
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-28 KEY_REKEY Parameters

Parameter	Description
protection_policy_name	Generate new encryption keys for databases that are part of this protection policy.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-29 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.
comments	Optional user supplied comment describing reason for executing this command.

MOVE_BACKUP

This procedure moves one or more long-term archival backup pieces from the Recovery Appliance to an 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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-30 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. If not specified, default format is RA_SBT_%d_%I_<SBT_job_template_key>_%U_<bs_key>.
template_name	The name of the SBT job library template. 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. Provides the highest level of compression with the most negative impact on CPU performance. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used.
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
comments	Optional user supplied comment describing reason for executing this command.

MOVE_BACKUP_PIECE

This procedure moves a single long-term archival backup piece from the Recovery Appliance to an 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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-31 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. If not specified, default format is RA_SBT_%d_%I_<SBT_job_template_key>_%U_<bs_key>.
template_name	The name of the SBT job 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	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. Provides the highest level of compression with the most negative impact on CPU performance. OFF: No compression. NULL: (default) indicates that the algorithm defined in the SBT job template should be used.
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
comments	Optional user supplied comment describing reason for executing this command.

PAUSE_REPLICATION_DATABASE

This procedure pauses replication for the specified database with all associated replication servers. If replication_server_name is specified, replication for the one database/one replication server is paused.

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_DATABASE. No replication tasks that run against this database/Recovery Appliance can execute until you resume_replication_database for the specified database/downstream Recovery Appliance.

Syntax

PROCEDURE pause_replication_database (
   db_unique_name IN VARCHAR2,
   replication_server_name IN VARCHAR2 DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-32 PAUSE_REPLICATION_DATABASE Parameters

Parameter	Description
db_unique_name	The protected database for which to pause replication.
replication_server_name	If not null, replication is paused only for the one database on this specified replication server. If null, replication is paused for that database on all associated replication servers.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-33 PAUSE_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the downstream Recovery Appliance.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-34 PAUSE_SBT_LIBRARY Parameters

Parameter	Description
lib_name	Name of the SBT library to pause.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-35 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-36 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. If not specified, default format is RA_SBT_%d_%I_<SBT_job_template_key>_%U_<bs_key>.
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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-37 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-38 RENAME_DB Parameters

Parameter	Description
db_unique_name_old	The DB_UNIQUE_NAME to change.
db_unique_name_new	The new DB_UNIQUE_NAME.
comments	Optional user supplied comment describing reason for executing this command.

RESET_ERROR

This procedure modifies the specified set of incident log entries to have the status RESET. It takes multiple optional input parameters to allow bulk resetting of errors. When two or more input parameters are specified in a single RESET_ERROR call, only records that match all the input parameters specified together are 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# NUMBER DEFAULT NULL,
   error_code NUMBER DEFAULT NULL,
   error_text VARCHAR2 DEFAULT NULL,
   task_id NUMBER DEFAULT NULL,
   component VARCHAR2 DEFAULT NULL,
   low_time TIMESTAMP WITH TIME ZONE DEFAULT NULL,
   high_time TIMESTAMP WITH TIME ZONE DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-39 RESET_ERROR Parameters

Parameter	Description
incident#	The unique identifier of the incident log entry to reset.
error_code	The error code of the incident log entry to reset.
error_text	The text of the error message that completely or partially matches the incident log entry to reset.
task_id	The identifier for the task of the incident log entry to reset.
component	The component of the incident log entry to reset.
low_time
high_time	The low and high time with respect to last_seen column of the incident log entry to reset. If only one of them or neither of them are provided then the default values are used. The default value for low_time is the year 2000. The default value for high_time is systimestamp. Obtain the identifiers from the RA_INCIDENT_LOG view.
comments	Optional user supplied comment describing reason for executing this command.

RESUME_DB

This procedure restores a suspended database to normal operation. Only suspended databases may be resumed.

Suspended databases must be resumed before they can be backed up. A new reserved space value is required if the database is suspended in order to state how much space the newly reinstated database now requires. The reserved space value is not required if the protection policy for the database has autotune_reserved_space='YES'.

Syntax

PROCEDURE resume_db (
   db_unique_name IN VARCHAR2,
   reserved_space IN VARCHAR2 DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-40 RESUME_DB Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the database to be resumed.
reserved_space	Refer to ADD_DB
comments	Optional user supplied comment describing reason for executing this command.

RESUME_REPLICATION_DATABASE

This procedure resumes replication for the specified database after a previous call to pause_replication_database.

Syntax

PROCEDURE resume_replication_database (
   db_unique_name IN VARCHAR2,
   replication_server_name IN VARCHAR2 DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-41 RESUME_REPLICATION_DATABASE Parameters

Parameter	Description
db_unique_name	The protected database for which to pause replication.
replication_server_name	If not null, replication is resumed only for the one database on this specified replication server. If null, replication is resumed for that database on all associated replication servers.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-42 RESUME_REPLICATION_SERVER Parameters

Parameter	Description
replication_server_name	The name of the downstream Recovery Appliance.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-43 RESUME_SBT_LIBRARY Parameters

Parameter	Description
lib_name	Name of the SBT library to resume.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-44 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-45 SET_SYSTEM_DESCRIPTION Parameters

Parameter	Description
sys_desc	A descriptive name for this Recovery Applicance.
comments	Optional user supplied comment describing reason for executing this command.

SHUTDOWN

Synonymous with SHUTDOWN_RECOVERY_APPLIANCE.

Syntax

PROCEDURE shutdown(
  comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-46 SHUTDOWN Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

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(
  comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-47 SHUTDOWN_RECOVERY_APPLIANCE Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

STARTUP

Synonymous with STARTUP_RECOVERY_APPLIANCE.

Syntax

PROCEDURE startup(
  comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-48 STARTUP Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

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(
  comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-49 STARTUP_RECOVERY_APPLIANCE Parameters

Parameter	Description
comments	Optional user supplied comment describing reason for executing this command.

SUSPEND_DB

This procedure deletes all local disk backups associated with this database from the Recovery Appliance. Backups on tape, in the cloud, or replicated to other Recovery Appliances are not affected.

While a database is suspended, it will not accept backups. The database must be resumed before it can return to normal operation.

A suspended database does not have a reserved_space.

If the Recovery Appliance cannot delete the local backups owned by this database due to errors, then the SUSPEND_DB operation fails. If errors occur, then the specified database is not completely removed from the Recovery Appliance. The Recovery Appliance logs errors that occur during the SUSPEND_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 the SUSPEND_DB is called. If you diagnose the errors and fix the problem, then you can run SUSPEND_DB again.

Syntax

PROCEDURE suspend_db (
   db_unique_name IN VARCHAR2,
   wait IN BOOLEAN DEFAULT TRUE,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-50 SUSPEND_DB Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the database to be suspended.
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.
comments	Optional user supplied comment describing reason for executing this command.

UPDATE_ARCHIVAL_BACKUP_KEEP

This procedure updates the retention time of archival backup with the specified keep_until_time. Archival backup is identified by user specified restore_tag and restore_point.

This API has the following restrictions for input options:

• If restore point doesn't exist for the specified restore_tag and restore_point of the given database, this returns an error.

• If keep_compliance of the protection policy is set to YES and keep_until_time is less than the existing retention time of archival backup, this returns an error.

• If keep_compliance of the protection policy is set to YES and the backups are KEEP FOREVER, this returns an error.

Syntax

PROCEDURE update_archival_backup_keep(
   db_unique_name IN VARCHAR2,
   restore_tag IN VARCHAR2,
   restore_point IN VARCHAR2 DEFAULT NULL,
   restore_until_scn      IN VARCHAR2,
   keep_until_time     IN TIMESTAMP WITH TIME ZONE,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-51 UPDATE_ARCHIVAL_BACKUP_KEEP Parameters

Parameter	Description
db_unique_name	The DB_UNIQUE_NAME of the protected database. If this is not specified, or if the state of this database is not valid, this API returns with an error.
restore_tag	Specifies the user-defined tag of the archival backup.
restore_point	User specified restore point name of the archival backup.
keep_until_time	User specified retention time for the archival backup. If not specified, then the archival backup will be KEEP FOREVER backup. If KEEP_COMPLIANCE is active, KEEP FOREVER backups will never be deleted.
comments	Optional user supplied comment describing reason for executing this command.

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',
   skip_initial_replication IN BOOLEAN DEFAULT FALSE,
   compliance_hold IN TIMESTAMP WITH TIME ZONE DEFAULT dbms_ra_misc.tsnull('pl'),
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-52 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 the db_timezone. By default, this procedure updates the current incarnation. If the protected database administrator has not specified a db_timezone and this list contains the current incarnation key, then this procedure associates the time zone with the metadata for the current incarnation. If the time zone is set in the parameter file already for the incarnation, then the new db_timezone is ignored.
skip_initial_replication	If set to TRUE, the initial replication is skipped.
compliance_hold	The time from which backups may not be deleted from the Recovery Appliance or guaranteed tape or cloud storage. The database must be recoverable to the time specified by this compliance_hold. Specify the time as any valid TIMESTAMP WITH TIME ZONE expression, such as SYSTIMESTAMP - NUMTODSINTERVAL(7, 'DAY'), meaning "starting 7 days ago." If the database is being updated with compliance_hold, make sure that its associated protection policies do not have autotune_reserved_space configured.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-53 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   log_compression_algorithm IN VARCHAR2 DEFAULT NULL,
   autotune_reserved_space IN VARCHAR2 DEFAULT 'NO',
   autotune_space_limit IN VARCHAR2 DEFAULT NULL,
   recovery_window_compliance IN DSINTERVAL_UNCONSTRAINED DEFAULT dbms_ra_misc.intervalnull('p5'),
   keep_compliance IN VARCHAR2 'NO',
   max_reserved_space IN VARCHAR2 DEFAULT NULL,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-54 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.
log_compression_algorithm	See CREATE_PROTECTION_POLICY.
autotune_reserved_space	See CREATE_PROTECTION_POLICY. YES means that the Recovery Appliance will supply an initial reserved_space setting for a database if none is supplied. The Recovery Appliance will also tune settings daily based upon database space usage. NO means that the Recovery Appliance administrator is responsible for specifying and maintaining the reserved_space settings for databases associated with this protection policy. Do not use autotune_reserved_space with any of the compliance parameters: recovery_window_compliance or keep_compliance
autotune_space_limit	This parameter limits unconstrained growth of reserved_space by the autotune reserved space feature when a storage location begins to fill. Autotune will not restrict reserved space growth when the total reserved space usage is below this specified limit. When the total reserved space usage is above this specified limit, autotune will restrict subsequent reserved_space growth to 10% per week for each database in the storage location. 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 If no unit is specified, then Recovery Appliance interprets the value as a number of bytes. This value may be set to NULL if there should never be restrictions on on reserved space growth through the autotune_reserved_space option.
recovery_window_compliance	See CREATE_PROTECTION_POLICY. This setting specifies for each database a range of backups that will not be deleted. These backups must not use more than disk_reserved_space bytes of storage, and if they do, new backups will be rejected until those backups age out of the range. Specify the window as any valid INTERVAL DAY TO SECOND expression, such as INTERVAL '4' HOUR (4 hours).
keep_compliance	See CREATE_PROTECTION_POLICY. YES means the "keep until time" for an archival backup may not be modified by the RMAN CHANGE command. NO means the "keep until time" for an archival backup may be modified by the RMAN CHANGE command. NO is the default.
max_reserved_space	This parameter is the maximum disk_reserved_space permitted for each database supported by the protection policy 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 If no unit is specified, then Recovery Appliance interprets the value as a number of bytes. If max_reserved_space is specified as NULL, the disk_reserved_space setting for databases will not be restricted except that the sum of the reserved spaces for all databases must fit within the storage location.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-55 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.
comments	Optional user supplied comment describing reason for executing this command.

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'),
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-56 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.
comments	Optional user supplied comment describing reason for executing this command.

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,
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-57 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 a value is specified, it becomes the new setting. Specify OFF to remove the compression algorithm from this template. This changes the value of COMPRESSION_ALGORITHM to NONE. If you do not specify this parameter or if you specify NULL, then the Recovery Appliance retains the existing value.
encryption_algorithm	see CREATE_SBT_JOB_TEMPLATE.
comments	Optional user supplied comment describing reason for executing this command.

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'),
   guaranteed IN VARCHAR2 DEFAULT 'NO',
   immutable IN VARCHAR2 DEFAULT 'NO',
   comments IN VARCHAR2 DEFAULT NULL);

Parameters

Table 21-58 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.
guaranteed	If YES, this library may be used as a backing store to support the GUARANTEED_COPY protection policy attribute.
immutable	If YES, this library may be used as a backing store to support the KEEP_COMPLIANCE protection policy attribute.
comments	Optional user supplied comment describing reason for executing this command.