Execute RMAN Stored Scripts with the RUN Command

In the previous lesson, you learned how to create and manage local and global scripts in an RMAN recovery catalog. To execute one of those scripts, place EXECUTE SCRIPT inside a brace-delimited RUN block. RMAN must be connected to the target database and to the open recovery catalog that contains the stored definition.

The RUN command groups a sequence of RMAN job commands and executes them in order. When RMAN reads the closing brace, it compiles the commands into one or more RMAN job steps and immediately executes those steps. They are not PL/SQL blocks, and the compiled job is not saved as another stored script. The recovery-catalog script remains the reusable definition.

A RUN block can also establish temporary settings, override configured channels, invoke an operating-system command with HOST, and execute supported SQL against the target database. These capabilities allow a backup or recovery procedure to operate as one controlled job.

RUN Block Requirements and Structure

Execute RUN only at the RMAN prompt. Enclose the job commands between an opening and closing brace, and terminate each command inside the block with a semicolon:

RMAN> RUN
2> {
3>   RMAN_job_command;
4>   RMAN_job_command;
5> }

A stored script requires a recovery catalog. Before running it, confirm that the catalog database is open, the target is registered, and RMAN is connected to both databases. The following example uses operating-system authentication for the target and an example catalog owner and service name:

RMAN> CONNECT TARGET /;
RMAN> CONNECT CATALOG rco@catdb;

When password authentication is required, allow RMAN to prompt for the password instead of placing it on the command line or in a script. A target or auxiliary connection requires an appropriately privileged account, normally an account granted SYSBACKUP or SYSDBA.

Execute a Local Stored Script

Lesson 6 created the local script backup_users. The following RUN block retrieves its definition from the recovery catalog and executes it against the connected target database:

RMAN> RUN
2> {
3>   EXECUTE SCRIPT backup_users;
4> }

EXECUTE SCRIPT is valid only within a RUN block. RMAN places the contents of the stored script into the active block, so those commands become part of the current job. If the stored definition allocates a channel, do not allocate the same channel in the outer block.

When GLOBAL is omitted, RMAN first searches for a local script associated with the connected target. If no local script has the requested name, RMAN searches for a global script with that name. This local-before-global rule permits database-specific behavior to take precedence over a shared catalog procedure.

Execute a Global Stored Script

Use EXECUTE GLOBAL SCRIPT when the catalog-wide definition must be selected explicitly:

RMAN> RUN
2> {
3>   EXECUTE GLOBAL SCRIPT global_full_backup;
4> }

The target must be registered in the recovery catalog, and the named global script must exist. If GLOBAL is specified but the script is not present, RMAN reports RMAN-06004. Explicit global syntax is especially useful when a local and global script share the same name.

Pass Values to a Stored Script

A stored script may contain substitution variables such as &1, &2, and &3. Supply their runtime values with USING:

RMAN> RUN
2> {
3>   EXECUTE SCRIPT backup_df USING 3 test_backup df3;
4> }

RMAN substitutes 3 for &1, test_backup for &2, and df3 for &3 before it executes the stored commands. Validate the supplied values because substitution changes the command text that RMAN processes.

Use RUN as a Temporary Configuration Scope

A RUN block creates a scope in which a job can override persistent RMAN configuration. For example, the block can allocate a manual channel with a job-specific destination:

RMAN> RUN
2> {
3>   ALLOCATE CHANNEL c1 DEVICE TYPE DISK FORMAT '/u02/backup/%U';
4>   BACKUP DATABASE PLUS ARCHIVELOG;
5> }

RMAN releases a channel allocated in the block when the block completes. Settings established by supported SET commands also return to their prior values when their scope ends. This behavior makes a block useful for an exceptional job that must differ from the configured default.

Use persistent CONFIGURE settings and automatic channels for normal backup operations. Manual channel allocation should communicate a real requirement, such as a special device or destination, rather than being copied into every script by habit.

Run an Operating-System Command

The RMAN HOST command opens an operating-system subshell or executes a specified command. It can be used at the RMAN prompt or inside a RUN block. The following example lists a backup directory and then returns control to RMAN:

RMAN> RUN
2> {
3>   HOST 'ls -l /u02/backup';
4> }

HOST runs with the operating-system identity and permissions of the RMAN client process. This makes the command platform-dependent and can introduce security or portability concerns. Use it only for an approved operational need, avoid embedding secrets, and do not assume that a command written for Linux will work unchanged on Windows.

