Using the RMAN Pipe Interface

The RMAN pipe interface is an alternative method for issuing commands to RMAN and receiving the output from those commands. With this interface, RMAN obtains commands and sends output by using the DBMS_PIPE PL/SQL package instead of the operating system shell. Using this interface, it is possible to write a portable programmatic interface to RMAN.

The pipe interface is invoked by using thePIPE command-line parameter for the RMAN client. RMAN uses two private pipes: one for receiving commands and the other for sending output. The names of the pipes are derived from the value of the PIPE parameter. For example, you can invoke RMAN with the following command:

% rman PIPE abc TARGET SYS/oracle@trgt

RMAN opens the two pipes in the target database: ORA$RMAN_ABC_IN, which RMAN uses to receive user commands, and ORA$RMAN_ABC_OUT, which RMAN uses to send all output back to RMAN. All messages on both the input and output pipes are of type VARCHAR2.

Note that RMAN does not permit the pipe interface to be used with public pipes, because they are a potential security problem. With a public pipe, any user who knows the name of the pipe can send commands to RMAN and intercept its output.

If the pipes are not already initialized, then RMAN creates them as private pipes. If you want to put commands on the input pipe before starting RMAN, you must first create the pipe by calling DBMS_PIPE.CREATE_PIPE. Whenever a pipe is not explicitly created as a private pipe, the first access to the pipe automatically creates it as a public pipe, and RMAN returns an error if it is told to use a public pipe.

Note:

If multiple RMAN sessions can run against the target database, then you must use unique pipe names for each session of RMAN. The DBMS_PIPE.UNIQUE_SESSION_NAME function is one method that can be used to generate unique pipe names.

Executing Multiple RMAN Commands In Succession Through a Pipe: Example

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 will pause and wait for the next command.

Start RMAN by connecting to a target database (required) and specifying the PIPE option. For example, issue:
```
% rman PIPE abc TARGET SYS/oracle @trgt
```
You can also specify the TIMEOUT option, which forces RMAN to exit automatically if it does not receive any input from the input pipe in the specified number of seconds. For example, enter:
```
% rman PIPE abc TARGET SYS/oracle@trgt TIMEOUT = 60
```
Connect to the target database and put the desired commands on the input pipe by using DBMS_PIPE.PACK_MESSAGE and DBMS_PIPE.SEND_MESSAGE. In pipe mode, RMAN issues message RMAN-00572 when it is ready to accept input instead of displaying the standard RMAN prompt.
Read the RMAN output from the output pipe by using DBMS_PIPE.RECEIVE_MESSAGE and DBMS_PIPE.UNPACK_MESSAGE.
Repeat steps 2 and 3 to execute further commands with the same RMAN instance that was started in step 1.
If you used the TIMEOUT option when starting RMAN, RMAN terminates automatically after not receiving any input for the specified length of time. To force RMAN to terminate immediately, send the EXIT command.

Executing RMAN Commands In a Single Job Through a Pipe: Example

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 will exit.

After connecting to the target database, create a pipe (if it does not already exist under the name ORA$RMAN_pipe_IN).
Put the desired commands on the input pipe. In pipe mode, RMAN issues message RMAN-00572 when it is ready to accept input instead of displaying the standard RMAN prompt.
Start RMAN with the PIPE option, and specify TIMEOUT = 0. For example, enter:
```
% rman PIPE abc TARGET SYS/oracle@trgt TIMEOUT = 0
```
RMAN reads the commands that were put on the pipe and executes them by using DBMS_PIPE.PACK_MESSAGE and DBMS_PIPE.SEND_MESSAGE. When it has exhausted the input pipe, RMAN exits immediately.
Read RMAN output from the output pipe by using DBMS_PIPE.RECEIVE_MESSAGE and DBMS_PIPE.UNPACK_MESSAGE.

See Also:
Oracle Database PL/SQL Packages and Types Reference for documentation on the DBMS_PIPE package