3.1 Overview of Interacting With the RMAN Client

This section describes basic interactions with the RMAN client, such as starting and exiting the RMAN client, entering commands at the command prompt, and using command line arguments. It contains the following sections:

Starting and Exiting RMAN
Setting Globalization Support Environment Variables for RMAN
Entering RMAN Commands at the Command Prompt
Using Command Files with RMAN
Checking Syntax of RMAN Commands and Command Files: CHECKSYNTAX

3.1.1 Starting and Exiting RMAN

You have the following basic options for starting RMAN:

Start the RMAN executable at the operating system command line without specifying any connection options, as in this example:
```
% rman
```
Start the RMAN executable at the operating system command line while connecting to a target database and, possibly, a recovery catalog, as in these examples:
```
% rman TARGET /
```
```
% rman TARGET SYS/oracle@trgt NOCATALOG
```
```
% rman TARGET / CATALOG rman/cat@catdb 
```

Note:

Most RMAN commands require that RMAN connect to at least a target database to perform useful work. See "Connecting the RMAN Client to Databases" for more details on connecting RMAN to different types of databases.

To quit RMAN and terminate the program, type EXIT or QUIT at the RMAN prompt. For example:

RMAN> EXIT

3.1.2 Setting Globalization Support Environment Variables for RMAN

Before invoking RMAN, it may be useful to set the NLS_DATE_FORMAT and NLS_LANG environment variables. These variables determine the format used for the time parameters in RMAN commands such as RESTORE, RECOVER, and REPORT.

The following example shows typical language and date format settings:

NLS_LANG=american
NLS_DATE_FORMAT='Mon DD YYYY HH24:MI:SS'

If you are going to use RMAN to connect to an unmounted database and mount the database later while RMAN is still connected, then set the NLS_LANG environment variable so that it also specifies the character set used by the database.

A database that is not mounted assumes the default character set, which is US7ASCII. If your character set is different from the default, then RMAN returns errors after the database is mounted. For example, if the character set is WE8DEC, you can set the NLS_LANG parameter as follows:

NLS_LANG=american_america.we8dec

NLS_LANG and NLS_DATE_FORMAT must be set for NLS_DATE_FORMAT to be used.

3.1.3 Entering RMAN Commands at the Command Prompt

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> CONNECT CATALOG rman/rman@inst2

RMAN> BACKUP DATABASE ;

Most RMAN commands take a number of parameters and must end with a semicolon. (The few exceptions, 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> ;

3.1.4 Using Command Files with RMAN

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

BACKUP DATABASE INCLUDE CURRENT CONTROLFILE;

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.

3.1.5 Checking Syntax of RMAN Commands and Command Files: CHECKSYNTAX

You may want to test some RMAN commands for syntactic correctness without executing them, either entering them at the command prompt or reading them in from a command file. Use the command-line argument CHECKSYNTAX to start the RMAN client in a mode in which it only parses the commands you enter and returns an RMAN-00558 error for commands that are not legal RMAN syntax.

3.1.5.1 Checking RMAN Syntax at the Command Line: Example

To test commands at the command line, start RMAN with the CHECKSYNTAX parameter, and then enter the commands to be tested, as shown in the following example:

% rman CHECKSYNTAX
Recovery Manager: Release 10.2.0.1.0 - Production on Sun Jun 12 02:41:03 2005
 
Copyright (c) 1982, 2005, Oracle.  All rights reserved.
RMAN> run [ backup database; ] 
 
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-00558: error encountered while parsing input commands
RMAN-01006: error signalled during parse 
 RMAN-02001: unrecognized punctuation symbol "["
 
RMAN> run { backup database; }

The command has no syntax errors

RMAN>

3.1.5.2 Checking RMAN Syntax in Command Files: Example

To test commands in a command file, start RMAN with the CHECKSYNTAX parameter, and use the @ argument to name the command file to be passed. For example, use a text editor to create a command file /tmp/goodcmdfile with the following contents:

#command file with legal syntax
restore database; 
recover database;

Also create another command file, /tmp/badcmdfile, with the following contents:

#command file with bad syntax commands
restore database
recover database

When you run the command files through RMAN with CHECKSYNTAX, the output is:

% rman CHECKSYNTAX @/tmp/goodcmdfile
Recovery Manager: Release 10.2.0.1.0 - Production on Sun Jun 12 02:41:03 2005
 
Copyright (c) 1982, 2005, Oracle.  All rights reserved.
 
RMAN> # command file with legal syntax
2> restore database;
3> recover database;
4>
The cmdfile has no syntax errors
 
Recovery Manager complete.

% rman checksyntax @/tmp/badcmdfile
Recovery Manager: Release 10.2.0.1.0 - Production on Sun Jun 12 02:41:03 2005
 
Copyright (c) 1982, 2005, Oracle.  All rights reserved.
RMAN> #command file with syntax error
2> restore database
3> recover
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS===============
RMAN-00571: ===========================================================
RMAN-00558: error encountered while parsing input commands
RMAN-01005: syntax error: found "recover": expecting one of: "archivelog, 
      channel, check, controlfile, clone, database, datafile, device, 
      from, force, high, (, preview, ;, skip, spfile, standby, tablespace, 
      until, validate"
RMAN-01007: at line 3 column 1 file: /tmp/badcmdfile