dbms_backup_restore.backupbackuppiece

package dbms_backup_restore
  PROCEDURE backupBackupPiece( bpname   IN   varchar2
                              ,fname    IN   varchar2
                              ,handle   OUT  varchar2
                              ,comment  OUT  varchar2
                              ,media    OUT  varchar2
                              ,concur   OUT  boolean
                              ,recid    OUT  number
                              ,stamp    OUT  number
                              ,tag      IN   varchar2  default NULL
                              ,params   IN   varchar2  default NULL
                              ,media_pool IN binary_integer default 0
                              ,reuse    IN boolean default FALSE);

  -- This procedure copies a backup piece that was originally written to an
  -- operating system file, onto sequential media. This requires allocating
  -- a sequential device first. Of course, this could copy to another operating
  -- system file if the NULL device is allocated.
  --
  -- A record is made in the controlfile as if the piece was just created and
  -- written to this output file. It can be queried from V$BACKUP_PIECE using
  -- the record ID returned. Note that no new entries are made in V$BACKUP_SET,
  -- V$BACKUP_DATAFILE, V$BACKUP_REDOLOG, or V$BACKUP_CORRUPTION.
  --
  -- It is acceptable to copy a backup piece when a backup controlfile has been
  -- mounted. However, note that the files named in the control
  -- file may no longer exist.
  --
  -- Input parameters:
  --   bpname
  --     Operating system file name of the existing backup piece. This will be
  --     read and copied to sequential media.
  --   fname
  --     Filename of the backup piece to be created. This will be translated
  --     into a file handle after the piece is created.
  --   tag
  --     The tag stored in the file header of the copied and backed up files,
  --     and also in the controlfile records describing those files.
  --   params
  --     This string is simply passed to the sequential file create OSD. It is
  --     completely port and device specific.
  -- Output parameters:
  --   handle
  --     The handle for the backup piece that was created. This is a permanent
  --     name that can be used to read this sequential file for restore. It
  --     can only be used with the same device type that was allocated at
  --     this call.
  --   comment
  --     The comment for the backup piece. This is any string that the OSD
  --     decided was useful. It will be a null string for operating system
  --     files. Note that this comment is not the same as the comment where the
  --     original backup piece was created.
  --   media
  --     The media handle returned by the operating system. This is the name
  --     of media where the file was created. It is not needed for retrieving
  --     the backup piece. For some devices this information will not be
  --     provided.
  --   concur
  --     TRUE if the device type used to create this piece
  --     supports multiple processes concurrently accessing the same media.
  --     If FALSE, it is best to only have one process at a time
  --     doing a restore of backup pieces with the same media handle.
  --   recid
  --     This is the ID of the record in the controlfile where the
  --     information about this backup piece was recorded. It can be used as
  --     the primary key to query V$BACKUP_PIECE.
  --   stamp
  --     This is a number that can be used to verify that the row in
  --     V$BACKUP_PIECE is really for this backup piece. The stamp combined
  --     with recid makes a key that is unique for this backup piece for all
  --     time.
  --   media_pool
  --     a number from 0-255 whose meaning is defined by rman or by 3rd-party
  --     media management software.
  -- Exceptions:
  --   NO-INPUT-FILENAME (ora-19605)
  --     src_name must be assigned a non-NULL string in copyControlFile.
  --   NO-OUTPUT-FILENAME (ora-19574)
  --     dest_name must be assigned a non-NULL string in copyControlFile.
  --   NAME-TOO-LONG (ora-19704)
  --     The specified file name is longer than the port-specific
  --     maximum file name length.
  --   TAG-TOO-LONG (ora-19705)
  --     The tag is longer than the port-specific maximum.
  --   DEVICE-PARM-TOO-LONG (ora-19702)
  --     The device parameter is longer than the port-specific maximum.
  --   CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
  --     The database is in the process of being opened, closed, mounted,
  --     or dismounted.
  --   DATABASE-NOT-MOUNTED (ora-1507)
  --     The database is not mounted.
  --   FILE-IN-USE (ora-19584)
  --     The specified output file is already in use by the database as a
  --     datafile or online redo log.
  --   DEVICE-NOT-ALLOCATED (ora-19569)
  --     This session does not have a device allocated.
  --   CANT-IDENTIFY-FILE (ora-19505)
  --     The file can not be opened.
  --   END-OF-VOLUME (ora-19630)
  --     end-of-volume was encountered while copying the backup piece.
  --   CORRUPT_BLOCK (ora-19599)
  --     A corrupt block was encountered.  Corrupt blocks are not tolerated
  --     in backup pieces.
  --   NOT-A-BACKUP-PIECE (ora-19608)
  --     The input file is not recognizable as a backup piece.
  --   CORRUPT-DIRECTORY (ora-19610)
  --     The backup piece directory is corrupt.
  --   IO-ERROR
  --     An error occured attempting to read the input file.
  --   CREATE-ERROR
  --     An error was reported by the OSD to create the sequential file.
  --   WRITE-ERROR
  --     An error was reported by the sequential write OSD.