4 Starting and Interacting with the RMAN Client

If you start RMAN without a connect string on the operating system command line, then you must issue a CONNECT TARGET command at the RMAN prompt to connect to a target database.

To make a database connection from the RMAN prompt:

To connect to a target database from the operating system command line, enter the rman command followed by the connection information. You can begin executing commands after the RMAN prompt is displayed.

Use the CATALOG keyword to connect to a recovery catalog. You can also start RMAN without specifying NOCATALOG or CATALOG. If you do not specify NOCATALOG on the command line, and if you do not specify CONNECT CATALOG after RMAN has started, then RMAN defaults to NOCATALOG mode the first time that you run a command that requires the use of the RMAN repository.

If you connect to the target database on the operating system command line, then you can begin executing commands after the RMAN prompt is displayed.

To use the DUPLICATE command, you must connect to an auxiliary instance. To perform RMAN tablespace point-in-time recovery (TSPITR), you may also need to connect to an auxiliary instance.

The form of an auxiliary connection is identical to a target database connection, except that you use the AUXILIARY keyword instead of the TARGET keyword.

If you create an RMAN command file that uses a CONNECT command with database level credentials (user name and password), then anyone with read access to this file can learn the password. There is no secure way to incorporate a CONNECT string with a password into a command file.

If you create an RMAN command file that uses a CONNECT command, then RMAN does not echo the connect string when you run the command file with the @ command. This behavior prevents connect strings from appearing in any log files that contain RMAN output. For example, suppose that you create a command file listbkup.rman as follows:

cat > listbkup.rman << EOF
CONNECT TARGET /
LIST BACKUP;
EOF

You execute this script by running RMAN with the @ command line option as follows:

% rman @listbkup.rman

When the command file executes, RMAN replaces the connection string with an asterisk, as shown in the following output:

RMAN> CONNECT TARGET *
2> LIST BACKUP;
3>
connected to target database: RDBMS (DBID=771530996)

using target database control file instead of recovery catalog

List of Backup Sets
===================
. . .

When the RMAN client is ready for your commands, it displays the command prompt, as in this example:

RMAN> 

Enter commands for RMAN to execute. For example:

RMAN> CONNECT TARGET
RMAN> BACKUP DATABASE;

Most RMAN commands take several parameters and must end with a semicolon. Some commands, such as STARTUP, SHUTDOWN, and CONNECT, can be used with or without a semicolon.

When you enter a line of text that is not a complete command, RMAN prompts for continuation input with a line number. For example:

RMAN> BACKUP DATABASE
2> INCLUDE CURRENT 
3> CONTROLFILE
4> ;

For repetitive tasks, you can create a text file containing RMAN commands, and start the RMAN client with the @ argument, followed by a file name. For example, create a text file cmdfile1 in the current directory containing one line of text as shown here:

BACKUP DATABASE PLUS ARCHIVELOG;

You can run this command file from the command line as shown in this example, and the command contained in it is executed:

% rman TARGET / @cmdfile1

After the command completes, RMAN exits.

You can also use the @ command at the RMAN command prompt to execute the contents of a command file during an RMAN session. RMAN reads the file and executes the commands in it. For example:

RMAN> @cmdfile1

After the command file contents have been executed, RMAN displays the following message:

RMAN>  **end-of-file**

Unlike the case where a command file is executed from the operating system command line, RMAN does not exit.

The comment character in RMAN is a pound sign (#). All text from the pound sign to the end of the line is ignored. For example, the contents of the following command file back up the database and archived redo log files and include comments:

# Command file name: mybackup.rman
# The following command backs up the database
BACKUP DATABASE;
# The following command backs up the archived redo logs
BACKUP ARCHIVELOG ALL;

The following example shows how you can break a single RMAN command across multiple lines:

RMAN> BACKUP # this is a comment
2> SPFILE;

When running a command file, you can specify one or more values in a USING clause for use in substitution variables in a command file. In this way, you can make your command files dynamic.

As in SQL*Plus, &1 indicates where to place the first value, &2 where to place the second value, and so on. The substitution variable syntax is &integer followed by an optional period, for example, &1.3. The optional period is part of the variable and replaced with the value, thus enabling the substitution text to be immediately followed by another integer. For example, if you pass the value mybackup to a command file containing the variable &1.3, then the result of the substitution is mybackup3.

The following procedure explains how to create and use a dynamic shell script that calls a command file containing substitution variables.

To create and use a dynamic shell script:

This scenario assumes that the application controlling RMAN wants to run multiple commands in succession. After each command is sent down the pipe and executed and the output returned, RMAN pauses and waits for the next command.

To execute RMAN commands through a pipe:

This scenario assumes that the application controlling RMAN wants to run one or more commands as a single job. After running the commands that are on the pipe, RMAN exits.

To execute RMAN commands in a single job through a pipe: