SET

Purpose

Use the SET command to control RMAN behavior within a job or session. Use CONFIGURE to configure options that persist across sessions.

Prerequisites

You can use the SET command either at the RMAN prompt or within a RUN block. When used at the RMAN prompt, changes made by SET persist until you exit the RMAN client (see setRmanOption). When used inside of a RUN block, changes made by SET persist until the end of the RUN block or the next SET command that changes the value of the same attribute (see setRunOption).

Syntax

set::=

Description of set.gif follows
Description of the illustration set.gif

(setRmanOption::=, setRunOption::=)

setRmanOption::=

Description of setrmanoption.gif follows
Description of the illustration setrmanoption.gif

(deviceSpecifier::=, formatSpec::=)

setRunOption::=

Description of setrunoption.gif follows
Description of the illustration setrunoption.gif

(deviceSpecifier::=, formatSpec::=, datafileSpec::=, tempfileSpec::=, untilClause::=)

setRmanOrRunOption::=

Description of setrmanorrunoption.gif follows
Description of the illustration setrmanorrunoption.gif

(deviceSpecifier::=, formatSpec::=)

Semantics

setRmanOption

This subclause specifies SET options that are usable outside of a RUN block.

Syntax Element Description

COMPRESSION ALGORITHM
'algorithm_name'		 Specifies the compression algorithm for backup sets. This command overrides the current CONFIGURE COMPRESSION ALGORITHM setting for the current RMAN session. The default compression algorithm is BZIP2.

Specify either ZLIB or BZIP2 (default). ZLIB compression is very fast but has a compression ratio that is not as good as other algorithms. BZIP2 has a very good compression ratio, but is somewhat slow. In short, the ZLIB algorithm is faster than BZIP2, but this improvement in speed is obtained at the cost of a slightly worse compression ratio. The COMPATIBLE initialization parameter must be set to 11.0.0 or higher for ZLIB compression, which requires the Oracle Advanced Compression option.

Note: The view V$RMAN_COMPRESSION_ALGORITHM describes supported algorithms.

DECRYPTION
IDENTIFIED BY password		 Specifies one or more decryption passwords to be used when reading dual-mode or password-encrypted backups.

Password-encrypted backups require the correct password to be entered before they can be restored. When RMAN reads an encrypted backup piece, it tries each password in the list until it finds the correct one to decrypt this backup piece. RMAN signals an error if none of the specified keys work.

Note: If restoring from a group of backups created with different passwords, then specify all of the required passwords on the SET DECRYPTION command. RMAN will automatically use the correct password with each backup set.

See Also: "Encryption of Backup Sets"
ECHO {OFF | ON} Controls whether RMAN commands appear in the message log. When reading commands from a command file, RMAN automatically echoes them to the message log. When reading commands from standard input, by default RMAN does not echo these commands to the message log. To force RMAN to echo the commands, run the SET ECHO ON command before running your command file. Run SET ECHO OFF to disable echoing to the command log.

The command is useful when stdin and stdout have been redirected. For example, in UNIX you can redirect RMAN's input and output in this manner:

% rman TARGET / < in_file > out_file

By including SET ECHO ON in the in_file, you enable the commands contained in in_file to be visible in out_file.
ENCRYPTION Specifies encryption-related options that apply to BACKUP commands that create backup sets for the duration of the RMAN session.

See Also: "Encryption of Backup Sets"

   ALGORITHM
   'algorithm_name'		 Specifies the algorithm used during this RMAN session. Overrides the configured default encryption algorithm specified by CONFIGURE ALGORITHM. Possible values are listed in V$RMAN_ENCRYPTION_ALGORITHMS.

   IDENTIFIED BY
   password [ONLY]		 Specifies whether to employ a user-specified password in backup encryption according to the following rules:

  • Omit IDENTIFIED BY password clause to specify transparent-mode encrypted backups.

  • Use IDENTIFIED BY password ONLY to specify password-mode encrypted backups.

  • Use IDENTIFIED BY password without ONLY to specify dual-mode encrypted backups.

Create a password that is secure. See Oracle Database Security Guide for more information.

Note that if the password is not surrounded by quotes, then it is translated internally into upper case. Thus, the following clauses are all synonyms for IDENTIFIED BY "SOMEPWD":

  • IDENTIFIED BY somepwd

  • IDENTIFIED BY Somepwd

  • IDENTIFIED BY sOmEpWd