Execute SQL from an RMAN Job

Oracle AI Database 26ai RMAN can execute supported SQL statements and PL/SQL procedures. Current RMAN syntax permits many SQL statements directly, without the older SQL 'quoted statement' wrapper. The following job archives the current online redo log before backing up the available archived redo logs:

RMAN> RUN
2> {
3>   ALTER SYSTEM ARCHIVE LOG CURRENT;
4>   BACKUP ARCHIVELOG ALL;
5> }

RMAN sends the ALTER SYSTEM statement to the target database. If that statement succeeds, RMAN continues to the BACKUP ARCHIVELOG command. The older quoted SQL form remains available for compatibility, but the direct form is clearer when the statement is supported by current RMAN SQL syntax.

Distinguish SQL from SQL*Plus Commands

SQL*Plus includes client commands that are not part of the SQL language. For example, SHOW SGA is interpreted by SQL*Plus itself. Sending it to the database as a SQL statement from RMAN results in an invalid SQL statement error. Run it in SQL*Plus when that client-specific display is needed:

SQL> SHOW SGA

The word RUN also has different meanings in RMAN and SQL*Plus:

SQL*Plus script files remain operating-system files. They are not RMAN stored scripts and are not retrieved from an RMAN recovery catalog.

Understand RMAN Command Context

The legacy distinction between stand-alone commands and job commands is useful only as a starting point. Oracle AI Database 26ai contains commands with different placement rules and context-dependent forms. Consult the current command reference when a command's placement is uncertain.

EXECUTE SCRIPT is a particularly important exception to remember: it must appear inside a RUN block. In contrast, CREATE SCRIPT, REPLACE SCRIPT, PRINT SCRIPT, and DELETE SCRIPT manage the catalog definition at the RMAN prompt.

Run Backup Commands Directly

A RUN block does not have to invoke a stored script. The block can contain the same job commands that could have been placed in a stored definition. This example creates a level 0 incremental backup of the standard USERS tablespace:

RMAN> RUN
2> {
3>   BACKUP INCREMENTAL LEVEL 0 TABLESPACE users;
4> }

The example relies on configured automatic channels and destinations. This keeps the job portable and avoids the obsolete hard-coded Windows path and nonstandard USER_DATA tablespace used by the legacy lesson. Use a stored script when the sequence should be named, reviewed, and reused through the recovery catalog. Use an inline block for a controlled one-time job or a small temporary variation.

Choose a Stored Script or an Inline RUN Block

Both approaches execute RMAN job commands, but they solve different operational problems. A stored script centralizes a reusable definition in the recovery catalog. An inline block keeps a temporary procedure visible in the current RMAN session or command file.

Do not duplicate a standard procedure across many inline blocks when a reviewed global script would provide a single controlled definition. Conversely, do not make a global script depend on one database's path, tablespace, or device settings. Select the form that makes scope and ownership obvious.

Handle Execution Failures

Commands in a RUN block form one ordered job. If a command fails, later steps do not simply continue as though the operation succeeded. Review the RMAN error stack, correct the underlying condition, and determine which completed backups or changes remain valid before rerunning the job.

An external scheduler should capture RMAN output and process status, retain job history, and notify the responsible administrator when a job fails. The stored script and RUN block define the RMAN procedure, while scheduling, credential protection, monitoring, and alerting remain separate operational responsibilities.

Prepare a Reliable RUN Job

Before moving a block or stored script into an automated schedule, review the complete execution path rather than checking only whether RMAN accepts the syntax. A dependable procedure normally includes the following preparation:

1. Confirm the target database, recovery catalog, and intended local or global script scope.
2. Use PRINT SCRIPT to review a stored definition before execution, especially after REPLACE SCRIPT.
3. Use SHOW to review persistent RMAN configuration when the job relies on automatic channels, device types, or retention settings.
4. Verify that any temporary path, media manager, channel, and operating-system command is available to the RMAN client identity.
5. Test the backup procedure and confirm that its output can support the required restore and recovery objective.
6. Record RMAN output and return status so a partial or failed job cannot be mistaken for a successful backup.

A syntactically valid RUN block can still fail because a database object, destination, device, permission, or external program is unavailable. Testing establishes whether the complete environment can perform the procedure, while monitoring establishes whether each scheduled execution actually completed.

The RUN command provides the execution context for stored RMAN procedures and other grouped backup or recovery commands. In the next lesson, you will examine the recovery-catalog data dictionary views that report catalog contents and RMAN activity.