1 About RMAN Commands

This chapter includes the following topics:

Structure of RMAN Command Entries
RMAN Syntax Diagrams
Format of RMAN Commands
RMAN Reserved Words
Summary of RMAN Commands
Summary of RMAN Subclauses

Structure of RMAN Command Entries

All RMAN commands in Chapter 2, "RMAN Commands" are organized into the following sections:

Purpose This section provides a brief description of the command and the most common circumstances in which it is used.

Prerequisites This section lists the prerequisites for using the command.

Usage Notes This optional section provides general notes about using the command. Notes specific to a command option are included with the option description.

Syntax The syntax diagrams show the keywords and parameters that make up the statement.

Caution:

Not all keywords and parameters are valid in all circumstances. Be sure to refer to the "Semantics" section of each statement and clause to learn about any restrictions on the syntax.

Semantics

This section describes the purpose of the keywords, parameter, and clauses that make up the syntax, as well as restrictions and other usage notes that may apply to them. The conventions for keywords and parameters used in this chapter are explained in

"Conventions".

Examples This section shows how to use the various clauses and parameters of the statement.

Optional sections following the examples provide more information on how and when to use the statement.

RMAN Syntax Diagrams

Syntax descriptions are provided in this book for RMAN command-line constructs in graphic form or Backus Naur Form (BNF). See Oracle Database SQL Language Reference for general information about how to interpret syntax diagrams and BNF notation. This section explains RMAN conventions exclusively.

Recovery Manager syntax diagrams use lines and arrows to show syntactic structure, as shown in the following example for the CATALOG command.

catalog::=

Description of the illustration catalog.gif

This section describes the components of syntax diagrams and gives examples of how to write RMAN commands. Syntax diagrams are made up of these items:

Keywords in RMAN Syntax
Placeholders in RMAN Syntax
Quotes in RMAN Syntax

Keywords in RMAN Syntax

Keywords have special meanings in Recovery Manager syntax. In the syntax diagrams, keywords appear in rectangular boxes and an uppercase font, like the word CATALOG in the example diagram. When used in text and code examples, RMAN keywords appear in uppercase, monospace font, for example, CATALOG DATAFILECOPY. You must use keywords in RMAN statements exactly as they appear in the syntax diagram, except that they can be either uppercase or lowercase.

Placeholders in RMAN Syntax

Placeholders in syntax diagrams indicate non-keywords. In the syntax diagrams, they appear in ovals, as in the word integer in the example diagram. When described in text, RMAN placeholders appear in lowercase italic, for example, 'filename'. Placeholders are usually:

Names of database objects (tablespace_name)
Oracle datatype names (date_string)
Subclauses (datafileSpec)

When you see a placeholder in a syntax diagram, substitute an object or expression of the appropriate type in the RMAN statement. For example, to write a DUPLICATE TARGET DATABASE TO 'database_name' command, use the name of the duplicate database you want to create, such as dupdb, in place of the database_name placeholder in the diagram.

The only system-independent, legal environment variables in RMAN quoted strings are a question mark (?) for the Oracle home and an at-sign (@) for the SID. However, you can use operating system-specific environment variables on the target system within quoted strings. The environment variables are interpreted by the database server and not the RMAN client.

The following table shows placeholders that appear in the syntax diagrams and provides examples of the values you might substitute for them in your statements.

Placeholder	Description	Examples
Quoted strings such as '`filename`', '`tablespace_name`', '`channel_name`', '`channel_parms`'	A string of characters contained in either single or double quotes. A quoted string may contain white space, punctuation, and RMAN and SQL keywords.	`"?/dbs/cf.f"` `'dev1'`
Nonquoted strings such as `channel_id`, `tag_name`, `date_string`	A sequence of characters containing no white space and no punctuation characters and starting with an alphabetic character.	`ch1`
`integer`	Any sequence of only number characters.	`67843`

Quotes in RMAN Syntax

The RMAN syntax diagrams shows some placeholder values enclosed in required or optional quotes. The syntax diagrams show single quotes, though in all cases double quotes are also legal in RMAN syntax. For example, you may specify either 'filename' or "filename". For the SQL command, it is recommended that you use double quotes because the SQL statement itself may also contain a quote, and the most common type of quote in a SQL statement is a single quote. Single and double quotes do not mean the same in SQL as they do in RMAN.

Format of RMAN Commands

The RMAN language is free-form. Keywords must be separated by at least one white space character (such as a space, tab, or line break). An RMAN command starts with a keyword corresponding to one of the commands described in Chapter 2, "RMAN Commands", followed by arguments and ending with a semicolon, as shown in the syntax diagrams. The following example shows an RMAN backup command:

BACKUP DATABASE;

A command can span multiple lines. For example, you can rewrite each keyword in the preceding command on a separate line as follows:

BACKUP
  DATABASE
;

You can insert a comment by using a pound (#) character at any point in a line. After the # character, the remainder of the line is ignored. For example:

# run this command once each day
BACKUP INCREMENTAL LEVEL 1 
  FOR RECOVER OF COPY      # using incrementally updated backups
  WITH TAG "DAILY_BACKUP"  # daily backup routine
  DATABASE;

RMAN Reserved Words

The RMAN language contains a number of reserved words, which are or have been used in RMAN commands. Table 1-1 lists all of the current reserved words.

Table 1-1 RMAN Reserved Words

A-C	C-D	D-L	L-P	P-S	S-W
`,`	`CHANGE`	`DURATION`	`LOGSEQ`	`PARALLELMEDIARESTORE`	`SECTION`
`#`	`CHANNEL`	`ECHO`	`LOGS`	`PARALLEL`	`SEND`
`(`	`CHECKSYNTAX`	`ENCRYPTION`	`LOG`	`PARAMETER`	`SEQUENCE`
`)`	`CHECK`	`EXCLUDE`	`LOGSCN`	`PARAMETER_VALUE_CONVERT`	`SETLIMIT`
`\`	`CLEAR`	`EXECUTE`	`LOW`	`PARMS`	`SETSIZE`
`{`	`CLONENAME`	`EXIT`	`MAINTENANCE`	`PARTIAL`	`SET`
`}`	`CLONE`	`EXPIRED`	`MASK`	`PASSWORD`	`SHIPPED`
`<<<`	`CLONE_CF`	`EXPORT`	`MAXCORRUPT`	`PFILE`	`SHOW`
`>>>`	`CLOSED`	`FAILOVER`	`MAXDAYS`	`PIPE`	`SHUTDOWN`
`;`	`CMDFILE`	`FAILURE`	`MAXOPENFILES`	`PLATFORM`	`SINCE`
`&`	`COMMAND`	`FILESPERSET`	`MAXPIECESIZE`	`PLSQL`	`SIZE`
`_`	`COMMENT`	`FILES`	`MAXSEQ`	`PLUS`	`SKIP`
`'`	`COMPATIBLE`	`FILES`	`MAXSETSIZE`	`POINT`	`SLAXDEBUG`
`=`	`COMPLETED`	`FINAL`	`MAXSIZE`	`POLICY`	`SNAPSHOT`
`^`	`COMPRESSED`	`FLASHBACK`	`METHOD`	`POOL`	`SPFILE`
`@`	`COMPRESSION`	`FORCE`	`MINIMIZE`	`PREVIEW`	`SPOOL`
`.`	`CONFIGURE`	`FOREIGN`	`MISC`	`PRIMARY`	`SQL`
`:`	`CONNECT`	`FOREVER`	`MOUNT`	`PRINT`	`STANDBY`
`ABORT`	`CONSISTENT`	`FORMAT`	`MSGLOG`	`PRIORITY`	`STARTUP`
`ACCESSIBLE`	`CONTROLFILECOPY`	`FOR`	`MSGNO`	`PRIVILEGES`	`START`
`ACTIVE`	`CONTROLFILE`	`FROM`	`M`	`PROXY`	`STEP`
`ADVISEID`	`CONVERT`	`FULL`	`NAMES`	`PUT`	`SUMMARY`
`ADVISE`	`COPIES`	`GET`	`NAME`	`QUIT`	`SWITCH`
`AES128`	`COPY`	`GLOBAL`	`NEED`	`RATE`	`TABLESPACES`
`AES192`	`CORRUPTION`	`HIGH`	`NEW-LINE`	`RCVCAT`	`TABLESPACE`
`AES256`	`CREATE`	`GRANT`	`NEWNAME`	`RCVMAN`	`TAG`
`AFFINITY`	`CRITICAL`	`GROUP`	`NEW`	`READONLY`	`TARGET`
`AFTER`	`CROSSCHECK`	`GUARANTEE`	`NOCATALOG`	`READRATE`	`TDES168`
`ALGORITHM`	`CUMULATIVE`	`G`	`NOCFAU`	`RECALL`	`TEMPFILE`
`ALLOCATE`	`CURRENT`	`HEADER`	`NOCHECKSUM`	`RECOVERABLE`	`TEST`
`ALLOW`	`DATABASE`	`HIGH`	`NODEVALS`	`RECOVERY`	`THREAD`
`ALL`	`DATAFILECOPY`	`HOST`	`NODUPLICATES`	`RECOVER`	`TIMEOUT`
`ALTER`	`DATAFILE`	`IDENTIFIED`	`NOEXCLUDE`	`REDUNDANCY`	`TIMES`
`AND`	`DATAPUMP`	`IDENTIFIER`	`NOFILENAMECHECK`	`REGISTER`	`TIME`
`APPEND`	`DAYS`	`ID`	`NOFILEUPDATE`	`RELEASE`	`TO`
`APPLIED`	`DBA`	`IMMEDIATE`	`NOKEEP`	`RELOAD`	`TRACE`
`ARCHIVELOG`	`DBID`	`IMPORT`	`NOLOGS`	`REMOVE`	`TRANSACTIONAL`
`AREA`	`DB_FILE_NAME_CONVERT`	`INACCESSIBLE`	`NOMOUNT`	`RENORMALIZE`	`TRANSPORT`
`AS`	`DB_NAME`	`INCARNATION`	`NONE`	`REPAIRID`	`TYPE`
`AT`	`DB_RECOVERY_FILE_DEST`	`INCLUDE`	`NOPARALLEL`	`REPAIR`	`UNAVAILABLE`
`ATALL`	`DB_UNIQUE_NAME`	`INCLUDING`	`NOPROMPT`	`REPLACE`	`UNCATALOG`
`AUTOBACKUP`	`DEBUG`	`INCREMENTAL`	`NOREDO`	`REPLICATE`	`UNDO`
`AUTOLOCATE`	`DECRYPTION`	`INPUT`	`NORMAL`	`REPORT`	`UNLIMITED`
`AUXILIARY`	`DEFAULT`	`INSTANCE`	`NOT`	`RESETLOGS`	`UNRECOVERABLE`
`AUXNAME`	`DEFINE`	`IO`	`NO`	`RESET`	`UNREGISTER`
`AVAILABLE`	`DELETE`	`JOB`	`NULL`	`RESTART`	`UNTIL`
`BACKED`	`DELETION`	`KBYTES`	`OBSOLETE`	`RESTORE`	`UPGRADE`
`BACKUPPIECE`	`DESTINATION`	`KEEP`	`OFFLINE`	`RESTRICTED`	`UP`
`BACKUPSET`	`DETAIL`	`KRB`	`OFF`	`RESYNC`	`USING`
`BACKUPS`	`DEVICE`	`K`	`OF`	`RETENTION`	`VALIDATE`
`BACKUP`	`DIRECTORY`	`LEVEL`	`ONLY`	`REUSE`	`VERBOSE`
`BEFORE`	`DISKRATIO`	`LIBPARM`	`ON`	`REVOKE`	`VIRTUAL`
`BETWEEN`	`DISK`	`LIBRARY`	`OPEN`	`RPCTEST`	`WINDOW`
`BLOCKRECOVER`	`DISPLAY`	`LIKE`	`OPTIMIZATION`	`RPC`	`WITH`
`BLOCKS`	`DORECOVER`	`LIMIT`	`OPTION`	`RUN`
`BLOCK`	`DROP`	`LIST`	`ORPHAN`	`SAVE`
`BY`	`DUMP`	`LOAD`	`OR`	`SCHEMA`
`CANCEL`	`DUPLEX`	`LOGFILE`	`PACKAGES`	`SCN`
`CATALOG`	`DUPLICATE`	`LOGICAL`	`PARALLELISM`	`SCRIPT`

If you must use one of the reserved words as an argument to an RMAN command (for example, as a filename, tablespace name, tag name, and so on), then surround it with single or double quotes. Otherwise, RMAN cannot parse your command correctly and generates an error. Example 1-1 shows correct and incorrect usage of RMAN reserved words in RMAN commands.

Example 1-1 Using Reserved Words as Arguments to RMAN Commands

ALLOCATE CHANNEL backup DEVICE TYPE DISK;         # incorrect
ALLOCATE CHANNEL "backup" DEVICE TYPE DISK;       # correct
BACKUP DATABASE TAG full;                         # incorrect
BACKUP DATABASE TAG 'full';                       # correct

In general, avoid using reserved words in ways that conflict with their primary meaning in the RMAN command language.

Summary of RMAN Commands

Table 1-2 provides a functional summary of RMAN commands that you can execute at the RMAN prompt, within a RUN command, or both. All commands from previous RMAN releases work with the current release, although some commands and options are now deprecated (see Appendix A, "Deprecated RMAN Commands"). For command-line options for the RMAN client, refer to RMAN.

Table 1-2 Recovery Manager Commands

Command	Purpose
`@`	Run a command file.
`@@`	Run a command file in the same directory as another command file that is currently running. The `@@` command differs from the `@` command only when run from within a command file.
`ADVISE FAILURE`	Display repair options.
`ALLOCATE CHANNEL`	Establish a channel, which is a connection between RMAN and a database instance.
`ALLOCATE CHANNEL FOR MAINTENANCE`	Allocate a channel in preparation for issuing maintenance commands such as `DELETE`.
`ALTER DATABASE`	Mount or open a database.
`BACKUP`	Back up database files, copies of database files, archived logs, or backup sets.
`CATALOG`	Add information about file copies and user-managed backups to the repository.
`CHANGE`	Mark a backup piece, image copy, or archived redo log as having the status `UNAVAILABLE` or `AVAILABLE`; remove the repository record for a backup or copy; override the retention policy for a backup or copy; update the recovery catalog with the `DB_UNIQUE_NAME` for the target database.
`CONFIGURE`	Configure persistent RMAN settings. These settings apply to all RMAN sessions until explicitly changed or disabled.
`CONNECT`	Establish a connection between RMAN and a target, auxiliary, or recovery catalog database.
`CONVERT`	Convert datafile formats for transporting tablespaces and databases across platforms.
`CREATE CATALOG`	Create the schema for the recovery catalog.
`CREATE SCRIPT`	Create a stored script and store it in the recovery catalog.
`CROSSCHECK`	Determine whether files managed by RMAN, such as archived logs, datafile copies, and backup pieces, still exist on disk or tape.
`DELETE`	Delete backups and copies, remove references to them from the recovery catalog, and update their control file records to status `DELETED`.
`DELETE SCRIPT`	Delete a stored script from the recovery catalog.
`DROP CATALOG`	Remove the schema from the recovery catalog.
`DROP DATABASE`	Delete the target database from disk and unregisters it.
`DUPLICATE`	Use backups of the target database to create a duplicate database that you can use for testing purposes or to create a standby database.
`EXECUTE SCRIPT`	Run an RMAN stored script.
`EXIT`	Quit the RMAN executable.
`FLASHBACK DATABASE`	Returns the database to its state at a previous time or SCN.
`GRANT`	Grants privileges to a recovery catalog user.
`HOST`	Invoke an operating system command-line subshell from within RMAN or run a specific operating system command.
`IMPORT CATALOG`	Imports the metadata from one recovery catalog into a different recovery catalog.
`LIST`	Produce a detailed listing of backup sets or copies.
`PRINT SCRIPT`	Display a stored script.
`QUIT`	Exit the RMAN executable.
`RECOVER`	Apply redo logs and incremental backups to datafiles or data blocks restored from backup or datafile copies, in order to update them to a specified time.
`REGISTER DATABASE`	Register the target database in the recovery catalog.
`RELEASE CHANNEL`	Release a channel that was allocated with an `ALLOCATE CHANNEL` command or `ALLOCATE CHANNEL FOR MAINTENANCE` command.
`REPAIR FAILURE`	Repair one or more failures recorded in the automated diagnostic repository.
`REPLACE SCRIPT`	Replace an existing script stored in the recovery catalog. If the script does not exist, then `REPLACE` `SCRIPT` creates it.
`REPORT`	Perform detailed analyses of the content of the recovery catalog.
`RESET DATABASE`	Inform RMAN that the SQL statement `ALTER` `DATABASE` `OPEN` `RESETLOGS` has been executed and that a new incarnation of the target database has been created, or reset the target database to a prior incarnation.
`RESTORE`	Restore files from backup sets or from disk copies to the default or a new location.
`RESYNC CATALOG`	Perform a full resynchronization, which creates a snapshot control file and then copies any new or changed information from that snapshot control file to the recovery catalog.
`REVOKE`	Revoke privileges from a recovery catalog user.
`RMAN`	Start RMAN from the operating system command line.
`RUN`	Execute a sequence of one or more RMAN commands, which are one or more statements executed within the braces of `RUN`.
`SEND`	Send a vendor-specific quoted string to one or more specific channels.
`SET`	Set the value of various attributes that affect RMAN behavior for the duration of a RUN block or a session.
`SHOW`	Display the current `CONFIGURE` settings.
`SHUTDOWN`	Shut down the target database. This command is equivalent to the SQL*Plus `SHUTDOWN` command.
`SPOOL`	Write RMAN output to a log file.
`SQL`	Execute a SQL statement from within Recovery Manager.
`STARTUP`	Start up the target database. This command is equivalent to the SQL*Plus `STARTUP` command.
`SWITCH`	Specify that a datafile copy is now the current datafile, that is, the datafile pointed to by the control file. This command is equivalent to the SQL statement `ALTER` `DATABASE` `RENAME` `FILE` as it applies to datafiles.
`TRANSPORT TABLESPACE`	Create transportable tablespace sets from backup for one or more tablespaces.
`UNREGISTER`	Unregister a database from the recovery catalog.
`UPGRADE CATALOG`	Upgrade the recovery catalog schema from an older version to the version required by the RMAN executable.
`VALIDATE`	Examine a backup set and report whether its data is intact. RMAN scans all of the backup pieces in the specified backup sets and looks at the checksums to verify that the contents can be successfully restored.

Summary of RMAN Subclauses

Subclauses are used in multiple commands are documented in a separate chapter to avoid unnecessary duplication. The descriptions of commands that use these subclauses include a cross-reference to the subclause entry in Chapter 3, "RMAN Subclauses". Table 1-3 summarizes the RMAN subclauses.

Table 1-3 Recovery Manager Subclauses

Subclause	Specifies . . .
`allocOperandList`	Channel control options such as `PARMS` and `FORMAT`.
`archivelogRecordSpecifier`	A range of archived redo log files.
`completedTimeSpec`	A time range during which the backup or copy completed.
`connectStringSpec`	The username, password, and net service name for connecting to a target, recovery catalog, or auxiliary database. The connection is necessary to authenticate the user and identify the database.
`datafileSpec`	A datafile by filename or absolute file number.
`deviceSpecifier`	The type of storage device for a backup or copy.
`fileNameConversionSpec`	Patterns to transform source to target filenames during `BACKUP` `AS` `COPY`, `CONVERT` and `DUPLICATE`.
`forDbUniqueNameOption`	All databases in a Data Guard environment or a database with the specified `DB_UNIQUE_NAME`.
`foreignlogRecordSpecifier`	A range of foreign archived redo log files.
`formatSpec`	A filename format for a backup or copy.
`keepOption`	A backup or copy should or should not be exempt from the current retention policy.
`listObjList`	Items that will be displayed by the `LIST` command.
`maintQualifier`	Additional options for maintenance commands such as `DELETE` and `CHANGE`.
`maintSpec`	Files operated on by maintenance commands such as `CHANGE`, `CROSSCHECK`, and `DELETE`.
`obsOperandList`	Backups that are obsolete according to specified criteria.
`recordSpec`	Objects that the maintenance commands should operate on.
`tempfileSpec`	A tempfile by path or by file number.
`untilClause`	An upper limit by time, SCN, or log sequence number. This clause is usually used to specify the desired point in time for an incomplete recovery.