Caution: Wallet-based encryption is more secure than password-based encryption because no passwords are involved. You should use password-based encryption only when absolutely necessary because your backups need to be transportable.

See Also: "Encryption of Backup Sets" for details on the different encryption modes
   {OFF | ON} Specifies whether to encrypt backup sets. If ON, then the default is to encrypt backup sets. If OFF, then the default is not to encrypt backup sets.

This option overrides settings made with the CONFIGURE ENCRYPTION FOR command. If no datafiles are configured for encryption, then you must explicitly use ON to encrypt required datafiles.

If FOR ALL TABLESPACES is not specified, then this setting controls encryption of backups for tablespaces where CONFIGURE ENCRYPTION FOR TABLESPACE tablespace_name has not been used to control encryption behavior.
   FOR ALL TABLESPACES Controls encryption for all tablespaces, overriding any CONFIGURE ENCRYPTION FOR TABLESPACE tablespace_name setting.

setRunOption

This subclause specifies SET options that are usable within a RUN block.

Syntax Element Description

ARCHIVELOG DESTINATION
TO 'log_archive_dest'		 Overrides the LOG_ARCHIVE_DEST_1 initialization parameter in the target database when forming names for restored archived redo logs during subsequent RESTORE and RECOVER commands. RMAN restores the logs to the destination specified in 'log_archive_dest'.

You can use this command to stage archived logs to different locations while restoring a database. RMAN knows where to find the newly restored archived logs; it does not require them to be in the destination specified by LOG_ARCHIVE_DEST_1. For example, if you specify a different destination from the one in the parameter file and restore archived log backups, subsequent restore and recovery operations detect this new location.

Use this parameter to restore archived redo logs that are not already on disk. RMAN always looks for logs on disk first before restoring them from backups.
BACKUP COPIES integer Specifies the number of copies of each backup piece that the channels should create: 1, 2, 3, or 4 (see Example 2-136).

RMAN can duplex backups to either disk or tape but cannot duplex backups to tape and disk simultaneously. When backing up to tape, ensure that the number of copies does not exceed the number of available tape devices. Also, if BACKUP COPIES is greater than 1, then the BACKUP_TAPE_IO_SLAVES initialization parameter must be enabled on the target database.

The SET BACKUP COPIES command affects all BACKUP commands in the RUN block issued after SET BACKUP COPIES (but not before) and is in effect until explicitly disabled or changed. The SET BACKUP COPIES command affects only BACKUP commands, but does not apply to the BACKUP AS COPY command.

The SET BACKUP COPIES command affects all channels allocated in the session. The order of precedence is as follows, with settings higher on the list overriding settings lower on the list:

BACKUP COPIES

SET BACKUP COPIES

CONFIGURE ... BACKUP COPIES

The names of the backup pieces are dependent on the FORMAT clause in the BACKUP command. You can specify up to four FORMAT strings. RMAN uses the second, third, and fourth values only when BACKUP COPIES, SET BACKUP COPIES, or CONFIGURE ... BACKUP COPIES is in effect. When choosing which format to use for each backup piece, RMAN uses the first format value for copy 1, the second format value for copy 2, and so on. If the number of format values exceeds the number of copies, then the extra formats are not used. If the number of format values is less than the number of copies, RMAN reuses the format values, starting with the first one.

Note: BACKUP COPIES option is not valid when files are created in flash recovery area. Backups to the flash recovery area cannot be duplexed.

Note: Control file autobackups on disk are a special case and are never duplexed: RMAN always writes one and only copy.

MAXCORRUPT
FOR DATAFILE datafileSpec
TO integer		 Sets a limit on the number of previously undetected block corruptions that the database will permit in a specified datafile or group of datafiles. The default limit is zero, meaning that RMAN tolerates no corrupt blocks.

The SET MAXCORRUPT command specifies the total number of physical and logical corruptions permitted in a datafile during a backup job. If the sum of physical and logical corruptions detected for a datafile is no more than its MAXCORRUPT setting, then the BACKUP command completes. If more than MAXCORRUPT corrupt blocks exist, then RMAN terminates without creating output files.

