Working with RMAN Stored Scripts in the Recovery Catalog

Creating Stored Scripts: CREATE SCRIPT

Make sure RMAN is connected to the right target database and the recovery catalog. Then run the CREATE SCRIPT command, as shown in this example:

CREATE SCRIPT full_backup 
{     
  BACKUP DATABASE PLUS ARCHIVELOG;
  DELETE OBSOLETE;
}

Examine the output. If no errors are displayed, then the script was successfully created and stored in the recovery catalog.

For a global script, the syntax is similar:

CREATE GLOBAL SCRIPT global_full_backup 
{     
  BACKUP DATABASE PLUS ARCHIVELOG;
  DELETE OBSOLETE;
}

You can also provide a COMMENT with descriptive information:

CREATE GLOBAL SCRIPT global_full_backup 
COMMENT 'use only with ARCHIVELOG mode databases'
{     
  BACKUP DATABASE PLUS ARCHIVELOG;
  DELETE OBSOLETE;
}

Finally, you can create a local or global script, reading its contents from a text file:

CREATE SCRIPT full_backup FROM FILE 'my_script_file.txt';

The file must begin with a { character, contain a series of commands valid within a RUN block, and end with a } character. Otherwise, a syntax error is signalled, just as if the commands were entered at the keyboard.

Running Stored Scripts: EXECUTE SCRIPT

To run a stored script, connect to the target database and recovery catalog, and use EXECUTE SCRIPT. EXECUTE SCRIPT requires a RUN block, as shown:

RUN { EXECUTE SCRIPT full_backup; }

This command invokes a local script if one is with the name specified. If no local script is found, but there is a global script with the name specified, RMAN will execute the global script. You can also use EXECUTE GLOBAL SCRIPT to control which script is invoked if a local and a global script have the same name. Assuming there is no local script called global_full_backup, the following two commands have the same effect:

RUN { EXECUTE GLOBAL SCRIPT global_full_backup; }
RUN { EXECUTE SCRIPT global_full_backup; }

Executing a global script only affects the connected target database; to run a global script across multiple databases, you must connect the RMAN client to each one separately and execute the script.

Your script will use the automatic channels configured at the time you execute the script. Use ALLOCATE CHANNEL commands in the script if you need to override the configured channels. Note that, because of the RUN block, if an RMAN command in the script fails, subsequent RMAN commands in the script will not execute.

Displaying a Stored Script: PRINT SCRIPT

The PRINT SCRIPT command displays a stored script or writes it out to a file. With RMAN connected to the target database and recovery catalog, use the PRINT SCRIPT command as shown here:

PRINT SCRIPT full_backup;

To send the contents of a script to a file, use this form of the command:

PRINT SCRIPT full_backup TO FILE 'my_script_file.txt';

For global scripts, the analogous syntax would be:

PRINT GLOBAL SCRIPT global_full_backup;

and

PRINT GLOBAL SCRIPT global_full_backup TO FILE 'my_script_file.txt';

Listing Stored Scripts: LIST SCRIPT NAMES

Use the LIST SCRIPT NAMES command to display the names of scripts defined in the recovery catalog. This command displays the names of all stored scripts, both global and local, that can be executed for the currently connected target database:

LIST SCRIPT NAMES;

If RMAN is not connected to a target database when the LIST SCRIPT NAMES command is run, then RMAN will respond with an error.

To view only global script names, use this form of the command:

LIST GLOBAL SCRIPT NAMES;

To view the names of all scripts stored in the current recovery catalog, including global scripts and local scripts for all target databases registered in the recovery catalog, use this form of the command:

LIST ALL SCRIPT NAMES;

The output will indicate for each script listed which target database the script is defined for (or whether a script is global).

Updating Stored Scripts: REPLACE SCRIPT

To update stored scripts, connect to the target database and recovery catalog and use the REPLACE SCRIPT command. If the script does not already exist, then RMAN creates it.

This command updates stored script script full_backup with new contents:

REPLACE SCRIPT full_backup 
{
  BACKUP DATABASE PLUS ARCHIVELOG;
}

Global scripts can be updated using the REPLACE GLOBAL SCRIPT command when connected to a recovery catalog, as follows:

REPLACE GLOBAL SCRIPT global_full_backup 
COMMENT 'A script for full backup to be used with any database'
{
  BACKUP AS BACKUPSET DATABASE PLUS ARCHIVELOG;
}

As with CREATE SCRIPT, you can update a local or global stored script from a text file, with this form of the command:

REPLACE GLOBAL SCRIPT global_full_backup FROM FILE 'my_script_file.txt';

Deleting Stored Scripts: DELETE SCRIPT

To delete a stored script from the recovery catalog, connect to the catalog and a target database, and use the DELETE SCRIPT command:

DELETE SCRIPT 'full_backup';

To delete a global stored script, use DELETE GLOBAL SCRIPT:

DELETE GLOBAL SCRIPT 'global_full_backup';

If you use DELETE SCRIPT without GLOBAL, and there is no stored script for the target database with the specified name, RMAN will look for a global stored script by the specified name and delete the global script if it exists. So, if you were to enter the command

DELETE SCRIPT 'global_full_backup';

RMAN would look for a script 'global_full_backup' defined for the connected target database, and if it did not find one, it would search the global scripts for a script called 'global_full_backup' and delete that script.

Starting the RMAN Client and Running a Stored Script

To run the RMAN client and start a stored script in the recovery catalog on startup, use the SCRIPT argument when starting the RMAN client.

% rman TARGET SYS/oracle@trgt CATALOG rman/cat@catdb SCRIPT 'full_backup';

You must connect to a recovery catalog (which contains the stored script) and target database (to which the script will apply) when starting the RMAN client.

Restrictions on Stored Script Names

There are some issues to be aware of about how RMAN resolves script names, especially when a local and global script share the same name.

• RMAN permits but generally does not require that you use quotes around the name of a stored script. However, if the name begins with a digit or if the name is an RMAN reserved word, you will have to put quotes around the name to use it as a stored script name. Consider avoiding stored script names that begin with characters other than A-Z or that are the same as RMAN reserved words.

  See Also:

  Oracle Database Backup and Recovery Reference

• When starting the RMAN client with a SCRIPT argument on the command line, if local and global scripts are defined with the same name, then RMAN will always execute the local script.

• For the EXECUTE SCRIPT, DELETE SCRIPT and PRINT SCRIPT commands, if the script name passed as an argument is not the name of a script defined for the connected target instance, RMAN will look for a global script by the same name to execute, delete or print. For example, if the a stored script global_full_backup is in the recovery catalog as a global script, but no local stored script global_full_backup is defined for the target database, the following command will delete the global script:

  DELETE SCRIPT global_full_backup;
  

Consider using some naming convetion to avoid mistakes due to confusion between global stored scripts and local stored scripts.