8.7 Cataloging Archived Logs and User-Managed Copies

You can make RMAN aware of the existence of archived logs that are not recorded in the repository as well as file and backup piece copies that are created through means other than RMAN. This section contains the following topics:

About Cataloging Archived Logs and User-Managed Copies
Cataloging User-Managed Datafile Copies
Cataloging Backup Pieces
Cataloging All Files in a Disk Location

8.7.1 About Cataloging Archived Logs and User-Managed Copies

The target database control file keeps records of all archived logs generated by the target database as well as all RMAN backups. The purpose of the CATALOG command is to add metadata to the repository when it does not have a record of files that you want RMAN to know about.

Run the RMAN CATALOG command when:

You use an operating system utility to make copies of datafiles, archived logs, or backup pieces. In the case, the repository has no record of them.
You perform recovery with a backup control file and you change the archiving destination or format during recovery. In this situation, the repository will not have information about archived logs needed for recovery. Hence, you must catalog these logs.
You want to catalog datafile copy as a level 0 backup, thus enabling you to perform an incremental backup later by using the datafile copy as the base of an incremental backup strategy
You want to catalog user-managed copies of Oracle7 database files created before you migrated to a higher release, or of Oracle8 and higher database files created before you started to use RMAN. These datafile copies enable you to recover the database if it crashes after migration but before you have a chance to take a backup of the migrated database.

Whenever you make a user-managed copy, for example, by using the UNIX cp command to copy a datafile, make sure to catalog it. When making user-managed copies, you can use the ALTER TABLESPACE ... BEGIN/END BACKUP statement to make datafile copies off an online tablespace. Although RMAN does not create such datafile copies, you can use the CATALOG command to add them to the recovery catalog so that RMAN is aware of them.

For a user-managed copy to be cataloged, it must be:

Accessible on disk
A complete image copy of a single file
Either a datafile copy, control file copy, archived redo log copy, or backup piece copy

For example, if you store datafiles on mirrored disk drives, then you can create a user-managed copy by breaking the mirror. In this scenario, use the CATALOG command to notify RMAN of the existence of the user-managed copy after breaking the mirror. Before reforming the mirror, run a CHANGE ... UNCATALOG command to notify RMAN that the file copy no longer exists.

8.7.2 Cataloging User-Managed Datafile Copies

Use the CATALOG command to propagate information about user-managed copies to the RMAN repository. After the files are cataloged, you can run LIST or query V$BACKUP_FILES to confirm.

To create and catalog a user-managed copy of a datafile:

Make a datafile copy with an operating system utility. ALTER TABLESPACE BEGIN/END BACKUP is necessary if the database is open and the datafiles are online while the backup is in progress. This example backs up an online datafile.
```
SQL> ALTER TABLESPACE users BEGIN BACKUP;
% cp $ORACLE_HOME/oradata/trgt/users01.dbf /tmp/users01.dbf;
SQL> ALTER TABLESPACE users END BACKUP;
```

After connecting to the target database and, if desired, the recovery catalog, run the CATALOG command. For example, enter:

CATALOG DATAFILECOPY '/tmp/users01.dbf';

If you try to catalog a datafile copy from a database other than the connected target database, then RMAN issues an error such as the following:

RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-03009: failure of catalog command on default channel at 08/29/2001 14:44:34
ORA-19563: datafile copy header validation failed for file /tmp/tools01.dbf

8.7.3 Cataloging Backup Pieces

You can catalog backup pieces on disk. This technique is useful if you use an operating system utility to copy backup pieces from location to another on the same host, or from one host to another. You can even catalog a backup piece from a prior incarnation of the database. RMAN can determine whether that backup piece can be used during a subsequent restore and recovery operation.

To catalog a backup piece:

After connecting RMAN to the target database, catalog the filenames of the backup pieces. For example:
```
CATALOG BACKUPPIECE '/disk2/09dtq55d_1_2', '/disk2/0bdtqdou_1_1';
```
After a backup piece is cataloged, you can display its metadata by querying V$BACKUP_PIECE, V$BACKUP_SET, V$BACKUP_DATAFILE, V$BACKUP_REDOLOG, and V$BACKUP_SPFILE.
Note:
If you are cataloging backup pieces from a release earlier than Oracle9i, you can achieve significant performance gains by cataloging the highest copy numbers first. Otherwise, RMAN must examine all pieces to determine the correct order. For example, catalog copy 3 of a piece before copy 2:
```
CATALOG BACKUPPIECE '/disk2/09dtq55d_1_3', 
'/disk2/09dtq55d_1_2';
```
Backup pieces from Oracle Database Release 10g are not affected by this issue and can be cataloged in any order.
You can query V$ views to verify your changes. For example:
```
SELECT HANDLE FROM V$BACKUP_PIECE;
```
See Also:
Oracle Database Backup and Recovery Reference for CATALOG BACKUPPIECE restrictions

8.7.4 Cataloging All Files in a Disk Location

If you use Automatic Storage Management (ASM), an Oracle Managed Files framework, or the flash recovery area, then you may need a way to recatalog files that are known to the disk management system but are no longer listed in the RMAN repository. This situation can occur when the intended mechanisms for tracking filenames fails due to media failure, software bug, or user error.

The CATALOG START WITH command enables you to search through all files in an ASM disk group, Oracle Managed Files location, or traditional file system directory and investigate those that are not recorded in the RMAN repository. If the command can catalog a file, then it will; if it cannot catalog it, then it makes its best guess about the contents of the skipped file.

To catalog all files in a disk location:

After connecting RMAN to the target database, specify the disk location whose files you want to catalog. For example:

RMAN> CATALOG START WITH '+disk'; # catalog all files from an ASM disk group
RMAN> CATALOG START WITH '/fs1/datafiles/'; # catalog all files in directory

Note:

Wildcard characters are not legal in the START WITH clause.

8.7.5 Cataloging Flash Recovery Area Contents

The CATALOG RECOVERY AREA command will catalog all files in the flash recovery area. During this operation, any files in the recovery area that are not listed in the RMAN repository are added to the RMAN repository. For example:

CATALOG RECOVERY AREA;