Whether or not the MAXCORRUPT limit is exceeded, RMAN populates the V$DATABASE_BLOCK_CORRUPTION view with any corrupt block ranges that it finds. However, a backup or restore job is terminated after MAXCORRUPT+1 corrupt blocks are found, so in this case RMAN only records MAXCORRUPT+1 corruptions. Any block corruptions beyond the point at which the backup job terminated are not recorded.

Note: If you specify CHECK LOGICAL, then the MAXCORRUPT limit applies to the sum of logical and physical corruptions detected. Otherwise, MAXCORRUPT only applies to the number of physical block corruptions.

See Also: datafileSpec

NEWNAME FOR
DATAFILE datafileSpec		 Sets the default name for all subsequent RESTORE or SWITCH commands that affect the specified datafile. If you do not issue this command before the datafile restore operation, then RMAN restores the file to its default location.

After you restore a datafile to a new location, then you can run SWITCH to rename the file in the control file to the NEWNAME. If you do not run SWITCH, then the restored file is recorded as a datafile copy in the repository.

You cannot use SET NEWNAME TO NEW when creating a duplicate or standby database or performing RMAN TSPITR.

Note: The SET NEWNAME command supports ASM disk groups.

See Also: datafileSpec

NEWNAME FOR
TEMPFILE tempfileSpec		 Sets the new tempfile name for a subsequent SWITCH command that renames the specified tempfile to the specified name.

You cannot use SET NEWNAME TO NEW when creating a duplicate or standby database or performing RMAN TSPITR.

Note: The SET NEWNAME command supports ASM disk groups.

See Also: tempfileSpec
   TO 'filename' Specifies a user-defined filename or Automatic Storage Management disk group for the restored datafile or tempfile. If you set the NEWNAME to a disk group for a datafile and run a RESTORE, then RMAN restores the file to the disk group. If you specify a filename for a tempfile, then this will the new name of the tempfile after the database is recovered and opened.
   TO NEW Creates an Oracle-managed file in the directory specified in DB_CREATE_FILE_DEST. If the original file is an Oracle-managed file or is on an Automatic Storage Management disk group, then RMAN attempts to delete the original file. If you specify TO NEW for a tempfile, then the tempfile is created in DB_CREATE_FILE_DEST when the database is opened.

You cannot use this option when using the DUPLICATE command or performing RMAN TSPITR.

See Also: Oracle Database Administrator's Guide for information about Oracle-managed files

TO RESTORE POINT
restore_point_name		 Specifies a restore point for a subsequent RESTORE or RECOVER command, with the SCN at which the restore point was created as the upper, inclusive limit. Because the limit is inclusive, RMAN selects only files that can be used to restore or recover up to and including the SCN corresponding to the restore point.

Note: You can only use SET TO RESTORE POINT when the database is mounted, because the defined restore points are recorded in the control file. For example, you cannot use SET TO RESTORE POINT to specify the target SCN for a RESTORE CONTROLFILE operation.
untilClause Specifies an end time, SCN, or log sequence number for a subsequent RESTORE or RECOVER command.

See Also: untilClause

setRmanOrRunOption

This subclause specifies SET options that are usable inside or outside of a RUN block.

Syntax Element Description

AUXILIARY INSTANCE PARAMETER
FILE TO 'filename'		 Specifies the path to the parameter file to use in starting the instance. You can use this parameter when customizing TSPITR with an automatic auxiliary instance or when cloning RMAN tablespaces with RMAN.

Note: The filename is on the host running the RMAN client.

See Also: Oracle Database Reference for more on V$SESSION.CLIENT_INFO
COMMAND ID TO 'string' Enters the specified string into the V$SESSION.CLIENT_INFO column of all channels. Use this information to determine which database server sessions correspond to which RMAN channels. The SET COMMAND ID command applies only to channels that are already allocated.

The V$SESSION.CLIENT_INFO column contains information for each RMAN server session. The data appears in one of the following formats:

  • id=string

  • id=string, ch=channel_id

The first form appears in the RMAN target database connection. The second form appears in all allocated channels. When the current job is complete, the V$SESSION.CLIENT_INFO column will be cleared.

See Also: Oracle Database Reference for more on V$SESSION.CLIENT_INFO

CONTROLFILE AUTOBACKUP
FORMAT FOR DEVICE TYPE
deviceSpecifier
TO formatSpec		 Overrides the default filename format for the control file autobackup on the specified device type. You can use this command either in RUN or at the RMAN prompt. The order of precedence is as follows:

SET CONTROLFILE AUTOBACKUP executed within a RUN block

SET CONTROLFILE AUTOBACKUP executed at the RMAN prompt

CONFIGURE CONTROLFILE AUTOBACKUP FORMAT

The %F substitution variable is required to be in the new formatSpec. No other substitution variable is valid in a control file autobackup formatSpec.

See Also: formatSpec for the semantics of the %F substitution variable
DBID integer Specifies the DBID, which is a unique 32-bit identification number computed when the database is created.

RMAN displays the DBID upon connection to the target database. You can obtain the DBID by querying the V$DATABASE view or the RC_DATABASE and RC_DATABASE_INCARNATION recovery catalog views.

You should only run the SET DBID command in the following specialized circumstances:

  • You are not connected to a recovery catalog and want to restore the control file (see Example 2-137). The same restriction applies when you use the Data Recovery Advisor to restore a control file autobackup. CONFIGURE can locate an autobackup and restore it only if SET DBID is issued before ADVISE FAILURE.

  • You want to restore the server parameter file (see Example 2-138).

  • You are connected to the recovery catalog but not the target database and use the FOR DB_UNIQUE_NAME option on the CONFIGURE, LIST, REPORT, SHOW, or UNREGISTER commands.

Examples

Example 2-135 Setting the Command ID

This example sets the command ID to rman, backs up the database, and then archives the online redo logs. You can use the command ID to query V$SESSION with WHERE LIKE '%rman%' for job status information.

RUN
{
  ALLOCATE CHANNEL d1 DEVICE TYPE DISK FORMAT '/disk1/%U';
  ALLOCATE CHANNEL d2 DEVICE TYPE DISK FORMAT '/disk2/%U';
  SET COMMAND ID TO 'rman';
  BACKUP INCREMENTAL LEVEL 0 DATABASE;
  SQL 'ALTER SYSTEM ARCHIVE LOG CURRENT';
}

Example 2-136 Duplexing a Backup Set

Assume that the current duplexing configuration is as follows:

CONFIGURE ARCHIVELOG COPIES FOR DEVICE TYPE sbt TO 3;
CONFIGURE DATAFILE COPIES FOR DEVICE TYPE sbt TO 3;

One of the tape drives goes bad, leaving only two available. The guideline for tape backups is that the number of devices should equal the number of copies multiplied by the number of channels. The following example overrides the persistent duplexing configuration with SET BACKUP COPIES and writes two copies of a database backup to the two functioning tape drives:



RUN
{
  ALLOCATE CHANNEL dev1 DEVICE TYPE sbt
    PARMS 'ENV=(OB_DEVICE_1=stape1,OB_DEVICE_2=stape2)';
  SET BACKUP COPIES 2;
  BACKUP DATABASE PLUS ARCHIVELOG;
}

Example 2-137 Setting the Control File Autobackup Format During a Restore

Assume that the disk containing the control file fails. You edit the CONTROL_FILES parameter in the initialization parameter file to point to a new location.

In this example, you do not have access to a recovery catalog. The example starts the instance, sets the DBID, and then restores a control file autobackup. After the database is mounted, you can recover the database.

CONNECT TARGET /
STARTUP FORCE NOMOUNT
SET DBID 28014364;
RUN
{
  SET CONTROLFILE AUTOBACKUP FORMAT FOR DEVICE TYPE DISK TO '/disk2/cf_%F.bak';
  RESTORE CONTROLFILE FROM AUTOBACKUP MAXSEQ 100;
}
ALTER DATABASE MOUNT;
RECOVER DATABASE;
ALTER DATABASE OPEN RESETLOGS;

Example 2-138 Restoring the Server Parameter File

Assume that the database is shut down while maintenance is being performed on the database host. During this time, the server parameter file is accidentally deleted. You start the RMAN client, CONNECT as TARGET to the database, and connect to the recovery catalog. The following example restores a server parameter file from an autobackup on tape and then restarts the instance.

SET DBID 3257174182;  # set dbid so RMAN can identify the database
STARTUP FORCE NOMOUNT # RMAN starts database with a dummy server parameter file
RUN
{
  ALLOCATE CHANNEL t1 DEVICE TYPE sbt;
  RESTORE SPFILE FROM AUTOBACKUP;
}
STARTUP FORCE; # RMAN restarts database with restored server parameter file