1 PACKAGE dbms_backup_restore IS
2
3 -------------
4 -- Version --
5 -------------
6
7 -- Advance the min numbers whenever support is removed for old
8 -- versions of the RMAN client. Advance the max number whenever
9 -- new functions are added or existing ones are changed (once per release
10 -- cycle).
11
12 protocol_version_number_min NUMBER := 8; -- major release number
13 protocol_release_number_min NUMBER := 0; -- maintenance release number
14 protocol_update_number_min NUMBER := 4; -- application release number
15 protocol_component_number_min NUMBER := 0; -- component release number
16
17 protocol_version_number_max NUMBER := 12; -- major release number
18 protocol_release_number_max NUMBER := 1; -- maintenance release number
19 protocol_update_number_max NUMBER := 0; -- application release number
20 protocol_component_number_max NUMBER := 2; -- component release number
21
22 snapshot_enqueue_busy EXCEPTION;
23 PRAGMA EXCEPTION_INIT(snapshot_enqueue_busy, -230);
24
25 snapshot_name_not_set EXCEPTION;
26 PRAGMA EXCEPTION_INIT(snapshot_name_not_set, -231);
27
28 snapshot_not_made EXCEPTION;
29 PRAGMA EXCEPTION_INIT(snapshot_not_made, -232);
30
31 inconsistant_read EXCEPTION;
32 PRAGMA EXCEPTION_INIT(inconsistant_read, -235);
33
34 record_not_found EXCEPTION;
35 PRAGMA EXCEPTION_INIT(record_not_found, -19571);
36
37 inc_scn_matches_df_scn EXCEPTION;
38 PRAGMA EXCEPTION_INIT(inc_scn_matches_df_scn, -19648);
39
40 file_not_found EXCEPTION;
41 PRAGMA EXCEPTION_INIT(file_not_found, -19625);
42
43 file_validation_failure EXCEPTION;
44 PRAGMA EXCEPTION_INIT(file_validation_failure, -19563);
45
46 archivelog_validate_error EXCEPTION;
47 PRAGMA EXCEPTION_INIT(archivelog_validate_error, -19582);
48
49 archivelog_not_found EXCEPTION;
50 PRAGMA EXCEPTION_INIT(archivelog_not_found, -19579);
51
52 different_resetlogs EXCEPTION;
53 PRAGMA EXCEPTION_INIT(different_resetlogs, -19658);
54
55 -- following are backuppiece failover exceptions
56 not_a_backup_piece EXCEPTION;
57 PRAGMA EXCEPTION_INIT(not_a_backup_piece, -19608);
58
59 corrupt_directory EXCEPTION;
60 PRAGMA EXCEPTION_INIT(corrupt_directory, -19610);
61
62 corrupt_block EXCEPTION;
63 PRAGMA EXCEPTION_INIT(corrupt_block, -19599);
64
65 cant_identify_file EXCEPTION;
66 PRAGMA EXCEPTION_INIT(cant_identify_file, -19505);
67
68 retryable_error_exp EXCEPTION;
69 PRAGMA EXCEPTION_INIT(retryable_error_exp, -19624);
70
71 -- following exceptions are used in SPFILE and controlfile restore from
72 -- autobackup
73 spfile_not_in_bs EXCEPTION;
74 PRAGMA EXCEPTION_INIT(spfile_not_in_bs, -19687);
75 scf_not_in_bs EXCEPTION;
76 PRAGMA EXCEPTION_INIT(scf_not_in_bs, -19695);
77
78 -- this exception is used in copy code
79 identical_input_output_file EXCEPTION;
80 PRAGMA EXCEPTION_INIT(identical_input_output_file, -19635);
81
82 -- this exception is signaled if recovery area is not set
83 ra_not_set EXCEPTION;
84 PRAGMA EXCEPTION_INIT(ra_not_set, -19801);
85
86 -- this exception is not really an exception but a way to interrupt
87 -- the xtts restore once we have the names of the files that will be
88 -- restored so that the rman client can print them.
89 xtts_name_files EXCEPTION;
90 PRAGMA EXCEPTION_INIT(xtts_name_files, -19989);
91
92 file_type_mismatch EXCEPTION;
93 PRAGMA EXCEPTION_INIT(file_type_mismatch, -19620);
94
95 --***************
96 -- Record Types
97 --***************
98 -- DO NOT add new fields to existing record definition between releases. This
99 -- would cause RMAN executable incompatibility because the package definition
100 -- is also linked into RMAN executable. Rather define new record types if
101 -- existing record type doesn't suite your need.
102 --
103 -- It is better to have some spare fields in existing record type so as to
104 -- avoid definiting new record types.
105 --
106
107 --
108 -- This record captures block statistics for a file validation.
109 --
110 TYPE blockStat_t IS RECORD
111 (
112 filetype binary_integer, -- KSFD file type
113 dfnumber number, -- datafile number
114 thread binary_integer, -- archived log thread
115 sequence number, -- archived log sequence
116 highscn number, -- highest scn found in the datafile
117 examined number, -- total blocks examined
118 corrupt number, -- total blocks that are marked corrupt
119 empty number, -- total empty blocks
120 data_proc number, -- total data blocks that are processed
121 data_fail number, -- total data blocks that failed
122 index_proc number, -- total index blocks that are processed
123 index_fail number, -- total index blocks that failed
124 other_proc number, -- total other blocks that are processed
125 other_fail number, -- total other blocks that failed
126
127 -- Spare fields for future
128 spare1 number,
129 spare2 number,
130 spare3 number,
131 spare4 number,
132 spare5 number,
133 spare6 number,
134 spare7 date,
135 spare8 date
136 );
137
138 --
139 -- Table of block statistics
140 --
141 TYPE blockStatTable_t IS TABLE OF blockStat_t INDEX BY BINARY_INTEGER;
142
143 --
144 -- Record to describe a block range
145 --
146 TYPE blockRange_t IS RECORD
147 (
148 blknumber number,
149 dfnumber number,
150 range number,
151 spare1 number,
152 spare2 number,
153 spare3 number
154 );
155
156 --
157 -- Table of block ranges
158 --
159 TYPE blockRangeTable_t IS TABLE OF blockRange_t INDEX BY BINARY_INTEGER;
160
161 --
162 -- Register Auxiliary Datafile Copy records
163 --
164 TYPE register_auxdfc IS RECORD (
165 fname varchar2(1024),
166 dfnumber number,
167 tsnum number,
168 blksize number,
169 spare1 number default NULL,
170 spare2 number default NULL,
171 spare3 number default NULL,
172 spare4 number default NULL,
173 spare5 number default NULL);
174
175 TYPE register_auxdfc_list IS TABLE of register_auxdfc
176 INDEX BY BINARY_INTEGER;
177
178 --
179 -- Package constants
180 --
181 MAXSCNVAL constant number := 281474976710655;
182
183 --***************
184 -- Introduction
185 --***************
186 -- This package contains the interface to the kernel for creating and
187 -- restoring backups of datafiles and archived logs. Backups can exist on
188 -- sequential media such as tape. The kernel will read and write backups,
189 -- but it is the responsibility of the caller to catalog the names of the
190 -- backups.
191 --
192 -- None of the procedures in this package can be executed in a Multi
193 -- Threaded Server process. A connection to a dedicated server is required.
194 --
195 -- Many of these procedures create or retrieve records from the controlfile.
196 -- Each record is given a record ID and a stamp when it is created. The
197 -- record ID is a monotonically increasing integer that is incremented for
198 -- each new record that is created. A different counter is used for each
199 -- type of record. Only a certain number of records of each type are kept.
200 -- Thus records are overwritten when they get old, but the new record will
201 -- have a new record ID. The record ID should normally be unique but there
202 -- is the possibility of a backup controlfile restore or a create controlfile
203 -- that allows record IDs to be reused. A stamp is also allocated with every
204 -- new controlfile record to ensure there is no confusion between records
205 -- with the same record ID. The stamp is based on the time and date.
206
207 --*****************
208 -- Device control
209 --*****************
210 -- Unlike other Oracle files, backups may be put on removable media which
211 -- must be written sequentially. This may involve using a device to mount
212 -- the removable media. These procedures provide an interface for controlling
213 -- the device used for creating and restoring backups.
214
215 FUNCTION deviceAllocate( type IN varchar2 default NULL
216 ,name IN varchar2 default NULL
217 ,ident IN varchar2 default NULL
218 ,noio IN boolean default FALSE
219 ,params IN varchar2 default NULL )
220 RETURN varchar2;
221
222 -- Describe the device to be used for sequential I/O. For device types where
223 -- only one process at a time can use a device, this call allocates a device
224 -- for exclusive use by this session. The device remains allocated until
225 -- deviceDeallocate is called or session termination. The device can be used
226 -- both for creating and restoring backups.
227 --
228 -- Specifying a device allocates a context that exists until the session
229 -- terminates or deviceDeallocate is called. Only one device can be specified
230 -- at a time for a particular session. Thus deviceDeallocate must be called
231 -- before a different device can be specified. This is not a limitation since
232 -- a session can only read or write one backup at a time.
233 --
234 -- The other major effect of allocating a device is to specify the name space
235 -- for the backup handles (file names). The handle for a sequential file does
236 -- not necessarily define the type of device used to write the file. Thus it
237 -- is necessary to specify the device type in order to interpret the file
238 -- handle. The NULL device type is defined for all systems. It is the file
239 -- system supplied by the operating system. The sequential file handles are
240 -- thus normal file names.
241 --
242 -- A device can be specified either by name or by type.
243 -- If the type is specified but not the name, the system picks an
244 -- available device of that type.
245 -- If the name is specified but not the type, the type is determined
246 -- from the device.
247 -- If neither the type or the name is given, the backups are files in
248 -- the operating system file system.
249
250 -- Note that some types of devices, optical disks for example, can be shared
251 -- by many processes, and thus do not really require allocation of the device
252 -- itself. However we do need to allocate the context for accessing the
253 -- device, and we do need to know the device type for proper interpretation
254 -- of the file handle. Thus it is always necessary to make the device
255 -- allocation call before making most other calls in this package.
256 --
257 -- Input parameters:
258 -- type
259 -- If specified, this gives the type of device to use for sequential
260 -- I/O. The allowed types are port specific. For example a port may
261 -- support the type "TAPE" which is implemented via the Oracle tape
262 -- API. If no type is specified, it may be implied by specifying a
263 -- particular device name to allocate. The type should be allowed to
264 -- default to NULL if operating system files are to be used.
265 --
266 -- name
267 -- If specified, this names a particular piece of hardware to use for
268 -- accessing sequential files. If not specified, any available
269 -- device of the correct type will be allocated. If the device cannot
270 -- be shared, it is allocated to this session for exclusive use.
271 -- The name should be allowed to default to NULL if operating system
272 -- files are to be used.
273 --
274 -- ident
275 -- This is the users identifier that he uses to name this device. It
276 -- is only used to report the status of this session via
277 -- dbms_application_info. This value will be placed in the CLIENT_INFO
278 -- column of the V$SESSION table, in the row corresponding to the
279 -- session in which the device was allocated. This value can also
280 -- be queried with the dbms_application_info.read_client_info procedure.
281 --
282 -- noio
283 -- If TRUE, the device will not be used for doing any I/O. This allows
284 -- the specification of a device type for deleting sequential files
285 -- without actually allocating a piece of hardware. An allocation for
286 -- noio can also be used for issuing device commands. Note that some
287 -- commands may actually require a physical device and thus will get
288 -- an error if the allocate was done with noio set to TRUE.
289 --
290 -- params
291 -- This string is simply passed to the device allocate OSD. It is
292 -- completely port and device specific.
293 --
294 -- Returns:
295 -- It returns a valid device type. This is the type that should be
296 -- allocated to access the same sequential files at a later date. Note
297 -- that this might not be exactly the same value as the input string.
298 -- The allocate OSD may do some translation of the type passed in. The
299 -- return value is NULL when using operating system files.
300 --
301 -- Exceptions:
302 -- DEVICE-TYPE-TOO-LONG (ora-19700)
303 -- The device type is longer than the port-specific maximum.
304 -- DEVICE-NAME-TOO-LONG (ora-19701)
305 -- The device name is longer than the port-specific maximum.
306 -- MULTI-THREADED-SERVER (ora-19550)
307 -- This session is not connected to a dedicated server.
308 -- DEVICE-ALLOCATED (ora-19568)
309 -- This session already has a device allocated.
310 -- ALLOCATION-FAILURE (ora-19554)
311 -- The allocation failed. Other messages should also be issued.
312 -- DEVICE-BUSY (ora-19551)
313 -- The requested device is allocated to another session, or no
314 -- device was named,or all devices of the requested type are busy.
315 -- INVALID-DEVICE-TYPE (ora-19552)
316 -- The device type is not a recognized type.
317 -- INVALID-DEVICE-NAME (ora-19553)
318 -- The device name is not a recognized device.
319 -- DEVICE-ERROR (ora-19557)
320 -- The OSD returned an error.
321
322 PROCEDURE deviceCommand( cmd IN varchar2
323 ,params IN varchar2 default NULL );
324
325 -- Send an arbitrary command to the currently allocated device.
326 -- Input parameters:
327 -- cmd
328 -- A text string for the command. The syntax and semantics of the text
329 -- string are completely port and device specific.
330 -- params
331 -- A text string for the parameters. The syntax and semantics of the text
332 -- string are completely port and device specific.
333 --
334 -- Exceptions:
335 -- DEVICE-PARM-TOO-LONG (ora-19702)
336 -- The device parameter is longer than the port-specific maximum.
337 -- DEVICE-COMMAND-TOO-LONG (ora-19703)
338 -- The device command is longer than the port-specific maximum.
339 -- DEVICE-NOT-ALLOCATED (ora-19569)
340 -- This session does not have a device allocated.
341 -- DEVICE-ERROR (ora-19557)
342 -- The OSD returned an error.
343 -- DEVICE-COMMAND-ERROR (ora-19559)
344 -- The command failed. Other messages should also be issued.
345
346 PROCEDURE deviceDeallocate( params IN varchar2 default NULL );
347
348 -- Release the currently allocated device. This also cleans up the context
349 -- that was created by deviceAllocate. This must be done before ending
350 -- the session. The current device must be deallocated before a different
351 -- one can be allocated. This may be done in the middle of a backup or
352 -- restore conversation for cases where different pieces of the same backup
353 -- set are on different media.
354 --
355 -- Input parameters:
356 -- params
357 -- This string is simply passed to the device deallocate OSD. It is
358 -- completely port and device specific.
359 --
360 -- Exceptions:
364 -- This session does not have a device allocated.
361 -- DEVICE-PARM-TOO-LONG (ora-19702)
362 -- The device parameter is longer than the port-specific maximum.
363 -- DEVICE-NOT-ALLOCATED (ora-19569)
365 -- DEVICE-ERROR (ora-19557)
366 -- The OSD returned an error. The device will still be deallocated from
367 -- this package even when this error is returned. Thus a different
368 -- device may then be allocated
369 -- DEVICE-DEALLOCATION-ERROR (ora-19558)
370 -- The command failed. Other messages should also be issued.
371
372 PROCEDURE deviceStatus( state OUT binary_integer
373 ,type OUT varchar2
374 ,name OUT varchar2
375 ,bufsz OUT binary_integer
376 ,bufcnt OUT binary_integer
377 ,kbytes OUT number
378 ,readrate OUT binary_integer
379 ,parallel OUT binary_integer );
380
381 NO_DEVICE constant binary_integer := 0;
382 NO_IO_ALLOC constant binary_integer := 1;
383 EXCL_ALLOC constant binary_integer := 2;
384 CONCUR_ALLOC constant binary_integer := 3;
385 FILESYSTEM constant binary_integer := 4;
386
387 -- deviceStatus returns information about the currently allocated device.
388 -- It is useful for informational purposes only. It can be called even if
389 -- there is no device allocated. When no device is allocated the state will
390 -- be NO_DEVICE and all the other values will be NULL.
391 --
392 -- Note that there are no exceptions since this does nothing but return
393 -- information about this session.
394 --
395 -- Output parameters:
396 -- state
397 -- This defines what kind of allocation has been done. The constants
398 -- have the following meanings.
399 -- NO_DEVICE
400 -- No device has been allocated by this session. The other output
401 -- values will be NULL when this state is returned. Note that this
402 -- state does not signal an error.
403 -- NO_IO_ALLOC
404 -- A device, or at least a device type, has been allocated, but the
405 -- noio parameter was TRUE when deviceAllocate was called. It is not
406 -- possible to do a backup or restore, but changeBackupPiece can be
407 -- called.
408 -- EXCL_ALLOC
409 -- A device has been exclusively allocated to this session. This type
410 -- of device can not support access by more than one session. A tape
411 -- drive is typical of this kind of allocate.
412 -- CONCUR_ALLOC
413 -- A device has been allocated which supports multiple processes
414 -- concurrently accessing its storage. A hierarchical storage manager
415 -- is an example of this kind of device. The device name may be NULL
416 -- for this kind of allocation since there may not be any particular
417 -- piece of hardware reserved.
418 -- FILESYSTEM
419 -- This means that deviceAllocate was called with NULL type and name.
420 -- The allocated device is the operating system's file system. This
421 -- naturally allows concurrent accesses. The type and name parameters
422 -- returned will both be NULL.
423 -- type
424 -- This is the type name of the allocated device. This may be different
425 -- than the value passed in to deviceAllocate if a generic device type
426 -- was converted to a specific type when the allocation was done. For
427 -- example maybe the type given to deviceAllocate was 'TAPE'. This value
428 -- could then be 'IBM3490'. NULL may have been given to deviceAllocate
429 -- and the type determined from the device name. The returned type will
430 -- be NULL only when the state is FILESYSTEM.
431 -- name
432 -- This is the name of the particular piece of hardware that was
433 -- allocated. For device types that do not reserve particular pieces
434 -- of hardware this will be NULL.
435 -- bufsz
436 -- bufcnt
437 -- These two arguments describe the memory buffers that were allocated
438 -- to do I/O to this device. If opened for noio these values will be
439 -- zero. The bufsz is in bytes.
440 -- kbytes
441 -- readrate
442 -- parallel
443 -- These are the current values of the backup limits that have been set
444 -- by calls to setLimit.
445
446 --***********************************
447 -- Backup Limits Setting Procedures--
448 --***********************************--
449 -- There are a few limits that can be set to control the performance of
450 -- taking a backup, and the size of each piece of the backup. The limit
451 -- values are kept per session. Limits are initially set to infinity. Once
452 -- changed, they persist until the device is deallocated. They may be changed
453 -- at any time while a device is allocated. For each limit there is a
454 -- constant that names it for the purpose of changing it. The following
455 -- limits are defined.
456
457 KBYTES constant binary_integer := 1;
458 READRATE constant binary_integer := 2;
459 PARALLEL constant binary_integer := 3;
460 DUPCNT constant binary_integer := 4;
461 DUR_EST_SECS constant binary_integer := 5;
462 DUR_ENDTIME constant binary_integer := 6;
463 MAX_READ_KBYTES constant binary_integer := 7;
464 SLEEP_SECS constant binary_integer := 8;
468 --
465 DUR_SOFTENDTIME constant binary_integer := 9;
466
467 -- KBYTES: The number of bytes that may be written to a backup piece.
469 -- It is given in units of 1024 bytes to avoid a 4 gigabyte limit.
470 -- Once this number of bytes have been written, the backup piece
471 -- is closed and the currently executing backupPieceCreate
472 -- procedure returns control. If the backup set is not complete,
473 -- the backupPieceCreate must be called again to
474 -- continue the backup into another backup piece.
475 --
476 -- This limit is useful for cases where the size of the output
477 -- media is known to the user but not to the operating system.
478
479 -- READRATE: The number of buffers that may be read per file per second.
480 --
481 -- Use of this option causes the backup to limit the rate at
482 -- which it reads blocks from a file. This limit has no effect if
483 -- it is greater than the actual capacity. For some output devices
484 -- it may be necessary to read from multiple files in order to keep
485 -- the device streaming.
486 --
487 -- This limit is useful to prevent the backup process from
488 -- consuming too much disk bandwidth, thereby degrading on-line
489 -- performance.
490 --
491 -- Note that this limit is implemented by counting down the limit
492 -- number, and check if a second has passed since the counter was
493 -- last initialized. Thus the limit is only an average over one
494 -- second, not enforced on every I/O.
495
496 -- PARALLEL: The maximum number of files that will be open for reading at
497 -- the same time.
498 --
499 -- If this limit is greater than the number of files in the backup,
500 -- all files can be open for reading. Note that each open file can
501 -- be read at no more than READRATE I/O's per second, so this
502 -- limits the rate at which the output file can be written.
503 -- This limit is useful to keep the number of open files down to a
504 -- reasonable value when there are a large number of small redo
505 -- logs in a backup.
506 --
507 -- Note that changing this value during a conversation has no
508 -- effect.
509 -- DUPCNT: Duplex count for the channel. Allowed range for values is 1-4.
510 -- DUR_EST_SECS : Number of seconds estimated for the backupset/copy
511 -- performed on this device.
512 -- DUR_ENDTIME : Time limit for the backupset/copy performed on this device.
513 -- If the backup/copy could not be completed by this time,
514 -- server returns an time out error. Client can extend the time
515 -- and re-try the operation if required.
516 -- MAX_READ_KBYTES : This limits specifies the maximum number of kilo bytes
517 -- that can be read during backup/copy.
518 -- SLEEP_SECS : This is artifial time introduced during the last
519 -- backup/copy on this channel.
520 -- DUR_SOFTENDTIME : Time limit for the backupset/copy after which the job
521 -- can run at full speed.
522
523 PROCEDURE setLimit( name IN binary_integer
524 ,value IN number );
525
526 -- Set a limit to a particular value. The limit keeps this value until
527 -- the current device is deallocated, or a call is made to change the limit.
528 --
529 -- Input parameters:
530 -- name
531 -- The limit number to set. Valid limit numbers are the constants above.
532 -- value
533 -- The value of the limit.
534 -- Exceptions:
535 -- INVALID-LIMIT-NUMBER (ora-19560)
536 -- An invalid limit number was specified.
537 -- DEVICE-NOT-ALLOCATED (ora-19569)
538 -- This session does not have a device allocated.
539 -- DEVICE-BUSY (ora-19551)
540 -- The requested device is allocated to another session,
541 -- or all devices of the requested type are busy.
542 -- DEVICE-ERROR (ora-19557)
543 -- The OSD returned an error.
544
545 PROCEDURE reInit;
546
547 -- Reset all limits to infinity.
548 --
549 -- Exceptions:
550 -- DEVICE-NOT-ALLOCATED (ora-19569)
551 -- This session does not have a device allocated.
552
553
554 --********************************************
555 -- Backup Conversation Initiation Procedures--
556 --*******************************************--
557
558 -- A backup conversation is a sequence of calls to create a backup of
559 -- one or more files. The files may be either archived redo logs or
560 -- datafiles. A controlfile may be included in a datafile backup. The backup
561 -- consists of one or more sequential files called backup pieces. The pieces
562 -- taken together make a backup set. A successful backup conversation
563 -- consists of the following phases:
564 -- 1) Start conversation specifying the type of backup.
565 -- 2) Name the files that go into the backup.
566 -- 3) Create each piece of the backup.
567 -- 4) Collect data on the contents of the backup.
568
569 PROCEDURE backupSetDataFile( set_stamp OUT number
570 ,set_count OUT number
571 ,nochecksum IN boolean default FALSE
572 ,tag IN varchar2 default NULL
576 -- backupSetDataFile starts a backup conversation to backup datafiles and
573 ,incremental IN boolean default FALSE
574 ,backup_level IN binary_integer default 0 );
575
577 -- possibly a controlfile.
578
579 PROCEDURE backupSetArchivedLog( set_stamp OUT number
580 ,set_count OUT number
581 ,nochecksum IN boolean default FALSE );
582
583 -- backupSetArchivedLog starts a backup conversation to backup archived redo
584 -- logs.
585
586 -- No information is placed into the controlfile until the entire backup
587 -- set is complete. The setid and stamp parameters returned by
588 -- backupSetDataFile or backupSetArchivedLog are the key that can be used to
589 -- identify all controlfile data created by this conversation.
590 --
591 -- The database must be mounted to create a backup set. A device must
592 -- have already been allocated for creating backup pieces.
593 --
594 -- It is acceptable to create a backup when a backup controlfile has been
595 -- mounted. However, note that the files named in the controlfile
596 -- may no longer exist. Logs archived since the controlfile backup will
597 -- not be in V$ARCHIVED_LOG. Missing files will not be detected until they
598 -- are read while creating a backup piece. This makes it impossible to
599 -- continue the backup conversation.
600 --
601 -- A row is also added to V$SESSION_LONGOPS to record the progress of
602 -- the backup. The whole column will contain the number of blocks that
603 -- will be read from the datafiles or archived redo logs. The total will be
604 -- increased as files are added to the backup. Progress will be indicated
605 -- as the backup pieces are created.
606 --
607 -- When backing up datafiles, blocks that have never been modified will
608 -- not be put into the backup. Note that this does not avoid blocks that
609 -- were once in use but are not part of any object at this time. A future
610 -- version may avoid these blocks.
611 --
612 -- Input parameters:
613 -- tag
614 -- The tag stored in the file header of the copied and backed up files,
615 -- and also in the controlfile records describing those files.
616 -- incremental
617 -- Specifies whether or not this backup set is part of the database's
618 -- incremental backup hierarchy. If false, then the backup is not part
619 -- of the hierarchy.This does not affect the file backup process - it is
620 -- simply stored in the controlfile and reflected in the V$BACKUP_SET and
621 -- V$BACKUP_DATAFILE views.
622 -- nochecksum
623 -- If true, we will not calculate a checksum on blocks that
624 -- do not have a checksum. If there is a checksum in a block it is
625 -- always validated after reading, and it is saved in the backup.
626 -- backup_level
627 -- This indicates the location of this backup set in the database's
628 -- incremental backup hierarchy. If zero, then a full backup will be
629 -- produced, which must be restored with restoreSetDataFile. If
630 -- non-zero, then a valid SCN must be supplied with all calls to
631 -- backupDataFile[Copy], and an incremental backup set will be produced,
632 -- which must be restored with applySetDataFile.
633 --
634 -- Output parameters:
635 -- set_stamp and set_count, taken together, form the primary key used to
636 -- identify records for this backup set in the following fixed views:
637 -- V$BACKUP_SET
638 -- V$BACKUP_PIECE
639 -- V$BACKUP_DATAFILE
640 -- V$BACKUP_REDOLOG
641 -- V$BACKUP_CORRUPTION
642 --
643 -- Note that set_stamp and set_count are NOT the recid and stamp of the
644 -- circular-reuse record that is created in v$backup_set for this backup
645 -- set. These separately maintained fields are used as the backup set
646 -- key because they are obtained when the backup set is begun and can be
647 -- placed in each backup piece. The recid/stamp of the v$backup_set
648 -- record are not obtained until the backup set is complete, and so cannot
649 -- be placed in each backup piece.
650 --
651 -- set_stamp
652 -- This is a timestamp that is used to identify the backup set.
653 -- set_count
654 -- This is a counter that is kept in the database information
655 -- section of the mounted controlfile. During backup set
656 -- conversation initialization, a read/write controlfile transaction is
657 -- used to increment this counter by one.
658
659 -- Exceptions:
660 -- TAG-TOO-LONG (ora-19705)
661 -- The tag is longer than the port-specific maximum.
662 -- CONVERSATION-ACTIVE (ora-19590)
663 -- A backup or restore conversation is already active in this session.
664 -- MULTI-THREADED-SERVER (ora-19550)
665 -- This session is not connected to a dedicated server.
666 -- ALTERNATE-CONTROLFILE-OPEN (ora-226)
667 -- This session's fixed tables are currently re-directed to a snapshot
668 -- or other alternate controlfile.
669 -- DATABASE-NOT-MOUNTED (ora-1507)
670 -- No database is mounted.
671
672 --*********************************
673 -- Backup File List Specification
674 --*********************************
675
676 -- The second phase of taking a backup is to list the files that go into
677 -- the backup. Files are listed by controlfile record. A number of files
678 -- may need to be in a single backup in order to provide enough data to
682 -- any particular datafile. Restoring only one file from a backup set
679 -- keep the output device streaming. However, backups of large databases
680 -- should be partitioned into different backup conversations so that the
681 -- conversations can be done in parallel, minimizing the restore times for
683 -- requires a sequential scan through the entire backup set, until the
684 -- required file is completely restored.
685 --
686 -- Note that an error adding a file to a backup does not terminate the
687 -- backup conversation. More files can still be added, or piece creation
688 -- can begin, if at least one file has been successfully added.
689
690 PROCEDURE backupDataFile( dfnumber IN binary_integer
691 ,since_change IN number default 0
692 ,max_corrupt IN binary_integer default 0 );
693
694 -- Add a data file to a backup set. backupDataFile backups a current
695 -- datafile in the database. The file may be either online or offline.
696
697 PROCEDURE backupDataFileCopy( copy_recid IN number
698 ,copy_stamp IN number
699 ,since_change IN number default 0
700 ,max_corrupt IN binary_integer default 0 );
701
702 -- Add a data file to a backup set. backupDataFileCopy backups a copy of
703 -- a datafile that was made via copyDataFile or some operating system
704 -- utility. If the copy was made by operation system utility, it may be
705 -- necessary to call inspectDataFileCopy to build a controlfile record
706 -- for this copy before calling backupDataFileCopy.
707
708 -- From the time that a datafile is named as part of a backup set until
709 -- the last backup piece containing any portion of the datafile is
710 -- successfully created, the backup session holds a shared file access
711 -- enqueue on the file, making it impossible to drop it from the database
712 -- or take it offline normal. If the file goes offline immediate before
713 -- it is opened for placing in the backup set, it will fail with an error
714 -- reading the file.
715 --
716 -- Input parameters:
717 -- dfnumber
718 -- Data file number of a file to backup. This refers to the file that
719 -- is currently accessible via SQL commands.
720 -- copy_recid
721 -- The record ID from V$DATAFILE_COPY for the datafile copy. This
722 -- is the record ID returned from copyDataFile or inspectDataFileCopy.
723 -- copy_stamp
724 -- The stamp corresponding to copy_recid. This is to insure that the
725 -- record is the same one that was selected.
726 -- since_change
727 -- Only blocks modified since this SCN will be included in the backup.
728 -- This creates an incremental backup that can only be applied to a
729 -- datafile that is checkpointed between this SCN and the backup's
730 -- checkpoint. Note that an incremental backup cannot change the
731 -- resetlogs stamp in a file, so this SCN may not be less than the
732 -- ressetlogs SCN in the file header.
733 -- max_corrupt
734 -- Up to this many data blocks from this file can be made corrupt in the
735 -- backup. The whole backup will fail if more blocks are found corrupt.
736 -- This does not count blocks that were already marked corrupt in the
737 -- datafile. It only counts blocks that failed verification when they
738 -- were read, and had to be reformatted to be corrupt in the backup. Note
739 -- that such blocks are always included in incremental backups since we
740 -- cannot know when the last change was made.
741 -- Exceptions:
742 -- INVALID-SCN (ora-19706)
743 -- The incremental start SCN could not be converted into the internal
744 -- SCN representation because it is non-integral, less than zero, or
745 -- greater than the highest possible SCN.
746 -- CONVERSATION-NOT-ACTIVE (ora-19580)
747 -- A backup conversation was not started before specifying files.
748 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
749 -- The database is in the process of being opened, closed, mounted,
750 -- or dismounted.
751 -- DATABASE-NOT-MOUNTED (ora-1507)
752 -- The database is not mounted.
753 -- WRONG-CONVERSATION-TYPE (ora-19592)
754 -- The backup set is not for datafiles and controlfiles.
755 -- NAMING-PHASE-OVER (ora-19604)
756 -- backuppiececreate has already been called. No files can be named
757 -- after piececreate is called.
758 -- INVALID-FILE-NUMBER (ora-19570)
759 -- The specified real file number is out of range.
760 -- DUPLICATE-DATAFILE (ora-19593)
761 -- Only one version of a datafile can exist in the same backup set.
762 -- DATABASE-NOT-OPEN (ora-1138)
763 -- Some other instance is open, but this instance is not open. Either
764 -- open this instance or close all other instances.
765 -- FILE-IS-FUZZY (ora-19602)
766 -- The file is fuzzy and the database is in noarchivelog mode.
767 -- FILE-BEING-RESIZED (ora-19572)
768 -- The file is in the middle of a resize operation. Wait for the
769 -- resize to complete.
770 -- CANT-GET-REAL-FILE-ENQUEUE (ora-19573)
771 -- A datafile is locked. Another backup or restore could be in progress,
772 -- or some other database activity, such as media recovery, holds an
773 -- exclusive enqueue on the file.
774 -- FILE-NOT-FOUND (ora-19625)
775 -- The file can not be opened.
776 -- BLOCKSIZE-MISMATCH (ora-19597)
777 -- Only files with the same blocksize can be put into the same backup
781 -- The file is not the one described by the controlfile record.
778 -- set. This is not really a restriction in 8.0 since there is only
779 -- one datafile block size per database.
780 -- FILE-VALIDATION-FAILURE (ora-19563)
782 -- RECORD-NOT-FOUND (ora-19571)
783 -- The specified datafile copy record does not exist.
784 -- RECORD-NOT-VALID (ora-19588)
785 -- The specified datafile copy record is no longer valid - it has been
786 -- marked as deleted.
787 -- RETRYABLE-ERROR (ora-19624)
788 -- This is a pseudo-error that is placed on top of the stack when an
789 -- error is signalled but it may be possible to continue the
790 -- conversation.
791 -- INCREMENTAL-TOO-FAR (ora-xxxx)
792 -- The since_change value is less than the resetlogs SCN for the file.
793 -- IO-ERROR
794 -- An error occured attempting to read the file header.
795
796 PROCEDURE backupControlFile( cfname IN varchar2 default NULL );
797
798 -- Include the controlfile in the backup set. If a file name is given,
799 -- it must be a backup or standby controlfile that will be copied into
800 -- the backup set. If no file name is given, a backup is made from the
801 -- snapshot controlfile. The snapshot controlfile enqueue will be acquired
802 -- in mode S if it is not held already.
803 --
804 -- Input parameters:
805 -- cfname
806 -- Operating system file name of a standby or backup controlfile to
807 -- include in the backup set.
808 -- Exceptions:
809 -- NAME-TOO-LONG (ora-19704)
810 -- The specified controlfile name is longer than the port-specific
811 -- maximum file name length.
812 -- CONVERSATION-NOT-ACTIVE (ora-19580)
813 -- A backup conversation was not started before specifying files.
814 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
815 -- The database is in the process of being opened, closed, mounted,
816 -- or dismounted.
817 -- DATABASE-NOT-MOUNTED (ora-1507)
818 -- The database is not mounted.
819 -- WRONG-CONVERSATION-TYPE (ora-19592)
820 -- The backup set is not for datafiles and controlfiles.
821 -- NAMING-PHASE-OVER (ora-19604)
822 -- backuppiececreate has already been called. No files can be named
823 -- after piececreate is called.
824 -- DUPLICATE-CONTROLFILE (ora-19594)
825 -- Only one version of the controlfile can exist in the same backup set.
826 -- SNAPSHOT-ENQUEUE-ALREADY-HELD (ora-229)
827 -- This process already holds the snapshot controlfile enqueue.
828 -- SNAPSHOT-ENQUEUE-BUSY (ora-230)
829 -- The snapshot controlfile enqueue is in use by another process.
830 -- CONTROLFILE-IS-ACTIVE (ora-19607)
831 -- The controlfile name is the same as one of the controlfiles specified
832 -- in the init.ora file.
833 -- FILE-NOT-FOUND (ora-19625)
834 -- The file can not be opened.
835 -- FILE-VALIDATION-FAILURE (ora-19563)
836 -- A file that was specified by name is not a controlfile for the current
837 -- database.
838 -- NOT-BACKUP-CONTROLFILE (ora-19589)
839 -- A file that was specified by name is not a backup, standby, or
840 -- snapshot controlfile. An image copy of a controlfile can not be put
841 -- in a backup set.
842 -- BLOCKSIZE-MISMATCH (ora-19597)
843 -- Only files with the same blocksize can be put into the same backup
844 -- set. This is not really a restriction in 8.0 since there is only
845 -- one datafile block size per database.
846 -- RETRYABLE-ERROR (ora-19624)
847 -- This is a pseudo-error that is placed on top of the stack when an
848 -- error is signalled but it may be possible to continue the
849 -- conversation.
850 -- IO-ERROR
851 -- An error occured attempting to read the file header.
852
853 PROCEDURE backupArchivedLog( arch_recid IN number
854 ,arch_stamp IN number );
855
856 -- Add an archived log to the redo log backup set. It may be necessary to
857 -- call inspectArchivedLog to build a controlfile record.
858 --
859 -- Input parameters:
860 -- arch_recid
861 -- The controlfile record where the archiving record was created. This
862 -- is the RECID column from V$ARCHIVED_LOG or the record ID returned
863 -- from inspectArchivedLog.
864 -- arch_stamp
865 -- The stamp that corresponds to the arch_recid. This is to insure that
866 -- the correct record is identified.
867 -- Exceptions:
868 -- CONVERSATION-NOT-ACTIVE (ora-19580)
869 -- A backup conversation was not started before specifying files.
870 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
871 -- The database is in the process of being opened, closed, mounted,
872 -- or dismounted.
873 -- DATABASE-NOT-MOUNTED (ora-1507)
874 -- The database is not mounted.
875 -- WRONG-CONVERSATION-TYPE (ora-19592)
876 -- The backup set is not for archived logs.
877 -- NAMING-PHASE-OVER (ora-19604)
878 -- backuppiececreate has already been called. No files can be named
879 -- after piececreate is called.
880 -- RECORD-NOT-FOUND (ora-19571)
881 -- The specified archived log record does not exist.
882 -- RECORD-NOT-VALID (ora-19588)
883 -- The specified archived log record is no longer valid - it has been
884 -- marked as deleted.
885 -- DUPLICATE-BACKUP-ARCHIVELOG (ora-19595)
886 -- Only one version of an archived log can exist in the same backup set.
887 -- RESETLOGS-DATA-MISMATCH (ora-19617)
891 -- FILE-NOT-FOUND (ora-19625)
888 -- This archived log has different resetlogs data than the other logs
889 -- that have already been included. All archived logs in the same
890 -- backup set must have the same resetlogs data.
892 -- The file can not be opened.
893 -- FILE-VALIDATION-FAILURE (ora-19563)
894 -- The file is not the one described by the controlfile record.
895 -- BLOCKSIZE-MISMATCH (ora-19597)
896 -- Only files with the same blocksize can be put into the same backup
897 -- set. This is not really a restriction in 8.0 since there is only
898 -- one datafile block size per database.
899 -- RETRYABLE-ERROR (ora-19624)
900 -- This is a pseudo-error that is placed on top of the stack when an
901 -- error is signalled but it may be possible to continue the
902 -- conversation.
903 -- IO-ERROR
904 -- An error occured attempting to read the file header.
905
906 --************************
907 -- Backup Piece Creation
908 --************************
909 -- After all files and limits have been specified the next phase is to create
910 -- the pieces of a backup set.
911
912 PROCEDURE backupPieceCreate( fname IN varchar2
913 ,pieceno OUT binary_integer
914 ,done OUT boolean
915 ,handle OUT varchar2
916 ,comment OUT varchar2
917 ,media OUT varchar2
918 ,concur OUT boolean
919 ,params IN varchar2 default NULL);
920
921 -- This procedure should be called to create the first (and any subsequent)
922 -- backup piece after all calls to specify the file list have been issued.
923 -- Multiple backupPieceCreate calls may be necessary.
924 --
925 -- If any errors occur during the creation of a backup piece, the backup
926 -- conversation is still intact. Another backupPieceCreate call can be
927 -- made to retry.
928 --
929 -- The KBYTES and READRATE Limits may be changed between calls to
930 -- backupPieceCreate. The PARALLEL limit may not be changed between
931 -- pieces. The PARALLEL limit that is in effect at the start of the first
932 -- backup piece will remain in effect for the entire backup set.
933 --
934 -- Input parameters:
935 -- fname
936 -- Filename of the backup piece to be created. This will be translated
937 -- into a file handle after the piece is created.
938 -- params
939 -- This string is simply passed to the sequential file create OSD. It is
940 -- completely port and device specific.
941 -- Output parameters:
942 -- pieceno
943 -- The number of the successfully created piece. The first piece is
944 -- number 1.
945 -- done
946 -- TRUE if the backup set, not backup piece, is completed, FALSE
947 -- otherwise. If FALSE, backupPieceCreate must be called again to
948 -- continue the backup.
949 --
950 -- When TRUE, the backup conversation is now complete and all resources
951 -- associated with the conversation are freed. The controlfile has
952 -- been updated with all necessary records to describe the backup set.
953 -- The controlfile fixed views may now be queried, using the setid and
954 -- timestamp returned when the conversation was begun as the primary key,
955 -- to gather statistics from this backup set.
956 -- handle
957 -- The handle for the backup piece that was created. This is a permanent
958 -- name that can be used to read this sequential file for restore. It
959 -- can only be used with the same device type that was allocated at
960 -- this call.
961 -- comment
962 -- The comment for the backup piece. This is any string that the OSD
963 -- decided was useful. It will be the null string for operating system
964 -- files.
965 -- media
966 -- The media handle returned by the operating system. This is the name
967 -- of media where the file was created. It is not needed for retrieving
968 -- the backup piece. For some devices this information will not be
969 -- provided.
970 -- concur
971 -- TRUE if the device type used to create this piece
972 -- supports multiple processes concurrently accessing the same media.
973 -- If FALSE, it is best to only have one process at a time
974 -- doing a restore of backup pieces with the same media handle.
975 -- Exceptions:
976 -- NAME-TOO-LONG (ora-19704)
977 -- The specified backup piece name is longer than the port-specific
978 -- maximum file name length.
979 -- DEVICE-PARM-TOO-LONG (ora-19702)
980 -- The device parameter is longer than the port-specific maximum.
981 -- CONVERSATION-NOT-ACTIVE (ora-19580)
982 -- A backup conversation was not started before specifying files.
983 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
984 -- The database is in the process of being opened, closed, mounted,
985 -- or dismounted.
986 -- DATABASE-NOT-MOUNTED (ora-1507)
987 -- The database is not mounted.
988 -- DEVICE-NOT-ALLOCATED (ora-19569)
989 -- This session does not have a device allocated.
990 -- NO-FILES (ora-19581)
991 -- No files have been specified for the backup set so there is nothing
992 -- to backup.
993 -- FILE-VALIDATION-FAILURE (ora-19563)
994 -- One of the files does not match the description in the control file
995 -- or if specified by name the file header no longer matches the values
999 -- directory, and at least one data block were written to the backup
996 -- it had originally.
997 -- PIECE-TOO-SMALL (ora-19585)
998 -- An end-of-volume condition was received before the backup set header,
1000 -- piece.
1001 -- KBYTE_LIMIT-TOO-SMALL (ora-19586)
1002 -- The k-bytes per piece limit which was set with setLimit was reached
1003 -- before the backup set header, directory, and at least one data block
1004 -- were written to the backup piece.
1005 -- CORRUPT_LIMIT_EXCEEDED (ora-19566)
1006 -- Too many corrupt blocks were encountered in an input datafile.
1007 -- CORRUPT_BLOCK (ora-19599)
1008 -- A corrupt block was encountered in an input controlfile or archived
1009 -- log. Corrupt blocks are not tolerated in these types of files.
1010 -- EMPTY_FILE (ora-19562)
1011 -- A file was valid when it was specified during the file naming phase,
1012 -- but is now empty.
1013 -- FILE-TRUNCATED (ora-19575)
1014 -- The file did not contain the number of blocks that the file's header
1015 -- said it should.
1016 -- SINGLE-BLOCK-READ-ERROR (ora-19587)
1017 -- An I/O error occurred while reading the indicated block from the
1018 -- input file.
1019 -- RETRYABLE-ERROR (ora-19624)
1020 -- This is a pseudo-error that is placed on top of the stack when an
1021 -- error is signalled but it may be possible to continue the
1022 -- conversation.
1023 -- IO-ERROR
1024 -- An error occured attempting to read a file.
1025 -- CREATE-ERROR
1026 -- An error was reported by the OSD to create the sequential file.
1027 -- WRITE-ERROR
1028 -- An error was reported by the sequential write OSD.
1029 -- CORRUPT_BLOCK
1030 -- Too many corrupt blocks were encountered in one of the files being
1031 -- backed up. No corrupt blocks are allowed in redo logs or controlfiles.
1032 -- Some corrupt blocks can be allowed in datafiles via the
1033 -- argument to backupDataFile.
1034
1035
1036 --*****************************
1037 -- Backup Conversation Status--
1038 --****************************--
1039
1040 PROCEDURE backupStatus( state OUT binary_integer
1041 ,setid OUT number
1042 ,stamp OUT number
1043 ,pieceno OUT binary_integer
1044 ,files OUT binary_integer
1045 ,datafiles OUT boolean
1046 ,incremental OUT boolean
1047 ,nochecksum OUT boolean
1048 ,device OUT boolean );
1049
1050 BACKUP_NO_CONVERSATION constant binary_integer := 0;
1051 BACKUP_NAMING_FILES constant binary_integer := 1;
1052 BACKUP_PIECE_CREATE constant binary_integer := 2;
1053 BACKUP_PIECE_RETRY constant binary_integer := 3;
1054
1055 -- backupStatus returns information about the current backup conversation.
1056 -- It is useful for resyncing with a conversation after some error has
1057 -- interrupted normal execution, and it is now time to resume the
1058 -- conversation. It can also be called if there is no conversation.
1059 --
1060 -- Note that there are no exceptions since this does nothing but return
1061 -- information about this session.
1062 --
1063 -- Output parameters:
1064 -- state
1065 -- This defines the state of the backup conversation. It is one of the
1066 -- constants defined above. The constants have the following meanings.
1067 -- BACKUP_NO_CONVERSATION
1068 -- No backup conversation is currently active for this session. The
1069 -- other output values will be NULL when this state is returned. Note
1070 -- that this state does not signal an error.
1071 -- BACKUP_NAMING_FILES
1072 -- Still allowing more calls to add files to the backup. This is the
1073 -- state immediately after starting the conversation. This state
1074 -- continues until the first call to backupPieceCreate.
1075 -- BACKUP_PIECE_CREATE
1076 -- The last call to backupPieceCreate completed successfully. More
1077 -- pieces still need to be created to complete the backup set.
1078 -- BACKUP_PIECE_RETRY
1079 -- The session got an error while writing a backup piece.
1080 -- The error may have been from reading one of the input files
1081 -- or some other failure. The return value pieceno does not include
1082 -- the piece that was being written. The next call to
1083 -- backupPieceCreate will recreate the failed piece from its
1084 -- beginning.
1085 --
1086 -- setid and stamp are the key that will be used to identify the
1087 -- controlfile records that will be created when the backup set is
1088 -- complete. See the description of these parameters under the
1089 -- backupSetDataFile procedure for more information.
1090 -- pieceno
1091 -- This is the number of backup pieces that have been successfully
1092 -- created. It is zero until the first backupPieceCreate returns
1093 -- successfully.
1094 -- files
1095 -- This is the number of files that have been named for inclusion
1096 -- in the backup set. It is zero immediately after the conversation
1097 -- begins.
1098 -- datafiles
1099 -- TRUE if the backup conversation was started by calling
1100 -- backupSetDataFile; FALSE if backupSetArchivedLog was called.
1101 -- incremental
1102 -- This is the incremental argument to backupSetDataFile.
1103 -- nochecksum
1107 -- TRUE if a device has been allocated to this session.
1104 -- This is the nochecksum argument to backupSetDataFile or
1105 -- backupSetArchivedLog.
1106 -- device
1108
1109 --**********************************
1110 -- Backup Conversation Termination--
1111 --*********************************--
1112
1113 PROCEDURE backupCancel;
1114
1115 -- Cancels a backup conversation releasing the context. This needs to be
1116 -- done if a conversation is going to be abandoned without successfully
1117 -- completing the backup set. This can be done anytime within the
1118 -- conversation. No data will be added to the controlfile to reflect this
1119 -- conversation. The row in V$SESSION_LONGOPS will be deleted.
1120
1121 --***************
1122 -- File Copying--
1123 --**************--
1124 -- It is also possible to make image copies of some files. This is useful
1125 -- for staging backups on disk before copying them to sequential media.
1126 -- The READRATE limit applies to these procedures, but the other limits
1127 -- do not. The database must be mounted to execute these procedures.
1128 --
1129 -- Each of these operations create a row in V$SESSION_LONGOPS to track the
1130 -- progress of the copy in blocks.
1131
1132 PROCEDURE backupBackupPiece( bpname IN varchar2
1133 ,fname IN varchar2
1134 ,handle OUT varchar2
1135 ,comment OUT varchar2
1136 ,media OUT varchar2
1137 ,concur OUT boolean
1138 ,recid OUT number
1139 ,stamp OUT number
1140 ,tag IN varchar2 default NULL
1141 ,params IN varchar2 default NULL
1142 ,media_pool IN binary_integer default 0
1143 ,reuse IN boolean default FALSE);
1144
1145 -- This procedure copies a backup piece that was originally written to an
1146 -- operating system file, onto sequential media. This requires allocating
1147 -- a sequential device first. Of course, this could copy to another operating
1148 -- system file if the NULL device is allocated.
1149 --
1150 -- A record is made in the controlfile as if the piece was just created and
1151 -- written to this output file. It can be queried from V$BACKUP_PIECE using
1152 -- the record ID returned. Note that no new entries are made in V$BACKUP_SET,
1153 -- V$BACKUP_DATAFILE, V$BACKUP_REDOLOG, or V$BACKUP_CORRUPTION.
1154 --
1155 -- It is acceptable to copy a backup piece when a backup controlfile has been
1156 -- mounted. However, note that the files named in the control
1157 -- file may no longer exist.
1158 --
1159 -- Input parameters:
1160 -- bpname
1161 -- Operating system file name of the existing backup piece. This will be
1162 -- read and copied to sequential media.
1163 -- fname
1164 -- Filename of the backup piece to be created. This will be translated
1165 -- into a file handle after the piece is created.
1166 -- tag
1167 -- The tag stored in the file header of the copied and backed up files,
1168 -- and also in the controlfile records describing those files.
1169 -- params
1170 -- This string is simply passed to the sequential file create OSD. It is
1171 -- completely port and device specific.
1172 -- Output parameters:
1173 -- handle
1174 -- The handle for the backup piece that was created. This is a permanent
1175 -- name that can be used to read this sequential file for restore. It
1176 -- can only be used with the same device type that was allocated at
1177 -- this call.
1178 -- comment
1179 -- The comment for the backup piece. This is any string that the OSD
1180 -- decided was useful. It will be a null string for operating system
1181 -- files. Note that this comment is not the same as the comment where the
1182 -- original backup piece was created.
1183 -- media
1184 -- The media handle returned by the operating system. This is the name
1185 -- of media where the file was created. It is not needed for retrieving
1186 -- the backup piece. For some devices this information will not be
1187 -- provided.
1188 -- concur
1189 -- TRUE if the device type used to create this piece
1190 -- supports multiple processes concurrently accessing the same media.
1191 -- If FALSE, it is best to only have one process at a time
1192 -- doing a restore of backup pieces with the same media handle.
1193 -- recid
1194 -- This is the ID of the record in the controlfile where the
1195 -- information about this backup piece was recorded. It can be used as
1196 -- the primary key to query V$BACKUP_PIECE.
1197 -- stamp
1198 -- This is a number that can be used to verify that the row in
1199 -- V$BACKUP_PIECE is really for this backup piece. The stamp combined
1200 -- with recid makes a key that is unique for this backup piece for all
1201 -- time.
1202 -- media_pool
1203 -- a number from 0-255 whose meaning is defined by rman or by 3rd-party
1204 -- media management software.
1205 -- Exceptions:
1206 -- NO-INPUT-FILENAME (ora-19605)
1207 -- src_name must be assigned a non-NULL string in copyControlFile.
1208 -- NO-OUTPUT-FILENAME (ora-19574)
1209 -- dest_name must be assigned a non-NULL string in copyControlFile.
1210 -- NAME-TOO-LONG (ora-19704)
1211 -- The specified file name is longer than the port-specific
1215 -- DEVICE-PARM-TOO-LONG (ora-19702)
1212 -- maximum file name length.
1213 -- TAG-TOO-LONG (ora-19705)
1214 -- The tag is longer than the port-specific maximum.
1216 -- The device parameter is longer than the port-specific maximum.
1217 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1218 -- The database is in the process of being opened, closed, mounted,
1219 -- or dismounted.
1220 -- DATABASE-NOT-MOUNTED (ora-1507)
1221 -- The database is not mounted.
1222 -- FILE-IN-USE (ora-19584)
1223 -- The specified output file is already in use by the database as a
1224 -- datafile or online redo log.
1225 -- DEVICE-NOT-ALLOCATED (ora-19569)
1226 -- This session does not have a device allocated.
1227 -- CANT-IDENTIFY-FILE (ora-19505)
1228 -- The file can not be opened.
1229 -- END-OF-VOLUME (ora-19630)
1230 -- end-of-volume was encountered while copying the backup piece.
1231 -- CORRUPT_BLOCK (ora-19599)
1232 -- A corrupt block was encountered. Corrupt blocks are not tolerated
1233 -- in backup pieces.
1234 -- NOT-A-BACKUP-PIECE (ora-19608)
1235 -- The input file is not recognizable as a backup piece.
1236 -- CORRUPT-DIRECTORY (ora-19610)
1237 -- The backup piece directory is corrupt.
1238 -- IO-ERROR
1239 -- An error occured attempting to read the input file.
1240 -- CREATE-ERROR
1241 -- An error was reported by the OSD to create the sequential file.
1242 -- WRITE-ERROR
1243 -- An error was reported by the sequential write OSD.
1244
1245 PROCEDURE copyDataFile( dfnumber IN binary_integer
1246 ,fname IN varchar2
1247 ,full_name OUT varchar2
1248 ,recid OUT number
1249 ,stamp OUT number
1250 ,max_corrupt IN binary_integer default 0
1251 ,tag IN varchar2 default NULL
1252 ,nochecksum IN boolean default FALSE
1253 ,isbackup IN boolean default FALSE );
1254 --
1255 -- copyDataFile copies the named file in the database. The datafile may be
1256 -- either online or offline.
1257
1258 PROCEDURE copyDataFileCopy( copy_recid IN number
1259 ,copy_stamp IN number
1260 ,full_name OUT varchar2
1261 ,recid OUT number
1262 ,stamp OUT number
1263 ,fname IN varchar2 default NULL
1264 ,max_corrupt IN binary_integer default 0
1265 ,tag IN varchar2 default NULL
1266 ,nochecksum IN boolean default FALSE
1267 ,isbackup IN boolean default FALSE);
1268 --
1269 -- copyDataFileCopy is used to make a copy of a copy.
1270
1271 -- These procedures make image copies of datafiles. An image copy is
1272 -- suitable for direct use by the database. Its name can be used in
1273 -- a rename command, then recovered to become current. It can also
1274 -- be copied to sequential media as part of a backup set. Some customers
1275 -- may want to keep an online image copy of all their datafiles as their
1276 -- most recent backup, then backup the image copy to tape. Note that
1277 -- these routines only make image copies on operating system files.
1278 -- It is impossible to put an image on sequential media. These procedures
1279 -- may NOT be executed during a backup or restore conversation. There must
1280 -- be a device allocated to the session and it must be the null device.
1281 --
1282 -- The procedure copyDataFile copies the current file in the database.
1283 -- The file may be either online or offline. The procedure copyDataFileCopy
1284 -- is used to make a copy of a copy. This may be advisable before using a
1285 -- copy for an incomplete recovery. If the incomplete recovery needs to
1286 -- be redone, the unrecovered file is still available on disk. For copying
1287 -- to the file specified by the controlfile, the fname parameter can be
1288 -- NULL. This is effectively a restore. It is not permitted to overwrite
1289 -- the file named by the controlfile with a copy unless the creation time
1290 -- of the copy is the same as the creation time of the real file.
1291 --
1292 -- It is acceptable to copy a file when a backup controlfile has been
1293 -- mounted. However, note the files named in the control file may no
1294 -- longer exist.
1295 --
1296 -- In order to handle a failure during the copy, the output file header
1297 -- will have its file type set to zero until the copy is complete. This
1298 -- insures it cannot be used until the copy is complete. When the copy is
1299 -- complete, a valid header, with all fuzziness removed except the
1300 -- calculated absolute fuzziness, is written to the file.
1301 --
1302 -- After the copy is complete, a record will be added to V$DATAFILE_COPY
1303 -- to describe the copied file. If the destination was the named
1304 -- datafile (copyDataFileCopy was used and no filename was specified),
1305 -- then the underlying controlfile record will be immediately marked as
1306 -- obsolete, and will not appear in the V$DATAFILE_COPY view. Before
1307 -- adding the new record to V$DATAFILE_COPY, the datafile copy record
1308 -- section of the controlfile will be scanned, looking for any existing
1309 -- copy records with the same filename. If any such records are found,
1310 -- they will be marked obsolete.
1311 --
1312 -- If any corrupt blocks are found in the datafiles, then records will be
1316 -- dfnumber
1313 -- inserted in V$COPY_CORRUPTION to describe the corrupt block ranges.
1314 --
1315 -- Input parameters:
1317 -- Datafile number of a file to copy. This refers to the file that
1318 -- is currently accessible via SQL commands.
1319 -- copy_recid
1320 -- The record ID from V$DATAFILE_COPY for the datafile copy. This
1321 -- is the record ID returned from inspectDataFileCopy or a previous call
1322 -- to make a datafile copy.
1323 -- copy_stamp
1324 -- The stamp that corresponds to copy_recid. This is to insure that the
1325 -- record is the same one that was selected.
1326 -- max_corrupt
1327 -- Up to this many corrupt data blocks from this file can appear in the
1328 -- backup. The copy will fail if more blocks are found corrupt.
1329 -- fname
1330 -- File name to copy the image to. This name may not be useable by
1331 -- another process, so it will be expanded.
1332 -- tag
1333 -- The tag to be stored in the file header of the copied and backed up
1334 -- files, and also in the controlfile records describing those files.
1335 -- nochecksum
1336 -- If true, we will not calculate a checksum on blocks that
1337 -- do not have a checksum. If there is a checksum in a block it is
1338 -- always validated after reading, and it is saved in the copy.
1339 -- isbackup
1340 -- If true, then Recovery Manager is treating this file as a level 0
1341 -- backup in the database's recovery strategy. This information is
1342 -- simply stored in the V$DATAFILE_COPY record created by this copy
1343 -- operation, and has no other effect.
1344 --
1345 -- Output parameters:
1346 -- full_name
1347 -- This is the fully expanded name of the file that was created. It will
1348 -- also appear in V$DATAFILE_COPY.
1349 -- recid
1350 -- This is the ID of the record that is created in the controlfile
1351 -- when the copy is successfully completed. It can be used to query
1352 -- information about the copy from V$DATAFILE_COPY.
1353 -- stamp
1354 -- This is a number that can be used to verify that the row in
1355 -- V$DATAFILE_COPY is really for this copy. The stamp combined with
1356 -- recid makes a key that is unique for this copy for all time.
1357 -- Exceptions:
1358 -- NAME-TOO-LONG (ora-19704)
1359 -- The specified file name is longer than the port-specific
1360 -- maximum file name length.
1361 -- TAG-TOO-LONG (ora-19705)
1362 -- The tag is longer than the port-specific maximum.
1363 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1364 -- The database is in the process of being opened, closed, mounted,
1365 -- or dismounted.
1366 -- DATABASE-NOT-MOUNTED (ora-1507)
1367 -- The database is not mounted.
1368 -- NO-OUTPUT-FILENAME (ora-19574)
1369 -- fname must be assigned a non-NULL string in copyDataFile.
1370 -- INVALID-FILE-NUMBER (ora-19570)
1371 -- The specified real file number is out of range.
1372 -- FILE-BEING-RESIZED (ora-19572)
1373 -- The file is in the middle of a resize operation. Wait for the
1374 -- resize to complete.
1375 -- CANT-GET-REAL-FILE-ENQUEUE (ora-19573)
1376 -- A datafile is locked. Another backup or restore could be in progress,
1377 -- or some other database activity, such as media recovery, holds an
1378 -- exclusive enqueue on the file.
1379 -- FILE-IN-USE (ora-19584)
1380 -- The specified output file is already in use by the database as a
1381 -- datafile or online redo log.
1382 -- DATABASE-NOT-OPEN (ora-1138)
1383 -- Some other instance is open, but this instance is not open. Either
1384 -- open this instance or close all other instances.
1385 -- FILE-IS-FUZZY (ora-19602)
1386 -- The file is fuzzy and the database is in noarchivelog mode.
1387 -- FILE-VALIDATION-FAILURE (ora-19563)
1388 -- The file is not the one described by the controlfile record.
1389 -- RECORD-NOT-FOUND (ora-19571)
1390 -- The specified datafile copy record does not exist.
1391 -- RECORD-NOT-VALID (ora-19588)
1392 -- The specified datafile copy record is no longer valid - it has been
1393 -- marked as deleted.
1394 -- REAL-FILE-NOT-FOUND (ora-19576)
1395 -- When restoring a datafile copy to its original location, the
1396 -- datafile record describing the original file could no longer be
1397 -- found, probably because the file was dropped from the database.
1398 -- DEVICE-NOT-ALLOCATED (ora-19569)
1399 -- This session does not have a device allocated.
1400 -- NULL-DEVICE-REQUIRED (ora-19561)
1401 -- A NULL device is required, but a non-null device was found.
1402 -- CANT-IDENTIFY-FILE (ora-19505)
1403 -- The file can not be opened.
1404 -- CORRUPT_LIMIT_EXCEEDED (ora-19566)
1405 -- Too many corrupt blocks were encountered in the input file.
1406 -- EMPTY_FILE (ora-19562)
1407 -- The input file is empty.
1408 -- FILE-TRUNCATED (ora-19575)
1409 -- The file did not contain the number of blocks that the file's header
1410 -- said it should.
1411 -- RETRYABLE-ERROR (ora-19624)
1412 -- This is a pseudo-error that is placed on top of the stack when an
1413 -- error is signalled but it may be possible to continue the
1414 -- conversation.
1415 -- IO-ERROR
1416 -- An error occured attempting to read a file.
1417 -- CREATE-ERROR
1418 -- An error was reported by the OSD to create the file.
1419 -- WRITE-ERROR
1420 -- An error was reported by the sequential write OSD.
1421
1425 ,full_name OUT varchar2
1422 PROCEDURE copyArchivedLog( arch_recid IN number
1423 ,arch_stamp IN number
1424 ,fname IN varchar2
1426 ,recid OUT number
1427 ,stamp OUT number
1428 ,nochecksum IN boolean default FALSE );
1429
1430 -- This procedure makes a copy of a log that was already archived. This
1431 -- may be useful for moving redo to a different location, or for extra
1432 -- redundancy. A record is created in the controlfile as if this log was
1433 -- just archived. Note that this cannot copy an online log. Copying an
1434 -- online log is actually archiving it, and has other implications. There
1435 -- are SQL commands for archiving.
1436 --
1437 -- It is acceptable to copy a file when a backup controlfile has been
1438 -- mounted. However, note the files named in the controlfile may no
1439 -- longer exist.
1440 --
1441 -- Input parameters:
1442 -- arch_recid
1443 -- The controlfile record where the archiving record was created. This
1444 -- is the RECID column from V$ARCHIVED_LOG or the record ID returned
1445 -- from inspectArchivedLog.
1446 -- arch_stamp
1447 -- The stamp that corresponds to the arch_recid. This is to insure that
1448 -- the correct record is identified.
1449 -- fname
1450 -- File name to copy the image to. This name may not be useable by
1451 -- another process, so it will be expanded.
1452 -- nochecksum
1453 -- If true, we will not calculate a checksum on blocks that
1454 -- do not have a checksum. If there is a checksum in a block it is
1455 -- always validated after reading, and it is saved in the backup.
1456 -- Output parameters:
1457 -- full_name
1458 -- This is the fully expanded name of the file that was created. It will
1459 -- also appear in V$ARCHIVED_LOG.
1460 -- recid
1461 -- This is the ID of the record that is created in the controlfile
1462 -- when the copy is successfully completed. It can be used to query
1463 -- information about the copy from V$ARCHIVED_LOG.
1464 -- stamp
1465 -- This is a number that can be used to verify that the row in
1466 -- V$ARCHIVED_LOG is really for this copy. The stamp combined with recid
1467 -- makes a key that is unique for this copy for all time.
1468 -- Exceptions:
1469 -- NAME-TOO-LONG (ora-19704)
1470 -- The specified file name is longer than the port-specific
1471 -- maximum file name length.
1472 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1473 -- The database is in the process of being opened, closed, mounted,
1474 -- or dismounted.
1475 -- DATABASE-NOT-MOUNTED (ora-1507)
1476 -- The database is not mounted.
1477 -- NO-OUTPUT-FILENAME (ora-19574)
1478 -- fname must be assigned a non-NULL string in copyArchivedLog
1479 -- FILE-IN-USE (ora-19584)
1480 -- The specified output file is already in use by the database as a
1481 -- datafile or online redo log.
1482 -- FILE-VALIDATION-FAILURE (ora-19563)
1483 -- The file is not the one described by the controlfile record.
1484 -- RECORD-NOT-FOUND (ora-19571)
1485 -- The specified datafile copy record does not exist.
1486 -- RECORD-NOT-VALID (ora-19588)
1487 -- The specified datafile copy record is no longer valid - it has been
1488 -- marked as deleted.
1489 -- DEVICE-NOT-ALLOCATED (ora-19569)
1490 -- This session does not have a device allocated.
1491 -- NULL-DEVICE-REQUIRED (ora-19561)
1492 -- A NULL device is required, but a non-null device was found.
1493 -- CANT-IDENTIFY-FILE (ora-19505)
1494 -- The file can not be opened.
1495 -- CORRUPT_BLOCK (ora-19599)
1496 -- A corrupt block was encountered in an input controlfile or archived
1497 -- log. Corrupt blocks are not tolerated in these types of files.
1498 -- EMPTY_FILE (ora-19562)
1499 -- The input file is empty.
1500 -- FILE-TRUNCATED (ora-19575)
1501 -- The file did not contain the number of blocks that the file's header
1502 -- said it should.
1503 -- RETRYABLE-ERROR (ora-19624)
1504 -- This is a pseudo-error that is placed on top of the stack when an
1505 -- error is signalled but it may be possible to continue the
1506 -- conversation.
1507 -- IO-ERROR
1508 -- An error occured attempting to read a file.
1509 -- CREATE-ERROR
1510 -- An error was reported by the OSD to create the file.
1511 -- WRITE-ERROR
1512 -- An error was reported by the sequential write OSD.
1513
1514 PROCEDURE copyControlFile( src_name IN varchar2
1515 ,dest_name IN varchar2
1516 ,recid OUT number
1517 ,stamp OUT number
1518 ,full_name OUT varchar2);
1519
1520 -- This routine makes copies of a controlfile that is already on disk in an
1521 -- operating system file. It is intended to be used to make copies of
1522 -- controlfiles for specifying multiple controlfiles in the initialization
1523 -- parameter.
1524 --
1525 -- If src_name is NULL, this function will make backup copy of a current
1526 -- controlfile. Backup controlfiles need modifications so that they can be
1527 -- recovered, so this command calls KCC layer to do that. You can also use
1528 -- ALTER DATABASE BACKUP CONTROLFILE.
1529 --
1530 -- If dest_name is NULL and database is not mounted, we restore and replicate
1534 -- Unlike the other copy procedures, copyControlFile works when the
1531 -- the controlfiles to all names that match current controlfiles in
1532 -- parameter file.
1533 --
1535 -- database is not mounted. Exception is when we make backup copy of a
1536 -- current controlfile.
1537 --
1538 -- When the database is mounted:
1539 --
1540 -- Neither the source nor destination file may be an active file as
1541 -- specified in the initialization parameter.
1542 --
1543 -- The destination file may not be the snapshot controlfile.
1544 --
1545 -- After the copy is complete, a record will be placed into the
1546 -- V$DATAFILE_COPY view (in the current controlfile, not the copy)
1547 -- describing the copy. The datafile number will be zero and the
1548 -- the datafile checkpoint will be the set to the controlfile checkpoint
1549 -- taken from the kccfhx.
1550 --
1551 -- When the database is NOT mounted:
1552 --
1553 -- The source file must be specified.
1554 --
1555 -- There are no restrictions on either the input or output file, except
1556 -- that the input file must be a controlfile for the started instance.
1557 --
1558 -- No record is made to describe the copy.
1559 --
1560 -- Input parameters:
1561 -- src_name
1562 -- Operating system file name of the controlfile to copy from.
1563 -- If NULL, then we will make backup copy of the current controlfile.
1564 -- dest_name
1565 -- File name to copy the image to. This name may not be useable by
1566 -- another process, so it will be expanded.
1567 -- Output parameters:
1568 -- recid
1569 -- This is the ID of the record that is created in the controlfile
1570 -- when the copy is successfully completed. It can be used to query
1571 -- information about the copy from V$DATAFILE_COPY. The controlfile is
1572 -- seen as datafile 0.
1573 -- stamp
1574 -- This is a number that can be used to verify that the row in
1575 -- V$DATAFILE_COPY is really for this copy. The stamp combined with
1576 -- recid makes a key that is unique for this copy for all time.
1577 -- full_name
1578 -- This is the fully expanded name of the file that was created.
1579 -- Exceptions:
1580 -- NAME-TOO-LONG (ora-19704)
1581 -- The specified file name is longer than the port-specific
1582 -- maximum file name length.
1583 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1584 -- The database is in the process of being opened, closed, mounted,
1585 -- or dismounted.
1586 -- DATABASE-NOT-MOUNTED (ora-1507)
1587 -- The database is not mounted.
1588 -- NO-OUTPUT-FILENAME (ora-19574)
1589 -- dest_name must be assigned a non-NULL string in copyControlFile.
1590 -- FILE-IN-USE (ora-19584)
1591 -- The specified output file is already in use by the database as a
1592 -- datafile or online redo log.
1593 -- FILE-NOT-FOUND (ora-19625)
1594 -- The file can not be opened.
1595 -- FILE-VALIDATION-FAILURE (ora-19563)
1596 -- The file is not a controlfile for the current database.
1597 -- NOT-BACKUP-CONTROLFILE (ora-19589)
1598 -- The input file is not a backup, standby, or snapshot controlfile.
1599 -- An image copy of a controlfile can not be copied.
1600 -- CONTROLFILE-IS-ACTIVE (ora-19607)
1601 -- The controlfile name is the same as one of the controlfiles specified
1602 -- in the init.ora file.
1603 -- CONTROLFILE-IS-SNAPSHOT (ora-19606)
1604 -- The destination file is the snapshot controlfile. You cannot use
1605 -- copyControlFile to create the snapshot controlfile.
1606 -- DEVICE-NOT-ALLOCATED (ora-19569)
1607 -- This session does not have a device allocated.
1608 -- NULL-DEVICE-REQUIRED (ora-19561)
1609 -- A NULL device is required, but a non-null device was found.
1610 -- CORRUPT_BLOCK (ora-19599)
1611 -- A corrupt block was encountered in an input controlfile or archived
1612 -- log. Corrupt blocks are not tolerated in these types of files.
1613 -- EMPTY_FILE (ora-19562)
1614 -- The input file is empty.
1615 -- FILE-TRUNCATED (ora-19575)
1616 -- The file did not contain the number of blocks that the file's header
1617 -- said it should.
1618 -- RETRYABLE-ERROR (ora-19624)
1619 -- This is a pseudo-error that is placed on top of the stack when an
1620 -- error is signalled but it may be possible to continue the
1621 -- conversation.
1622 -- IO-ERROR
1623 -- An error occured attempting to read a file.
1624 -- CREATE-ERROR
1625 -- An error was reported by the OSD to create the file.
1626 -- WRITE-ERROR
1627 -- An error was reported by the sequential write OSD.
1628
1629 PROCEDURE inspectDataFileCopy( fname IN varchar2
1630 ,full_name OUT varchar2
1631 ,recid OUT number
1632 ,stamp OUT number
1633 ,tag IN varchar2 default NULL
1634 ,isbackup IN boolean default FALSE);
1635
1636 -- This procedure reads the header from an operating system datafile copy,
1637 -- and makes a record in the controlfile as if the copy had just been made
1638 -- via copyDataFile. This is useful for registering a datafile copy that
1639 -- was made through the Oracle7 technique using an operating system copy
1640 -- utility. Some customers prefer to make backups by breaking a mirrored
1641 -- volume then reforming the mirror with a different drive. The broken off
1645 --
1642 -- drive can then be registered for use by inspecting it. A datafile copy
1643 -- must be registered in the controlfile before it can be put in a backup
1644 -- on sequential media.
1646 -- This may be called during a backup or restore conversation in order to
1647 -- have a record for the file. This is particularly advised when using a
1648 -- backup controlfile since the datafile information may be out of date.
1649 --
1650 -- Input parameters:
1651 -- fname
1652 -- File name of the datafile copy to inspect. This name may not be
1653 -- useable by another process, so it will be expanded.
1654 -- Output parameters:
1655 -- full_name
1656 -- This is the fully expanded name of the file that was inspected. It
1657 -- will also appear in V$DATAFILE_COPY.
1658 -- recid
1659 -- This is the ID of the record that is created in the controlfile
1660 -- when the copy is successfully inspected. It can be used to query
1661 -- information about the copy from V$DATAFILE_COPY.
1662 -- stamp
1663 -- This is a number that can be used to verify that the row in
1664 -- V$DATAFILE_COPY is really for this copy. The stamp combined with recid
1665 -- makes a key that is unique for this copy for all time.
1666 -- tag
1667 -- The tag to be stored in in the controlfile record describing this file
1668 -- InspectDataFileCopy does not store the tag in the file header
1669 -- isbackup
1670 -- If true, then Recovery Manager is treating this file as a level 0
1671 -- backup in the database's recovery strategy. This information is
1672 -- simply stored in the V$DATAFILE_COPY record created by this inspect
1673 -- operation, and has no other effect.
1674 -- Exceptions:
1675 -- NAME-TOO-LONG (ora-19704)
1676 -- The specified file name is longer than the port-specific
1677 -- maximum file name length.
1678 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1679 -- The database is in the process of being opened, closed, mounted,
1680 -- or dismounted.
1681 -- DATABASE-NOT-MOUNTED (ora-1507)
1682 -- The database is not mounted.
1683 -- FILE-IN-USE (ora-19584)
1684 -- The specified output file is already in use by the database as a
1685 -- datafile or online redo log.
1686 -- FILE-NOT-FOUND (ora-19625)
1687 -- The file can not be opened.
1688 -- FILE-VALIDATION-FAILURE (ora-19563)
1689 -- The file is not a datafile from the current database.
1690 -- IO-ERROR
1691 -- An error occured attempting to read a file.
1692
1693 PROCEDURE inspectArchivedLog( fname IN varchar2
1694 ,full_name OUT varchar2
1695 ,recid OUT number
1696 ,stamp OUT number );
1697
1698 -- This procedure reads the header from an archived redo log and constructs
1699 -- a record in the controlfile as if the file had just been archived or
1700 -- created via copyArchivedLog. This may be necessary in order to put the log
1701 -- in a backup on sequential media.
1702 --
1703 -- This may be called during a backup or restore conversation in order to
1704 -- have a record for the file. This is particularly advised when using a
1705 -- backup controlfile since the datafile information may be out of date.
1706 --
1707 -- Input parameters:
1708 -- fname
1709 -- File name of the archived log to inspect. This name may not be
1710 -- useable by another process, so it will be expanded.
1711 -- Output parameters:
1712 -- full_name
1713 -- This is the fully expanded name of the file that was inspected. It
1714 -- will also appear in V$ARCHIVED_LOG.
1715 -- recid
1716 -- This is the ID of the record that is created in the controlfile
1717 -- when the copy is successfully inspected. It can be used to query
1718 -- information about the copy from V$ARCHIVED_LOG.
1719 -- stamp
1720 -- This is a number that can be used to verify that the row in
1721 -- V$ARCHIVED_LOG is really for this copy. The stamp combined with recid
1722 -- makes a key that is unique for this copy for all time.
1723 -- Exceptions:
1724 -- NAME-TOO-LONG (ora-19704)
1725 -- The specified file name is longer than the port-specific
1726 -- maximum file name length.
1727 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1728 -- The database is in the process of being opened, closed, mounted,
1729 -- or dismounted.
1730 -- DATABASE-NOT-MOUNTED (ora-1507)
1731 -- The database is not mounted.
1732 -- FILE-IN-USE (ora-19584)
1733 -- The specified output file is already in use by the database as a
1734 -- datafile or online redo log.
1735 -- FILE-NOT-FOUND (ora-19625)
1736 -- The file can not be opened.
1737 -- FILE-VALIDATION-FAILURE (ora-19563)
1738 -- The file is not a datafile from the current database.
1739 -- IO-ERROR
1740 -- An error occured attempting to read a file.
1741
1742 PROCEDURE inspectControlFile(fname IN varchar2
1743 ,full_name OUT varchar2
1744 ,recid OUT number
1745 ,stamp OUT number );
1746
1747 -- This procedure reads the header from a backup controlfile and creates
1748 -- a record in the current controlfile as if the file had just been
1749 -- created with 'alter database backup controlfile' or copyControlFile or
1750 -- restoreControlFileTo. This may be necessary in order to put the log
1751 -- in a backup on sequential media.
1752 --
1756 -- Input parameters:
1753 -- This may be called during a backup or restore conversation in order to
1754 -- have a record for the file.
1755 --
1757 -- fname
1758 -- File name of the controlfile to inspect. This name may not be
1759 -- useable by another process, so it will be expanded.
1760 -- Output parameters:
1761 -- full_name
1762 -- This is the fully expanded name of the file that was inspected. It
1763 -- will also appear in V$DATAFILE_COPY.
1764 -- recid
1765 -- stamp
1766 -- These are the key of the record that is created in the controlfile
1767 -- when the copy is successfully inspected. It can be used to query
1768 -- information about the copy from V$DATAFILE_COPY.
1769 -- Exceptions:
1770 -- NAME-TOO-LONG (ora-19704)
1771 -- The specified file name is longer than the port-specific
1772 -- maximum file name length.
1773 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1774 -- The database is in the process of being opened, closed, mounted,
1775 -- or dismounted.
1776 -- DATABASE-NOT-MOUNTED (ora-1507)
1777 -- The database is not mounted.
1778 -- FILE-IN-USE (ora-19584)
1779 -- The specified output file is already in use by the database as a
1780 -- datafile or online redo log.
1781 -- FILE-NOT-FOUND (ora-19625)
1782 -- The file can not be opened.
1783 -- FILE-VALIDATION-FAILURE (ora-19563)
1784 -- The file is not a controlfile that was backed up from the current
1785 -- database.
1786 -- IO-ERROR
1787 -- An error occured attempting to read a file.
1788
1789 --*********************************************
1790 -- Restore Conversation Initiation Procedures--
1791 --********************************************--
1792
1793 -- A restore conversation is similar to a backup conversation except that
1794 -- it reads backups and creates operating system files. Either archived logs
1795 -- can be restored for use with recovery, or data files can be restored to
1796 -- be recovered. Restoring an incremental backup is equivalent to applying
1797 -- redo to an existing copy of the datafile. A successful restore
1798 -- conversation consists of the following phases:
1799 -- 1) Start conversation specifying the type of backup.
1800 -- 2) Specify which files to restore and where to restore them.
1801 -- 3) Read consecutive pieces of the backup set until all the specified
1802 -- files have been restored.
1803 -- The restore conversation ends when the last file has been successfully
1804 -- restored.
1805
1806 PROCEDURE restoreSetDataFile;
1807 -- restoreSetDataFile begins a conversation that will completely recreate
1808 -- datafiles and possibley a controlfile from the backup.
1809
1810 PROCEDURE applySetDataFile;
1811 -- applySetDataFile begins a conversation that will apply incremental
1812 -- backups to existing datafiles.
1813
1814 -- Recovery Server flags (bit pattern)
1815 -- For use with restoreSetDataFile and applySetDataFile
1816 -- Must match krbr.h
1817 KRBRCB_ORS_POOL constant binary_integer := 1; -- compressed blocks
1818 KRBRCB_ORS_INSP constant binary_integer := 2; -- ORS catalog bp
1819 KRBRCB_ORS_CONTEXT constant binary_integer := 4; -- ORS, no pool
1820 KRBRCB_ORS_NOKRBPH constant binary_integer := 8; -- skips krbph
1821 KRBRCB_ORS_UPDKRBPH constant binary_integer := 16; -- updates krbph
1822
1823 PROCEDURE restoreSetArchivedLog(destination IN varchar2 default NULL);
1824 -- restoreSetArchivedLog begins a conversation that will restore archived
1825 -- redo logs so that they can be applied by recovery.
1826 --
1827 -- These procedures begin a restore conversation. An appropriate context for
1828 -- the restore is allocated. The database does not need to be mounted to do a
1829 -- restore, but an instance must be started. A device must already be
1830 -- allocated for reading the backup pieces.
1831 --
1832 -- An instance must be started to call these procedures. If the controlfile
1833 -- is available, the database should be mounted. This provides better error
1834 -- checking, and allows specification of datafiles by file number
1835 --
1836 -- For a redo log conversation, a destination can be given for the
1837 -- location to create the logs. This is the same as giving a destination
1838 -- for archiving. The log_archive_format initialization parameter is used
1839 -- along with the destination to construct the name of the operating
1840 -- system files to create. If no destination is given, the current
1841 -- archiving destination is used.
1842 --
1843 -- Input parameters:
1844 -- destination
1845 -- This is used to construct the file name for creating the restored
1846 -- redo logs.
1847 -- Exceptions:
1848 -- DESTINATION-TOO-LONG (ora-19708)
1849 -- The specified archive log destination is longer than the port-
1850 -- specific maximum.
1851 -- CONVERSATION-ACTIVE (ora-19590)
1852 -- A backup or restore conversation is already active in this session.
1853 -- MULTI-THREADED-SERVER (ora-19550)
1854 -- This session is not connected to a dedicated server.
1855 -- ALTERNATE-CONTROLFILE-OPEN (ora-226)
1856 -- This session's fixed tables are currently re-directed to a snapshot
1857 -- or other alternate controlfile.
1858 -- DATABASE-NOT-MOUNTED (ora-1507)
1859 -- No database is mounted.
1860
1861 --**********************************
1862 -- Restore File List Specification--
1863 --*********************************--
1864
1865 -- The second phase of a restore conversation is to specify what to
1869 -- to specify all the files to be restored. Any files that appear in
1866 -- restore from a backup set and where to restore it. This is
1867 -- accomplished by calling these routines. Since a single backup set may
1868 -- contain multiple files, it may be necessary to make multiple calls
1870 -- the backup set, but are not mentioned in any calls, will be ignored
1871 -- by the restore. No files can be added to the list once the first
1872 -- backup piece is read. Only one destination can be given per file to
1873 -- restore. Errors while specifying the files to restore do not
1874 -- terminate the conversation.
1875
1876 PROCEDURE restoreControlfileTo(cfname IN varchar2);
1877
1878 -- This copies the controlfile from the backup set to an operating system
1879 -- file. If the database is mounted, the name must NOT match any of the
1880 -- current controlfiles.
1881 --
1882 -- Input parameters:
1883 -- cfname
1884 -- Name of file to create or overwrite with the controlfile from the
1885 -- backup set. When passed as NULL and database is not mounted, we
1886 -- restore and replicate the controlfiles to all names that match
1887 -- current controlfiles in parameter file.
1888 -- Exceptions:
1889 -- NAME-TOO-LONG (ora-19704)
1890 -- The specified file name is longer than the port-specific
1891 -- maximum file name length.
1892 -- CONVERSATION-NOT-ACTIVE (ora-19580)
1893 -- A restore conversation was not started before specifying files.
1894 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
1895 -- The database is in the process of being opened, closed, mounted,
1896 -- or dismounted.
1897 -- DATABASE-NOT-MOUNTED (ora-1507)
1898 -- The database is not mounted.
1899 -- WRONG-CONVERSATION-TYPE (ora-19592)
1900 -- This restore conversation is not for datafiles and controlfiles.
1901 -- CONVERSATION-IS-VALIDATE-ONLY (ora-19618)
1902 -- No files can be named after restoreValidate has been called.
1903 -- NAMING-PHASE-OVER (ora-19604)
1904 -- The first backup piece has been restored. No more files can be
1905 -- named.
1906 -- NO-OUTPUT-FILENAME (ora-19574)
1907 -- dest_name must be assigned a non-NULL string in copyControlFile.
1908 -- DUPLICATE-CONTROLFILE (ora-19594)
1909 -- The controlfile has already been specified for restoration.
1910 -- FILE-IN-USE (ora-19584)
1911 -- The specified output file is already in use by the database as a
1912 -- datafile or online redo log.
1913 -- CONTROLFILE-IS-ACTIVE (ora-19607)
1914 -- The destination file is the same as one of the controlfiles specified
1915 -- in the init.ora file.
1916 -- CONTROLFILE-IS-SNAPSHOT (ora-19606)
1917 -- The destination file is the snapshot controlfile. You cannot restore
1918 -- to the snapshot controlfile.
1919
1920 PROCEDURE restoreDataFileTo( dfnumber IN binary_integer
1921 ,toname IN varchar2 default NULL);
1922 --
1923 -- restoreDataFileTo creates the output file from a complete backup in the
1924 -- backup set.
1925
1926 PROCEDURE applyDataFileTo( dfnumber IN binary_integer
1927 ,toname IN varchar2 default NULL
1928 ,fuzziness_hint IN number default 0);
1929 --
1930 -- applyDataFileTo applies an incremental backup from the backup set to an
1931 -- existing copy of the datafile. Note that the incremental backup and the
1932 -- datafile must have the same resetlogs stamp, but this can not be detected
1933 -- until the restore is begun.
1934
1935 -- Add this file to the list of files to read from the backup. The file may
1936 -- be written to either the current version of the datafile, or to another
1937 -- copy. The current version is written if toname is NULL, or if it is the
1938 -- name of the current file.
1939 --
1940 -- If no database is mounted, toname must be given.
1941 -- If the database is open, the file must be offline to write to the current
1942 -- version.
1943 -- If there is a failure during a restore, the file will not be usable.
1944 --
1945 -- If there is a failure during an apply, the file's checkpoint will not
1946 -- be advanced, and its absolute fuzziness will be set to either the
1947 -- fuzziness hint passed by the caller or the greatest fuzziness found in
1948 -- the file itself, whichever is greater. Redo may be applied to
1949 -- compensate for the failed apply.
1950 --
1951 -- For full restores, in order to handle a failure during the restore,
1952 -- the output file header will have its file type set to zero until the
1953 -- restore is complete. This insures it cannot be used until the restore
1954 -- is complete. When the restore is complete, a valid header, with all
1955 -- fuzziness removed except the calculated absolute fuzziness, is written
1956 -- to the file.
1957 --
1958 -- When a datafile block in a backup set is found to be corrupt, we don't
1959 -- know which file it belongs to. The block will be discarded and a
1960 -- message will be written to the alert log. We will only know which
1961 -- files contained corrupt blocks when their DBA checksums (see next
1962 -- paragraph) are later found to be invalid. This only applies to blocks
1963 -- which fail cache header validation when read from the backup set, not
1964 -- to blocks that were marked media-corrupt or logically-corrupt when the
1965 -- backup set was created, but had valid cache headers.
1966 --
1967 -- A checksum is kept on all the DBAs stored in a backup set for each
1968 -- datafile. This checksum is stored in the datafile header, which is
1969 -- the last block in the backup set for each datafile. If, when reading
1973 -- advanced, although its absolute fuzziness may be increased. If this
1970 -- the datafile header, the checksum in the header does not match, then
1971 -- some blocks destined for that datafile must have been corrupt. If
1972 -- this is an incremental restore, the file's checkpoint will not be
1974 -- is a full restore, the file is invalid, and the header is not restored
1975 -- to a valid state.
1976 --
1977 -- It may also happen that the header is corrupt, and so is never seen.
1978 -- We will detect this when, prior to encountering the file's header, a
1979 -- piece header is read that indicates that the datafile should be
1980 -- completely contained on the prior pieces. This will also cause the
1981 -- restore of that datafile to fail.
1982 --
1983 -- Input parameters:
1984 -- dfnumber
1985 -- The datafile number of the datafile to restore.
1986 -- toname
1987 -- The name of a file to create or overwrite with the datafile from the
1988 -- backup set. This parameter is useful to direct the restore to a
1989 -- location different from the current datafile location. If this
1990 -- parameter is not used, the current datafile is overlaid with
1991 -- the restored file. This parameter must be specified if the database
1992 -- is not mounted.
1993 --
1994 -- The filename cannot already exist in the controlfile unless it is the
1995 -- current name of this file. (This check is not performed if the
1996 -- database is not mounted.) After completing the restore, an "ALTER
1997 -- DATABASE RENAME FILE 'xxx' TO 'yyy'" command command may be issued
1998 -- to point the controlfile to the restored datafile.
1999 -- fuzziness_hint
2000 -- This is the highest SCN that the client believes is contained in any
2001 -- block in the backup datafile. If the client supplies an accurate SCN
2002 -- then restore performance will be slightly improved, because the file
2003 -- header will only be re-written before restoring blocks with a higher
2004 -- SCN. If the client supplies a number that is greater than the actual
2005 -- fuzziness in the file, and the restore ends prematurely, then the
2006 -- datafile may require more redo than is truly necessary to bring the
2007 -- file to a consistent state.
2008 --
2009 -- Exceptions:
2010 -- NAME-TOO-LONG (ora-19704)
2011 -- The specified file name is longer than the port-specific
2012 -- maximum file name length.
2013 -- CONVERSATION-NOT-ACTIVE (ora-19580)
2014 -- A restore conversation was not started before specifying files.
2015 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
2016 -- The database is in the process of being opened, closed, mounted,
2017 -- or dismounted.
2018 -- OUTPUT-NAME-MUST-BE-SPECIFIED (ora-19616)
2019 -- The database is not mounted, but no output name was specified for
2020 -- restoreDataFileTo.
2021 -- WRONG-CONVERSATION-TYPE (ora-19592)
2022 -- This restore conversation is not for datafiles and controlfiles.
2023 -- CONVERSATION-IS-VALIDATE-ONLY (ora-19618)
2024 -- No files can be named after restoreValidate has been called.
2025 -- NAMING-PHASE-OVER (ora-19604)
2026 -- The first backup piece has been restored. No more files can be
2027 -- named.
2028 -- DUPLICATE-DATAFILE (ora-19593)
2029 -- This datafile has already been specified for restoration.
2030 -- FILE-IN-USE (ora-19584)
2031 -- The specified output file is already in use by the database as a
2032 -- datafile or online redo log.
2033 -- REAL-FILE-NOT-FOUND (ora-19576)
2034 -- When restoring a datafile to its original location, the
2035 -- datafile record describing the original file could no longer be
2036 -- found, probably because the file was dropped from the database.
2037 --
2038
2039 PROCEDURE restoreArchivedLogRange(
2040 low_change IN number default 0
2041 ,high_change IN number default 281474976710655 );
2042
2043 PROCEDURE restoreArchivedLog( thread IN binary_integer
2044 ,sequence IN number );
2045
2046 -- These procedures specify which logs to restore from a redo log backup
2047 -- set, and where to restore them. The logs can be specified either by
2048 -- giving an SCN range(restoreArchivedLogRange) or by giving a thread and
2049 -- sequence number(restoreArchivedLog). Multiple calls can be made to
2050 -- specify thread and sequence numbers, but only one SCN range and
2051 -- destination can be given per restore.
2052 --
2053 -- Input parameters:
2054 -- low_change
2055 -- Logs only containing redo below this SCN will not be restored unless
2056 -- explicitly requested by thread and sequence number. A log is not
2057 -- restored if its next SCN is less than or equal to low_change.
2058 -- high_change
2059 -- Logs only containing redo above this SCN will not be restored unless
2060 -- explicitly requested by thread and sequence number. A log is not
2061 -- restored if its low SCN is greater than high_change.
2062 -- thread
2063 -- sequence
2064 -- A log to be restored can be specified by giving its thread number and
2065 -- log sequence number.
2066 --
2067 -- Exceptions:
2068 -- INVALID-SCN (ora-19706)
2069 -- The incremental start SCN could not be converted into the internal
2070 -- SCN representation because it is non-integral, less than zero, or
2071 -- greater than the highest possible SCN.
2072 -- CONVERSATION-NOT-ACTIVE (ora-19580)
2073 -- A restore conversation was not started before specifying files.
2077 -- Only one archivelog range can be specified per restore conversation.
2074 -- WRONG-CONVERSATION-TYPE (ora-19592)
2075 -- This restore conversation is not for archived logs.
2076 -- ARCHIVELOG-RANGE-ALREADY-SPECIFIED (ora-19621)
2078 -- CONVERSATION-IS-VALIDATE-ONLY (ora-19618)
2079 -- No files can be named after restoreValidate has been called.
2080 -- NAMING-PHASE-OVER (ora-19604)
2081 -- The first backup piece has been restored. No more files can be
2082 -- named.
2083 -- INVALID-RANGE (ora-19628)
2084 -- The value of high_change is less than the value of low_change.
2085 -- DUPLICATE-RESTORE-ARCHIVELOG (ora-19636)
2086 -- This archivelog has already been specified for restoration.
2087
2088
2089 PROCEDURE restoreValidate;
2090
2091 -- This procedure is called to force the reading of the entire backup set as
2092 -- if all files in the backup were being restored. However no data will be
2093 -- written to any files. Incremental backup application does not require a
2094 -- valid file for applying the changes. No other calls to specify a restore
2095 -- file list may be made when this call is used.
2096 --
2097 -- After the conversation is complete, a report will be written to an oracle
2098 -- trace file, giving the status of all the files in the backup set. The
2099 -- report looks like this:
2100 --
2101 -- Restore Conversation File Status Report
2102 -- File Start Finish OK Name
2103 -- ----- ----- ------ -- --------------------
2104 -- 2 Y Y Y
2105 -- 4 Y Y Y
2106 -- 6 Y Y Y
2107 -- 3 Y Y Y
2108 -- 5 Y Y Y
2109 --
2110 -- One row is printed for each file in the in the backup set. The columns
2111 -- are as follows:
2112 -- start: at least one block for the indicated file was found in the backup
2113 -- set.
2114 -- finish: the header for the indicated file was found in the backup set.
2115 -- OK: the file's data in the backup set is complete and not corrupt.
2116 -- Name: for non-validation conversations, this is the target for this
2117 -- file. This report is not printed for non-validation conversations
2118 -- unless the krb_trace event is turned on.
2119
2120
2121
2122 --********************************
2123 -- Restoration from Backup Piece--
2124 --*******************************--
2125
2126 -- The third phase of a restore conversation is to read the pieces that
2127 -- make up the backup set and write the output files specified in the second
2128 -- phase. It is impossible to check for errors such as specifying a file
2129 -- that is not in the backup set until the first piece is read. Errors while
2130 -- processing a backup piece do not terminate the conversation. If the error
2131 -- can be repaired (e.g. the correct file is found or the hardware is
2132 -- fixed), the piece may be successfully reread and restored. However if the
2133 -- conversation is terminated, the entire backup set must be reread in a new
2134 -- restore conversation.
2135
2136 PROCEDURE restoreBackupPiece( handle IN varchar2
2137 ,done OUT boolean
2138 ,params IN varchar2 default NULL
2139 ,fromdisk IN boolean default FALSE );
2140
2141 PROCEDURE applyBackupPiece( handle IN varchar2
2142 ,done OUT boolean
2143 ,params IN varchar2 default NULL );
2144
2145 -- These procedures read one backup piece and write its contents to the
2146 -- files in the restore list.
2147 -- restoreBackupPiece creates files from complete backups.
2148 -- applyBackupPiece applies incremental backups to existing datafiles.
2149 --
2150 -- As soon as each target file is complete, records will be created in
2151 -- the appropriate controlfile tables. Records may be created in the
2152 -- following tables, depending on the type of restore conversation:
2153 --
2154 -- V$DATAFILE_COPY
2155 -- V$COPY_CORRUPTION
2156 -- V$ARCHIVED_LOG
2157 --
2158 -- If this was the last piece containing data required to restore the
2159 -- requested objects, then the "done" parameter is set to TRUE and the
2160 -- conversation is over. All resources allocated for the conversation are
2161 -- released.
2162 --
2163 -- Input parameters:
2164 -- handle
2165 -- The handle of the backup piece to restore from.
2166 -- params
2167 -- This string is simply passed to the sequential file open OSD. It is
2168 -- completely port and device specific.
2169 -- fromdisk
2170 -- TRUE if the backuppiece is from device disk. Used to dynamically
2171 -- allocate a disk context in SBT channel
2172 -- Output parameters:
2173 -- done
2174 -- TRUE if all requested objects have been completely restored, FALSE
2175 -- otherwise. Note that the restore may complete before we reach
2176 -- the last piece of the backup set. It is an error to call any of
2177 -- these procedures after "done" is set to TRUE.
2178 -- Exceptions:
2179 -- CONVERSATION-NOT-ACTIVE (ora-19580)
2180 -- A restore conversation was not started before specifying files.
2181 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
2182 -- The database is in the process of being opened, closed, mounted,
2183 -- or dismounted.
2184 -- DATABASE-NOT-MOUNTED (ora-1507)
2185 -- The database is not mounted.
2186 -- DEVICE-NOT-ALLOCATED (ora-19569)
2190 -- to restore.
2187 -- This session does not have a device allocated.
2188 -- NO-FILES (ora-19581)
2189 -- No files have been specified for restoration so there is nothing
2191 -- NOT-A-BACKUP-PIECE (ora-19608)
2192 -- The input file is not recognizable as a backup piece.
2193 -- WRONG-BACKUP-SET-TYPE
2194 -- This backup piece is from the wrong type of backup set. It cannot
2195 -- be processed by this conversation.
2196 -- WRONG-SET (ora-19609)
2197 -- The backup piece is not part of the backup set being restored from.
2198 -- WRONG-ORDER (ora-19611)
2199 -- The backup piece was supplied in the wrong order.
2200 -- CORRUPT-DIRECTORY (ora-19610)
2201 -- The backup piece directory is corrupt.
2202 -- CANT-GET-REAL-FILE-ENQUEUE (ora-19573)
2203 -- A datafile is locked. Another backup or restore could be in progress,
2204 -- or some other database activity, such as media recovery, holds an
2205 -- exclusive enqueue on the file.
2206 -- FILE-NOT-IN-BACKUP-SET (ora-19615)
2207 -- At least one of the files which were explicitely named for restoration
2208 -- is not found in this backup set. This applies only to
2209 -- files named by restoreControlFileTo, restoreDataFileTo,
2210 -- applyDataFileTo, and restoreArchivedLog. This error is raised only
2211 -- on the first piece of a backup set.
2212 -- NO-ARCHIVELOGS-IN-SCN-RANGE (ora-19629)
2213 -- This backup set contains no archivelogs in the specified range.
2214 -- DATAFILE-NOT-RESTORED (ora-19612)
2215 -- ARCHIVELOG-NOT-RESTORED (ora-19622)
2216 -- The indicated file could not be restored, because some of its
2217 -- blocks were corrupt in the backup set.
2218 -- DATAFILE-TOO-OLD
2219 -- At least one of the datafiles passed to applyDataFileTo is not
2220 -- current enough to apply this backup set. This error is raised
2221 -- only when applying an incremental backup set or a controlfile.
2222 -- DATAFILE-NOT-FOUND (ora-xxxx)
2223 -- At least one of the datafiles passed to applyDataFileTo can not
2224 -- be opened. This error is raised only when applying an incremental
2225 -- backup set.
2226 -- RECORD-NOT-FOUND (ora-xxxx)
2227 -- One of the files specified in the list of files to restore is not
2228 -- in the backup set. For applying offline ranges in a controlfile
2229 -- this error is returned when there is no offline range for the file.
2230 -- This error is only returned on the first piece of a backup set.
2231 -- WRONG-RESETLOGS
2232 -- Atempting to apply an incremental backup to a datafile with a
2233 -- different resetlogs time stamp. This error will not occur when
2234 -- applying a controlfile if the datafile is checkpointed cleanly
2235 -- at the beginning SCN of the offline range.
2236
2237 --******************************
2238 -- Restore Conversation Status
2239 --******************************
2240
2241 PROCEDURE restoreStatus( state OUT binary_integer
2242 ,pieceno OUT binary_integer
2243 ,files OUT binary_integer
2244 ,datafiles OUT boolean
2245 ,incremental OUT boolean
2246 ,device OUT boolean );
2247
2248 RESTORE_NO_CONVERSATION constant binary_integer := 0;
2249 RESTORE_NAMING_FILES constant binary_integer := 1;
2250 RESTORE_PIECE_READ constant binary_integer := 2;
2251 RESTORE_PIECE_RETRY constant binary_integer := 3;
2252
2253 -- restoreStatus returns information about the current restore
2254 -- conversation. It is useful for resyncing with a conversation after
2255 -- some error has interrupted normal execution, and it is now time to
2256 -- resume the conversation. It can also be called when there is no
2257 -- conversation.
2258 --
2259 -- Note that there are no exceptions since this does nothing but return
2260 -- information about this session.
2261 --
2262 -- Output parameters:
2263 -- state
2264 -- This defines the state of the restore conversation. It is one of the
2265 -- constants defined above. The constants have the following meanings.
2266 -- RESTORE_NO_CONVERSATION
2267 -- No restore conversation is currently active for this session. The
2268 -- other output values will be NULL when this state is returned. Note
2269 -- that this state does not signal an error.
2270 -- RESTORE_NAMING_FILES
2271 -- Still allowing more calls to describe files to restore. This is
2272 -- the state immediately after starting the conversation. This state
2273 -- continues until the first call to read a backup piece.
2274 -- RESTORE_PIECE_READ
2275 -- The last call to read a piece completed successfully.
2276 -- More pieces must be read to complete the restore.
2277 -- RESTORE_PIECE_RETRY
2278 -- The most recent call to read a backup piece signalled an error.
2279 -- The error may have been from writing one of the output
2280 -- files or some other failure. The return value pieceno does not
2281 -- include the piece that was being read. The restore can be
2282 -- continued by reissuing the call to read the same piece or another
2283 -- copy of the piece.
2284 -- pieceno
2285 -- This is the number of backup pieces that have been successfully
2286 -- restored. It is zero until the first call to read a backup piece
2287 -- returns successfully.
2288 -- files
2289 -- This is the number of files, data files or log files, that have been
2293 -- of files in the backup set which match the specified range has been
2290 -- named for restoration. It is zero immediately after the conversation
2291 -- begins. If restoreArchivedLogRange has been called, then this value
2292 -- may change after the first backup piece has been read and the number
2294 -- determined.
2295 -- datafiles
2296 -- TRUE if restoring datafiles; FALSE if restoring archived logs
2297 -- incremental
2298 -- TRUE if applying incremental backups of datafiles, or if using
2299 -- an offline range in a controlfile as an incremental backup.
2300 -- device
2301 -- TRUE if a device has been allocated to this session.
2302
2303 --***********************************
2304 -- Restore Conversation Termination--
2305 --**********************************--
2306
2307 PROCEDURE restoreCancel;
2308
2309 -- This procedure should be called to abort a restore conversation. It may
2310 -- be called at any time during a restore conversation. Any resources
2311 -- acquired to perform the restore are released. If this conversation
2312 -- is making full restores of datafiles, or restoring archived logs, then
2313 -- any partially restored files are unusable. If this conversation is
2314 -- applying an incremental backup to existing datafiles, then partially
2315 -- restored files may still be usable, but their checkpoints may not be
2316 -- advanced, and they may be fuzzier than before the restore began.
2317
2318 --*******************
2319 -- Retryable Errors--
2320 --******************--
2321
2322 -- It may be desirable to retry certain backup, restore, or copy
2323 -- operations if they fail with an I/O error. The following error code
2324 -- will be the top error on the stack when a retry may be possible.
2325 -- There will also be other messages on the error stack which may help a
2326 -- human to decide if a retry is possible.
2327 RETRYABLE_ERROR constant binary_integer := -19624;
2328
2329 --*************************************************
2330 -- Controlfile Fixed Table Redirection Procedures--
2331 --***********************************************--
2332
2333 -- These procedures allow the X$KCC fixed tables to be redirected to read
2334 -- a "snapshot controlfile" or a backup or standby controlfile rather than
2335 -- the current controlfile. A snapshot controlfile is a dynamically created
2336 -- "consistent-read" copy that is created under a dynamically specified
2337 -- filename. A snapshot controlfile enqueue is used to enforce serialization
2338 -- across instances of the creation and use of the snapshot controlfile.
2339
2340 PROCEDURE cfileSetSnapshotName( fname IN varchar2 );
2341
2342 -- This procedure sets the filename to be used for the snapshot
2343 -- controlfile during subsequent invocations of cfileMakeAndUseSnapshot
2344 -- and cfileUseSnapshot. However, in case that input filename is NULL,
2345 -- the procedure deletes the filename record for the snapshot controlfile.
2346 -- It attempts to acquire the snapshot controlfile enqueue in X mode,
2347 -- exiting with an exception if it is not available. On success, it exits
2348 -- with the snapshot controlfile enqueue released.
2349 --
2350 -- In case that the filename is not NULL, the file name is saved in the
2351 -- controlfile so that it is known database wide for the life of the
2352 -- database. However it will not be known in a standby database. It is
2353 -- preserved in backup controlfiles.
2354 -- In case that the filename is NULL, the snapshot controlfile name is
2355 -- deleted from the control file. In this case, cfileMakeAndUseSnapshot and
2356 -- cfileUseSnapshot will use default name snapshot controlfile name.
2357 --
2358 -- The invoker must not be inside a controlfile transaction when this
2359 -- routine is called; nor must he already hold the snapshot controlfile
2360 -- enqueue [as would result, e.g. from a prior invocation of
2361 -- cfileMakeAndUseSnapshot or cfileUseSnapshot without a matching invocation
2362 -- of cfileUseCurrent or cfileUseCopy]; nor must he have a copy controlfile
2363 -- in use [as would result, e.g. from a prior invocation of cfileUseCopy
2364 -- without a matching invocation of cfileUseCurrent].
2365 --
2366 -- Input parameters:
2367 -- fname
2368 -- Fully expanded operating system filename to be used for the snapshot
2369 -- controlfile during subsequent invocations of cfileMakeAndUseSnapshot
2370 -- and cfileUseSnapshot.
2371 -- Exceptions:
2372 -- MULTI-THREADED-SERVER (ora-19550)
2373 -- This session is not connected to a dedicated server.
2374 -- SNAPSHOT-ENQUEUE-BUSY (ora-230)
2375 -- The snapshot controlfile enqueue is in use by another process.
2376 -- DATABASE-NOT-MOUNTED (ora-xxxx)
2377 -- The database was not mounted when this procedure was invoked.
2378
2379 PROCEDURE cfileMakeAndUseSnapshot;
2380
2381 -- This procedure creates a snapshot of the current controlfile and stores
2382 -- it in a file it creates using the default filename or previously
2383 -- specified via cfileSetSnapshotName. It then sets up this process'
2384 -- PGA such that the X$KCC fixed tables will be redirected to read that
2385 -- snapshot controlfile rather than the current controlfile.
2386 -- At entry, it attempts to acquire the snapshot controlfile enqueue
2387 -- in X mode, exiting with an exception if it is not available, or if it
2388 -- is already held by this process.
2389 -- On success, it exits with the snapshot controlfile enqueue held in S mode.
2390 --
2391 -- The invoker must not be inside a controlfile transaction when this
2395 -- of cfileUseCurrent or cfileUseCopy]; nor must he have a copy controlfile
2392 -- routine is called; nor must he already hold the snapshot controlfile
2393 -- enqueue [as would result, e.g. from a prior invocation of
2394 -- cfileMakeAndUseSnapshot or cfileUseSnapshot without a matching invocation
2396 -- in use [as would result, e.g. from a prior invocation of cfileUseCopy
2397 -- without a matching invocation of cfileUseCurrent].
2398 --
2399 -- Exceptions:
2400 -- MULTI-THREADED-SERVER (ora-19550)
2401 -- This session is not connected to a dedicated server.
2402 -- SNAPSHOT-ENQUEUE-BUSY (ora-230)
2403 -- The snapshot controlfile enqueue is in use by another process.
2404 -- DATABASE-NOT-MOUNTED (ora-xxxx)
2405 -- The database was not mounted when this procedure was invoked.
2406 -- CREATE-ERROR
2407 -- An error was reported by the OSD invoked to create the file to hold
2408 -- the snapshot controlfile.
2409
2410 PROCEDURE cfileUseSnapshot;
2411
2412 -- This procedure sets up this process' PGA such that the X$KCC fixed tables
2413 -- will be redirected to read the snapshot controlfile previously created
2414 -- via (this or another process' invocation of) cfileMakeAndUseSnapshot.
2415 -- At entry, it attempts to acquire the snapshot controlfile enqueue in S
2416 -- mode, exiting with an exception if it is not available, or if it is
2417 -- already held by this process. On success, it exits with the snapshot
2418 -- controlfile enqueue held in S mode.
2419 --
2420 -- The invoker must not be inside a controlfile transaction when this
2421 -- routine is called; nor must he already hold the snapshot controlfile
2422 -- enqueue [as would result, e.g. from a prior invocation of
2423 -- cfileMakeAndUseSnapshot or cfileUseSnapshot without a matching invocation
2424 -- of cfileUseCurrent or cfileUseCopy]; nor must he have a copy controlfile
2425 -- in use [as would result, e.g. from a prior invocation of cfileUseCopy
2426 -- without a matching invocation of cfileUseCurrent].
2427 --
2428 -- Exceptions:
2429 -- MULTI-THREADED-SERVER (ora-19550)
2430 -- This session is not connected to a dedicated server.
2431 -- SNAPSHOT-ENQUEUE-BUSY (ora-230)
2432 -- The snapshot controlfile enqueue is in use by another process.
2433 -- DATABASE-NOT-MOUNTED (ora-xxxx)
2434 -- The database was not mounted when this procedure was invoked.
2435
2436 PROCEDURE cfileUseCurrent;
2437
2438 -- This procedure sets up this process' PGA such that the X$KCC fixed tables
2439 -- will revert to reading the current controlfile. It releases the
2440 -- snapshot controlfile enqueue if it was held at entry. Also closes any
2441 -- alternate controlfile that this process may currently have had in use for
2442 -- X$KCC fixed table redirection.
2443 --
2444 -- Exceptions:
2445 -- MULTI-THREADED-SERVER (ora-19550)
2446 -- This session is not connected to a dedicated server.
2447 -- DATABASE-NOT-MOUNTED (ora-xxxx)
2448 -- The database was not mounted when this procedure was invoked.
2449
2450 PROCEDURE cfileUseCopy( fname IN varchar2 );
2451
2452 -- This procedure sets up this process' PGA such that the X$KCC fixed tables
2453 -- will be redirected to read a backup or standby controlfile whose filename
2454 -- is specified. At entry, it releases the snapshot controlfile enqueue if
2455 -- it was held at entry. Also closes any alternate controlfile that this
2456 -- process may currently have had in use for X$KCC fixed table redirection.
2457 --
2458 -- The invoker must not be inside a controlfile transaction when this
2459 -- routine is called.
2460 --
2461 -- Input parameters:
2462 -- fname
2463 -- Operating system filename of a backup or standby controlfile to which
2464 -- all queries on X$KCC fixed tables will be redirected until one of the
2465 -- following procedures is invoked: cfileUseCurrent, cfileUseSnapshot,
2466 -- cfileMakeAndUseSnapshot.
2467 -- Exceptions:
2468 -- MULTI-THREADED-SERVER (ora-19550)
2469 -- This session is not connected to a dedicated server.
2470 -- SNAPSHOT-ENQUEUE-BUSY (ora-230)
2471 -- The snapshot controlfile enqueue is in use by another process.
2472 -- DATABASE-NOT-MOUNTED (ora-xxxx)
2473 -- The database was not mounted when this procedure was invoked.
2474 -- NOT-A-CONTROLFILE (ora-xxxx)
2475 -- The file specified by name is not a backup or standby controlfile.
2476
2477 --********************************
2478 -- Controlfile Sizing Procedures--
2479 --******************************--
2480
2481 -- These procedures are used to resize a record section of the controlfile
2482 -- and to calculate the size of a controlfile having specified counts of
2483 -- records of each type.
2484 --
2485 -- Valid record types are defined as the following constants:
2486
2487 RTYP_DB_INFO constant binary_integer := 0;
2488 RTYP_CKPTPROG constant binary_integer := 1;
2489 RTYP_THREAD constant binary_integer := 2;
2490 RTYP_LOGFILE constant binary_integer := 3;
2491 RTYP_DATAFILE constant binary_integer := 4;
2492 RTYP_FILENAME constant binary_integer := 5;
2493 RTYP_TABLESPACE constant binary_integer := 6;
2494 RTYP_RESERVED1 constant binary_integer := 7;
2495 RTYP_TEMPFILE constant binary_integer := 7;
2496 RTYP_RMAN_CONFIGURATION constant binary_integer := 8;
2497
2501 RTYP_BACKUP_SET constant binary_integer := 12;
2498 RTYP_LOG_HISTORY constant binary_integer := 9;
2499 RTYP_OFFLINE_RANGE constant binary_integer := 10;
2500 RTYP_ARCHIVED_LOG constant binary_integer := 11;
2502 RTYP_BACKUP_PIECE constant binary_integer := 13;
2503 RTYP_BACKUP_DFILE constant binary_integer := 14;
2504 RTYP_BACKUP_LOG constant binary_integer := 15;
2505 RTYP_DFILE_COPY constant binary_integer := 16;
2506 RTYP_BACKUP_DFILE_CORR constant binary_integer := 17;
2507 RTYP_DFILE_COPY_CORR constant binary_integer := 18;
2508 RTYP_DELETED_OBJECT constant binary_integer := 19;
2509 RTYP_RESERVED3 constant binary_integer := 20;
2510 RTYP_PROXY constant binary_integer := 20;
2511 RTYP_RESERVED4 constant binary_integer := 21;
2512 RTYP_BACKUP_SPFILE constant binary_integer := 21;
2513 RTYP_DB2 constant binary_integer := 22;
2514 RTYP_INCARNATION constant binary_integer := 23;
2515 RTYP_FLASHBACK constant binary_integer := 24;
2516 RTYP_RA_INFO constant binary_integer := 25;
2517 RTYP_INST_RSVT constant binary_integer := 26;
2518 RTYP_AGED_FILES constant binary_integer := 27;
2519 RTYP_RMAN_STATUS constant binary_integer := 28;
2520 RTYP_THREAD_INST constant binary_integer := 29;
2521 RTYP_MTR constant binary_integer := 30;
2522 RTYP_DFH constant binary_integer := 31;
2523 RTYP_SDM constant binary_integer := 32;
2524 RTYP_RSP constant binary_integer := 33;
2525 RTYP_NRR constant binary_integer := 34;
2526 RTYP_BLOCK_CORRUPTION constant binary_integer := 35;
2527 RTYP_ACM_OPERATION constant binary_integer := 36;
2528 RTYP_FOREIGN_ARCHIVED_LOG constant binary_integer := 37;
2529
2530
2531 PROCEDURE cfileResizeSection( record_type IN binary_integer
2532 ,before_numrecs OUT binary_integer
2533 ,after_numrecs OUT binary_integer
2534 ,delta_numrecs IN binary_integer default 0 );
2535
2536 -- This procedure attempts to resize the controlfile, expanding or shrinking
2537 -- the section holding records of the specified "record_type" such that it
2538 -- will hold "desired_numrecs" (rounded up to the nearest block boundary).
2539 --
2540 -- Input parameters:
2541 -- record_type
2542 -- The record type whose controlfile section is to be resized.
2543 -- Valid values are between RTYP_LOG_HISTORY and RTYP_<KCCDIMAX>
2544 -- delta_numrecs
2545 -- Number of record slots to expend(+) or shrink(-). The actual record
2546 -- slots might be rounded up(while expending) or rounded down(while
2547 -- shrinking) to the nearest block boundary.
2548 -- If delta_numrec == 0(default), both before_numrecs and after_numrecs
2549 -- return current record slots number.
2550 -- Output parameters:
2551 -- before_numrecs
2552 -- The number of record slots in the specified controlfile section at
2553 -- procedure entry time.
2554 -- after_numrecs
2555 -- The number of record slots in the specified controlfile section at
2556 -- procedure exit time.
2557 -- Exceptions:
2558 -- DATABASE-NOT-MOUNTED (ora-1507)
2559 -- The database was not mounted when this procedure was invoked.
2560 -- INVALID-RECTYPE (ora-xxxx)
2561 -- record_type was not between RTYP_LOG_HISTORY and RTYP_<KCCDIMAX>
2562 -- INVALID-DELTA-NUMRECS (ora-00219)
2563 -- "delta_numrecs" is invalid (either expand or shrink too much)
2564 -- RESIZE-ERROR
2565 -- The OSD invoked to resize the controlfile failed to accomplish the
2566 -- resize.
2567
2568
2569 FUNCTION cfileCalcSizeList(
2570 num_ckptprog_recs IN binary_integer default 0
2571 ,num_thread_recs IN binary_integer default 0
2572 ,num_logfile_recs IN binary_integer default 0
2573 ,num_datafile_recs IN binary_integer default 0
2574 ,num_filename_recs IN binary_integer default 0
2575 ,num_tablespace_recs IN binary_integer default 0
2576 ,num_tempfile_recs IN binary_integer default 0
2577 ,num_rmanconfiguration_recs IN binary_integer default 0
2578 ,num_loghistory_recs IN binary_integer default 0
2579 ,num_offlinerange_recs IN binary_integer default 0
2580 ,num_archivedlog_recs IN binary_integer default 0
2581 ,num_backupset_recs IN binary_integer default 0
2582 ,num_backuppiece_recs IN binary_integer default 0
2583 ,num_backedupdfile_recs IN binary_integer default 0
2584 ,num_backeduplog_recs IN binary_integer default 0
2585 ,num_dfilecopy_recs IN binary_integer default 0
2586 ,num_bkdfcorruption_recs IN binary_integer default 0
2587 ,num_dfcopycorruption_recs IN binary_integer default 0
2588 ,num_deletedobject_recs IN binary_integer default 0
2589 ,num_proxy_recs IN binary_integer default 0
2590 ,num_reserved4_recs IN binary_integer default 0)
2594 -- Obsolete from 10gR2 onwards - always returns 0
2591 return binary_integer;
2592
2593 --
2595 --
2596 -- cfileCalcSizeList takes a list of parameters, for each
2597 -- record type, the number of record slots postulated for the section
2598 -- containing records of that type.
2599 --
2600
2601 TYPE nrecs_array IS TABLE OF binary_integer INDEX BY BINARY_INTEGER;
2602
2603 FUNCTION cfileCalcSizeArray( num_recs IN nrecs_array )
2604 return binary_integer;
2605
2606 --
2607 -- Obsolete from 10gR2 onwards - always returns 0
2608 --
2609 -- cfileCalcSizeArray takes an array of parameters, at indices
2610 -- corresponding to each of the record types RTYP_DB_INFO through
2611 -- RTYP_<KCCDIMAX>, the number of record slots postulated for the
2612 -- section containing records of that type.
2613
2614 -- The two procedures return the size in blocks
2615 -- ,database blocksize, that the controlfile would have if it were sized
2616 -- to contain the specified counts of records of each type.
2617 -- If the number of records is missing for a type then the
2618 -- number of records in the current controlfile is used.
2619
2620 -- Input parameters:
2621 -- num_xxxxx_recs
2622 -- The input parameters specify the number of records to presume for
2623 -- each type of record. If a parameter is 0, the value from the
2624 -- existing controlfile is used.
2625 -- num_recs
2626 -- A array giving the sizes of each record type. The indexes in the
2627 -- table are the record type constants defined above. If 0, the
2628 -- values from the existing controlfile are used.
2629 --
2630 -- Output parameter:
2631 -- param_in_error
2632 -- If any of the input parameters or num_recs contains an invalid
2633 -- number of record, e.g. a negative value or a value
2634 -- greater than the maximum number of records permitted in a
2635 -- controlfile section, then param_in_error will contain the index
2636 -- of the record type of the first parameter in error. If no error,
2637 -- it is 0.
2638 --
2639 -- Return value:
2640 -- Return the size in blocks needed to contain a controlfile having
2641 -- sections containing, at least, the specified number of record
2642 -- slots of each record type.
2643
2644
2645
2646 --***************************
2647 -- Miscellaneous Procedures
2648 --***************************
2649
2650 PROCEDURE deleteFile( fname IN varchar2 );
2651
2652 -- Delete a file from the operating system. The operating system is called
2653 -- to delete the file name given. The effect of processes that already have
2654 -- the file open may differ between platforms. Note that this has no effect
2655 -- on the state of the database or controlfile. There are no checks to insure
2656 -- that the file is not part of the database. This may be done at any time.
2657 --
2658 -- WARNING! This procedure should not be used to delete files that are named
2659 -- by controlfile entries. Use deleteDataFile, or deleteRedoLog. Those
2660 -- routines will mark the controlfile entries as obsolete so that they no
2661 -- longer appear in V$ tables.
2662 --
2663 -- Input parameters:
2664 -- fname
2665 -- Name of the operating system file to delete
2666 -- Exceptions:
2667 -- FNAME-NOT-SPECIFIED (ora-19634)
2668 -- The fname must be specified and may not be null.
2669 -- DELETE-ERROR
2670 -- An error was reported by the OSD to delete the file.
2671
2672
2673 PROCEDURE deleteBackupPiece( recid IN number
2674 ,stamp IN number
2675 ,handle IN varchar2
2676 ,set_stamp IN number
2677 ,set_count IN number
2678 ,pieceno IN binary_integer
2679 ,params IN varchar2 default NULL );
2680
2681 -- Delete a backup piece from the storage subsystem. If a controlfile record
2682 -- ID is given, it is marked as obsolete so that it will no longer appear in
2683 -- V$BACKUP_PIECE. If the stamp in the record does not match the stamp
2684 -- argument, the controlfile record will not be marked as obsolete. The
2685 -- record is marked as obsolete before the OSD is called to do the delete.
2686 -- Thus a failure could result in the piece continuing to exist while the
2687 -- controlfile record is marked obsolete. An I/O error during the delete
2688 -- will return an error, but still mark the controlfile record as obsolete.
2689 --
2690 -- A device must be allocated in order to specify the device type. It is
2691 -- acceptable for some device types to not allocate a specifically named
2692 -- device for deleting even though a specific device name is needed for
2693 -- other operations. This is indicated by setting the noio argument to TRUE
2694 -- for the deviceAllocate procedure.
2695 --
2696 -- Input parameters:
2697 -- recid
2698 -- stamp
2699 -- These are the key for the record in the controlfile where the
2700 -- information about the backup piece was recorded. This is the record
2701 -- that will be marked as obsolete.
2702 -- handle
2703 -- The sequential file handle of the backup piece to delete. This is
2704 -- only used if the recid/stamp are not found in the controlfile. This
2705 -- field also participates in validation - if the backup piece record
2706 -- identified by recid/stamp is found and the handle does not match the
2710 -- pieceno
2707 -- handle in that record, then an error is signalled.
2708 -- set_stamp
2709 -- set_count
2711 -- Used to validate that the file is the correct file.
2712 -- params
2713 -- This string is simply passed to the sequential file delete OSD. It is
2714 -- completely port and device specific.
2715 -- Exceptions:
2716 -- DEVICE-NOT-ALLOCATED (ora-19569)
2717 -- This session does not have a device allocated.
2718 -- DATABASE-NOT-MOUNTED (ora-1507)
2719 -- The database is not mounted.
2720 -- RECOVERY-CATALOG-ERROR (ora-19633)
2721 -- The validation information passed to this function is out of sync
2722 -- with the information in the controlfile.
2723 -- FNAME-NOT-SPECIFIED (ora-19634)
2724 -- The handle must be specified and may not be null.
2725 -- DELETE-ERROR
2726 -- An error was reported by the OSD to delete the file.
2727
2728 PROCEDURE deleteDataFileCopy( recid IN number
2729 ,stamp IN number
2730 ,fname IN varchar2
2731 ,dfnumber IN binary_integer
2732 ,resetlogs_change IN number
2733 ,creation_change IN number
2734 ,checkpoint_change IN number
2735 ,blksize IN number
2736 ,no_delete IN binary_integer );
2737
2738 PROCEDURE deleteArchivedLog(recid IN number
2739 ,stamp IN number
2740 ,fname IN varchar2
2741 ,thread IN number
2742 ,sequence IN number
2743 ,resetlogs_change IN number
2744 ,first_change IN number
2745 ,blksize IN number );
2746
2747 -- These procedures delete an operating system file and mark its record in
2748 -- the controlfile as obsolete so that its row will not appear in the fixed
2749 -- view. If the stamp in the record does not match the stamp argument, the
2750 -- controlfile record will not be marked as obsolete. The record is marked
2751 -- as obsolete before the OSD is called to do the delete. Thus a failure
2752 -- could result in the piece continuing to exist while the controlfile record
2753 -- is marked obsolete. An I/O error during the delete will return an error,
2754 -- but still mark the controlfile record as obsolete.
2755 --
2756 -- Input parameters:
2757 -- recid
2758 -- stamp
2759 -- These are the key of the record in the controlfile where the
2760 -- information about the file was recorded. This is the record
2761 -- that will be marked as obsolete.
2762 -- fname
2763 -- Name of the operating system file to delete. This is
2764 -- only used if the recid/stamp are not found in the controlfile. This
2765 -- field also participates in validation - if the backup piece record
2766 -- identified by recid/stamp is found and the handle does not match the
2767 -- handle in that record, then an error is signalled.
2768 -- dfnumber
2769 -- Absolute file number. This and the remaining parameters are used to
2770 -- validate the file if the record is not found in the controlfile.
2771 -- resetlogs_change
2772 -- Resetlogs SCN.
2773 -- creation_change
2774 -- Creation SCN.
2775 -- checkpoint_change
2776 -- Checkpoint SCN.
2777 -- blksize
2778 -- Blocksize.
2779 -- thread
2780 -- Log thread number.
2781 -- sequence
2782 -- Log sequence number.
2783 -- first_change
2784 -- Low SCN.
2785 -- no_delete
2786 -- Flag for UNCATALOG option, datafile'll not be deleted when set
2787 -- Exceptions:
2788 -- DATABASE-NOT-MOUNTED (ora-1507)
2789 -- The database is not mounted.
2790 -- RECOVERY-CATALOG-ERROR (ora-19633)
2791 -- The validation information passed to this function is out of sync
2792 -- with the information in the controlfile.
2793 -- FNAME-NOT-SPECIFIED (ora-19634)
2794 -- The handle must be specified and may not be null.
2795 -- DELETE-ERROR
2796 -- An error was reported by the OSD to delete the file.
2797
2798 -- we need a placeholder for the deleted function, getDbInfo, in order
2799 -- to maintain pl/sql compatibility.
2800 PROCEDURE DELETED_getDbInfo;
2801
2802 PROCEDURE getFno( name IN varchar2
2803 ,dfnumber OUT binary_integer
2804 ,creation_change OUT number );
2805
2806 -- This procedure will expand the name and compare it with all the datafile
2807 -- names and return the file number for the matching file. The comparison is
2808 -- done through the operating system so that two different names for the same
2809 -- file will compare as equal. This is used to convert file names from the
2810 -- user into file numbers for use with the other procedures in this package.
2811 -- A straight string compare will no suffice because there maybe multiple
2812 -- names that refer to the same file. The database must be mounted so that
2813 -- the file names can be queried from the controlfile. Note that a call to
2814 -- switchControlfile will have no effect on getFno.
2815 --
2816 -- Input parameters:
2817 -- name
2818 -- The name of the file to lookup in the controlfile.
2819 -- Output parameters:
2823 -- The SCN that was allocated when the file was created.
2820 -- dfnumber
2821 -- The number of the datafile with the matching name.
2822 -- creation_change
2824 -- Exceptions:
2825 -- DATABASE-NOT-MOUNTED (ora-1507)
2826 -- The database is not mounted.
2827 -- FILE-NUMBER-NOT-FOUND (ora-19632)
2828 -- No datafile with this name could be found in the controlfile.
2829
2830 FUNCTION scanDataFile(dfnumber IN binary_integer,
2831 max_corrupt IN binary_integer default 0,
2832 update_fuzziness IN boolean default true)
2833 return number;
2834
2835 FUNCTION scanDataFileCopy(recid IN number,
2836 stamp IN number,
2837 max_corrupt IN binary_integer default 0,
2838 isbackup IN boolean default FALSE,
2839 update_fuzziness IN boolean default true)
2840 return number;
2841
2842 PROCEDURE scanArchivedLog(recid IN number,
2843 stamp IN number);
2844
2845 -- Scans a file and verifies the checksum (if present) in each block.
2846 --
2847 -- If processing the current datafile, the database must be closed or the
2848 -- file must be offline.
2849 --
2850 -- Input parameters:
2851 -- dfnumber
2852 -- The real datafile to scan.
2853 -- recid, stamp
2854 -- The datafile copy or archivelog to scan.
2855 -- max_corrupt
2856 -- Up to this many corrupt data blocks (blocks that fail cache header
2857 -- validation) may appear in this file. The file header will not be
2858 -- be updated if more blocks than this fail cache header validation.
2859 -- isbackup
2860 -- If true, then Recovery Manager is treating this file as a level 0
2861 -- backup in the database's recovery strategy. This information is
2862 -- simply stored in the V$DATAFILE_COPY record created by this inspect
2863 -- operation, and has no other effect.
2864 -- update_fuzziness
2865 -- If true, then the fuzziness information in the header of a datafile
2866 -- will be updated. The file's fuzziness is the highest SCN in the
2867 -- cache header of any block in the datafile, plus one.
2868 -- Returns:
2869 -- If update_fuzziness is true, then the return value is the absolute
2870 -- fuzzy SCN of the file, otherwise the return value is undefined.
2871 --
2872
2873 PROCEDURE switchToCopy( copy_recid IN number
2874 ,copy_stamp IN number );
2875
2876 -- Causes the filename in the indicated datafile copy record to become
2877 -- the current named datafile. The file number to rename is taken from
2878 -- the V$DATAFILE_COPY record. Does the following:
2879 --
2880 -- 1. Begin a read/write controlfile transaction.
2881 -- 2. If the database is open, ensure that the named file is not open.
2882 -- 3. Validate that the data in the V$DATAFILE_COPY record matches the
2883 -- data in the file header of the copied file.
2884 -- 4. Alter the file name entry for the named file to point to the copy.
2885 -- 5. Mark the V$DATAFILE_COPY record as deleted.
2886 -- 6. End the controlfile transaction.
2887 --
2888 -- Much of what this function does could have been done in the ordinary
2889 -- 'alter database rename file' code - that code could scan the
2890 -- V$DATAFILE_COPY records and delete any that are consumed by the
2891 -- rename. The code could also perform the additional header validations
2892 -- that are required when we know that the destination file exists.
2893 -- There are two reasons why we decided not to do this:
2894 -- 1. No matter how efficient we are in deleting obsolete V$DATFILE_COPY
2895 -- records, the Recovery Manager will still need its own algorithm to
2896 -- detect when some operation has caused a named file to consume a
2897 -- datafile copy. This is because the appropriate datafile copy record
2898 -- may have been reused in the controlfile, and only exists in the
2899 -- recovery catalog when, for example, a user issues a 'rename' that
2900 -- consumes a datafile copy.
2901 -- 2. If we decide to add such special handling for 'rename', we would also
2902 -- have to add code to 'alter tablespace add datafile', and perhaps other
2903 -- functions as well, and we don't want to do all that right now.
2904 --
2905 -- Input parameters:
2906 -- copy_recid
2907 -- The record ID from V$DATAFILE_COPY for the datafile copy. This
2908 -- is the record ID returned from inspectDataFileCopy or a previous call
2909 -- to make a datafile copy.
2910 -- copy_stamp
2911 -- The stamp that corresponds to copy_recid. This is to insure that the
2912 -- record is the same one that was selected.
2913 -- Exceptions:
2914 -- DATABASE-NOT-MOUNTED (ora-1507)
2915 -- The database is not mounted.
2916 -- RECORD-NOT-FOUND (ora-19571)
2917 -- The specified datafile copy record does not exist.
2918 -- RECORD-NOT-VALID (ora-19588)
2919 -- The specified datafile copy record is no longer valid - it has been
2920 -- marked as deleted.
2921 -- CANNOT-RENAME-TO-FILE (ora-01523)
2922 -- The specified file is already part of the database.
2923 -- FILE-IS-OPEN (ora-19623)
2924 -- The controlfile record points to a file that is currently open
2925 -- by the database.
2926 -- FILE-NOT-FOUND (ora-19625)
2927 -- The file can not be opened.
2928 -- FILE-VALIDATION-FAILURE (ora-19563)
2929 -- The file is not the file described by the controlfile record.
2930
2934 -- database and returns the normalized filename.
2931 FUNCTION normalizeFileName (fname IN varchar2) RETURN varchar2;
2932
2933 -- Normalizes the file name according to the rules of the target
2935 --
2936 -- Input parameters:
2937 -- fname
2938 -- File name to be normalized.
2939 -- Exceptions:
2940 -- NAME-TOO-LONG (ora-19704)
2941 -- The specified file name is longer than the port-specific
2942 -- maximum file name length.
2943
2944 FUNCTION validateBackupPiece(recid IN number
2945 ,stamp IN number
2946 ,handle IN varchar2
2947 ,set_stamp IN number
2948 ,set_count IN number
2949 ,pieceno IN binary_integer
2950 ,params IN varchar2 default NULL)
2951 return binary_integer;
2952
2953 FUNCTION validateDataFileCopy(recid IN number
2954 ,stamp IN number
2955 ,fname IN varchar2
2956 ,dfnumber IN binary_integer
2957 ,resetlogs_change IN number
2958 ,creation_change IN number
2959 ,checkpoint_change IN number
2960 ,blksize IN number)
2961 return binary_integer;
2962
2963 FUNCTION validateArchivedLog(recid IN number
2964 ,stamp IN number
2965 ,fname IN varchar2
2966 ,thread IN number
2967 ,sequence IN number
2968 ,resetlogs_change IN number
2969 ,first_change IN number
2970 ,blksize IN number)
2971 return binary_integer;
2972
2973 VALIDATE_OK constant binary_integer := 0;
2974 VALIDATE_RECORD_NOTFOUND constant binary_integer := 1;
2975 VALIDATE_RECORD_DIFFERENT constant binary_integer := 2;
2976 VALIDATE_FILE_DIFFERENT constant binary_integer := 4;
2977 VALIDATE_IN_USE constant binary_integer := 8;
2978 VALIDATE_DEL_FOR_SPACE constant binary_integer := 16;
2979
2980 -- Validate the correctness of the information in the recovery catalog
2981 -- and the controlfile regarding a backup piece, datafile copy, or
2982 -- archived log. Neither the controlfile record nor the file itself is
2983 -- deleted. No errors are signalled. The return code contains one or more
2984 -- of the above constants, which tell the caller whether the controlfile
2985 -- record and/or the file itself is valid. These constants are bit-flags,
2986 -- so bitand() must be used to decode the return code's value. The status
2987 -- of the file itself is independant of the status of the record in the
2988 -- controlfile. If the file is not found or does not match the validation
2989 -- data, then the VALIDATE_FILE_DIFFERENT flag will be set. If the
2990 -- record in the controlfile is not found or is different, the corresponding
2991 -- VALIDATE_RECORD_xxx flag will be set. The two VALIDATE_RECORD_xxx flags
2992 -- are mutually exclusive. Thus, the possible return codes from the validate
2993 -- functions are: 0, 1, 2, 4, 5, and 6.
2994 --
2995 -- These procedures do not update the controlfile.
2996 --
2997 -- Input parameters:
2998 -- stamp
2999 -- recid
3000 -- These are the key of the record in the controlfile where the
3001 -- information about the file was recorded. This is the record
3002 -- that will be marked as obsolete if the file is no longer valid.
3003 -- handle
3004 -- fname
3005 -- The name or handle of the file/piece to validate.
3006 -- params
3007 -- This string is simply passed to the sequential file reading OSD. It
3008 -- is completely port and device specific.
3009
3010 -- The remaining parameters are used to determine whether or not the
3011 -- file in question is the correct file.
3012
3013 -- set_stamp
3014 -- set_count
3015 -- Backup set identification.
3016 -- pieceno
3017 -- Piece number within backup set.
3018 -- dfnumber
3019 -- Absolute file number.
3020 -- resetlogs_change
3021 -- Resetlogs SCN.
3022 -- creation_change
3023 -- Creation SCN.
3024 -- checkpoint_change
3025 -- Checkpoint SCN.
3026 -- blksize
3027 -- Blocksize.
3028 -- thread
3029 -- Log thread number.
3030 -- sequence
3031 -- Log sequence number.
3032 -- first_change
3033 -- Low SCN of archived log.
3034 -- Returns:
3035 -- VALIDATE_OK
3036 -- Both the record and file exist, and the contents of the controlfile
3037 -- record, the file header, and the caller's validation data are the
3038 -- same.
3039 -- VALIDATE_RECORD_NOTFOUND
3040 -- The specified recid/stamp is not found in the controlfile.
3041 -- VALIDATE_RECORD_DIFFERENT
3042 -- The specified recid/stamp is found in the controlfile but its contents
3043 -- don't match the user's validation data.
3044 -- VALIDATE_FILE_DIFFERENT
3045 -- The specified recid/stamp is found in the controlfile and its contents
3046 -- match the user's validation data, but the file is either not found or
3047 -- its contents don't match.
3051 -- Applies to validateBackupPiece only.
3048 -- Exceptions:
3049 -- DEVICE-NOT-ALLOCATED (ora-19569)
3050 -- This session does not have a device allocated.
3052 -- DATABASE-NOT-MOUNTED (ora-1507)
3053 -- The database is not mounted.
3054 -- RECOVERY-CATALOG-ERROR (ora-19633)
3055 -- The validation information passed to this function is out of sync
3056 -- with the information in the controlfile.
3057 -- FNAME-NOT-SPECIFIED (ora-19634)
3058 -- The handle or file name must be specified and may not be null.
3059 -- If signal is not zero, then krbcdie[] exceptions are possible.
3060
3061 function getParm(parmid IN binary_integer,
3062 parmno IN binary_integer default null) return varchar2;
3063
3064 -- Return some parameter string value.
3065 -- The valid list of parmid's follows.
3066
3067 -- Get the default value for the snapshot controlfile name.
3068 SNAPSHOT_NAME constant binary_integer := 0;
3069
3070 -- Get the controlfile name(s) from the parameter file. parmno must be a
3071 -- value between 1 and the number of controlfiles defined in the
3072 -- CONTROL_FILES initialization parameter.
3073 CONTROL_FILE constant binary_integer := 1;
3074
3075 -- Get the pattern or replace string for db_file_name_convert
3076 -- parmno must be greater than 0
3077 DBF_CONVERT constant binary_integer := 2;
3078
3079 -- Get the pattern or replace string for log_file_name_convert
3080 -- parmno must be greater than 0
3081 LOG_CONVERT constant binary_integer := 3;
3082
3083 -- Get the default value for the SPFILE name.
3084 -- parmno is ignored
3085 -- The name is retrieved in following order:
3086 -- 1) If _restore_spfile is set to a non empty string, then return.
3087 -- 2) If _restore_spfile is not set, the parse default pfile location
3088 -- for a spfile value. If set to a non-empty string, then return.
3089 -- 3) Return default spfile location.
3090 SPFILE_DEFAULT constant binary_integer := 4;
3091
3092 -- Force the current incremental backup conversation to *not* attempt to
3093 -- accelerate using change tracking data
3094 INCR_NOCT constant binary_integer := 5;
3095
3096 -- Return the default format for controlfile autobackups on DISK devices.
3097 -- parmno is ignored
3098 CFAUTO_DISK_DEFAULT constant binary_integer := 6;
3099
3100 -- Return the default format for controlfile autobackups on TAPE devices.
3101 -- parmno is ignored
3102 CFAUTO_TAPE_DEFAULT constant binary_integer := 7;
3103
3104 -- Return the default format for datafilecopies and backups.
3105 -- parmno is ignored
3106 FORMAT_DEFAULT constant binary_integer := 8;
3107
3108 -- Force the current full backup conversation to *not* attempt to
3109 -- optimize backing up only the allocated blocks
3110 FULL_NOOPTIM constant binary_integer := 9;
3111
3112 -- Get the platform id of the database
3113 PLATFORM_ID constant binary_integer := 10;
3114
3115 -- Get trace file name
3116 TRACE_FILENAME constant binary_integer := 11;
3117
3118 -- Get password file name
3119 PASSWORD_FILENAME constant binary_integer := 12;
3120
3121 -- Check KD_ACO_ENABLED, return T is enabled, F otherwise
3122 ACO_ENABLED constant binary_integer := 13;
3123
3124 -- Same as CONTROL_FILE, but also look at DB_FILE_CREATE_DEST, not only
3125 -- at v$parameter
3126 XCONTROL_FILE constant binary_integer := 14;
3127
3128 -- Required by instant restore feature to get the backing file name
3129 -- from an instantly restored datafile
3130 BACKING_FILENAME constant binary_integer := 15;
3131
3132 PROCEDURE applyOfflineRange(cfname in varchar2 default null,
3133 dfname in varchar2 default null,
3134 blksize in number default null,
3135 recid in number default null,
3136 stamp in number default null,
3137 fno in binary_integer);
3138
3139 -- This applies an offline range record from the named controlfile to the
3140 -- named datafile. The controlfile can be either a backup controlfile or
3141 -- a current controlfile. The datafile must be from the same database as
3142 -- the controlfile. The offline range record identified by the
3143 -- recid/stamp parameters will be used as an incremental backup which
3144 -- contains no block images since there were no blocks changed. If the
3145 -- datafile's checkpoint is exactly at the beginning of the offline
3146 -- range, and the file is not fuzzy, then it will have datafile with a
3147 -- checkpoint at the beginning of offline range will have its checkpoint
3148 -- updated to the end of the offline range.
3149 --
3150 -- This has one advantage over a real incremental backups: a controlfile
3151 -- can be applied to a file that has a different resetlogs stamp, but an
3152 -- incremental backup can not modify the resetlogs stamp in a file
3153 -- header.
3154 --
3155 -- Note that it is not necessary to apply the current controlfile if the
3156 -- database is mounted. That will be done automatically by applying either
3157 -- redo logs or incremental backup.
3158 --
3159 -- Input parameters:
3160 -- cfname
3161 -- the operating system filename of the controlfile that contains the
3162 -- desired offline range record.
3163 -- dfname
3164 -- the operating system name of the datafile whose checkpoint will
3165 -- be advanced if it meets the criteria described above. if null,
3166 -- fno must not be null.
3167 -- blksize
3171 -- the recid and stamp of the desired offline range record.
3168 -- Oracle block size of the specified datafile.
3169 -- recid
3170 -- stamp
3172 -- fno
3173 -- datafile number. if dfname is null, then apply to the current
3174 -- datafile with this number. ignored unless dfname is null.
3175 -- Exceptions:
3176 -- CONVERSATION-ACTIVE (ora-19590)
3177 -- There is still either a backup or restore conversation still active
3178 -- in this session.
3179
3180 procedure getCkpt(ckp_scn OUT number
3181 ,high_cp_recid OUT number -- 1
3182 ,high_rt_recid OUT number -- 2
3183 ,high_le_recid OUT number -- 3
3184 ,high_fe_recid OUT number -- 4
3185 ,high_fn_recid OUT number -- 5
3186 ,high_ts_recid OUT number -- 6
3187 ,high_r1_recid OUT number -- 7
3188 ,high_rm_recid OUT number -- 8
3189 ,high_lh_recid OUT number -- 9
3190 ,high_or_recid OUT number -- 10
3191 ,high_al_recid OUT number -- 11
3192 ,high_bs_recid OUT number -- 12
3193 ,high_bp_recid OUT number -- 13
3194 ,high_bf_recid OUT number -- 14
3195 ,high_bl_recid OUT number -- 15
3196 ,high_dc_recid OUT number -- 16
3197 ,high_fc_recid OUT number -- 17
3198 ,high_cc_recid OUT number -- 18
3199 ,high_dl_recid OUT number -- 19
3200 ,high_r3_recid OUT number -- 20
3201 ,high_r4_recid OUT number -- 21
3202 );
3203
3204 -- Obtains an SCN and returns the high-recids from the controfile record
3205 -- section for each type of controlfile record. The recids and the
3206 -- SCN are allocated from inside a controlfile transaction. If the database
3207 -- is not open, then the SCN is calculated in the same way as for
3208 -- a backup controlfile.
3209
3210 procedure sleep(secs IN binary_integer);
3211
3212 -- Sleep for the specified number of seconds.
3213
3214 function checkFileName(name IN varchar2) return number;
3215 -- Returns 0 if the filename is not in use by the database as a
3216 -- controlfile, datafile, or online logfile. Returns 1 if the filename
3217 -- is in use. The filename must be normalized by the caller.
3218
3219 procedure set_client_info(client_info IN varchar2);
3220 -- This is equivalent to dbms_application_info.set_client_info, and was
3221 -- added so RMAN could call it from recover.bsq without needing to make
3222 -- the x$kqp326 package spec public.
3223
3224 PROCEDURE set_charset(charset_name IN VARCHAR2);
3225 -- If the database is closed, then make the specified charset be
3226 -- the charset for this session.
3227
3228 -- ********************************************************
3229 -- Proxy Copy procedures
3230 -- ********************************************************
3231
3232 -- Proxy copy is a new backup paradigm. Instead of Oracle reading
3233 -- the datafiles and passing the data to a storage subsystem (or doing
3234 -- the reverse when restoring), we simply pass the name of a file to be
3235 -- backed up, and a backup handle, to the storage subsystem, which
3236 -- handles all of the data movement.
3237 --
3238 -- These procedures are conversational, as are the backup/restore
3239 -- procedures above, and they also require that a device be allocated
3240 -- prior to calling them. The allocated device may not be of type DISK,
3241 -- because the DISK device does not invoke an external media manager.
3242 --
3243 -- The parameters to these routines have the same semantics as the
3244 -- corresponding parameters to the non-proxy routines above.
3245 --
3246 -- A new controlfile record type is used to record the existence of proxy
3247 -- copies in the controlfile. The same record type is used to store
3248 -- information about both proxy datafiles and proxy archived logs, but
3249 -- two different fixed views are used to display the information:
3250 -- v$proxy_datafile and v$proxy_archivedlog.
3251
3252 PROCEDURE proxyBeginBackup(tag IN varchar2 default NULL
3253 ,incremental IN boolean default FALSE
3254 ,media_pool IN binary_integer default 0
3255 ,set_stamp OUT number
3256 ,set_count OUT number);
3257
3258 -- Begin a proxy backup session. The database must be mounted for proxy
3259 -- backups, so that the backups can be recorded in the controlfile.
3260 --
3261 -- Input Parameters
3262 -- tag
3263 -- An arbitrary user-defined tag, up to 30 characters long, that is
3264 -- stored in the controlfile record describing DATAFILES that are
3265 -- proxy backed up. Proxy ARCHIVELOGS do not have a tag.
3266 -- incremental
3267 -- If TRUE, then this file will be considered as a level-0 incremental
3268 -- backup, which can be the basis for subsequent incremental backups.
3269 -- This applies only to datafiles, not archived logs.
3270 -- media_pool
3271 -- a number from 0-255 whose meaning is defined by rman or by 3rd-party
3272 -- media management software.
3273 -- set_stamp
3274 -- set_count
3275 -- a timestamp and counter that are used by recovery manager to generate
3276 -- unique file names.
3277
3278 PROCEDURE proxyBeginRestore(destination IN varchar2 default NULL);
3279
3280 -- Begin a proxy restore session. The database does not have to be mounted,
3284 -- controlfile.
3281 -- unless datafiles are to be restored to their default locations (see
3282 -- proxyRestoreDataFile). However, if the database is mounted, then records
3283 -- describing the restored files will be added to the currently mounted
3285 --
3286 -- Input Parameters
3287 -- destination
3288 -- This is used to construct the file name for creating restored
3289 -- archived logs. It is ignored when restoring datafiles. If not
3290 -- specified, the init.ora log_archive_dest parameter is used.
3291
3292 PROCEDURE proxyBackupDatafile(file# IN binary_integer, handle IN varchar2);
3293 PROCEDURE proxyBackupDatafileCopy(copy_recid IN number,
3294 copy_stamp IN number,
3295 handle IN varchar2);
3296 -- Specify one datafile or datafile copy to be backed up during a
3297 -- proxy copy session.
3298 --
3299 -- Input Parameters:
3300 -- file#
3301 -- the absolute file number of a datafile to be backed up.
3302 -- copy_recid
3303 -- copy_stamp
3304 -- the controlfile identifiers of a controlfile to be backed up.
3305 -- handle
3306 -- the filename of this backup in the media management catalog.
3307
3308 PROCEDURE proxyBackupControlfile(name IN varchar2 default NULL,
3309 handle IN varchar2);
3310
3311 -- Specify one controlfile to be backed up with proxy copy.
3312 --
3313 -- Input Parameters:
3314 -- name
3315 -- the name of a backup controlfile to back up. If NULL, the snapshot
3316 -- controlfile will be backed up.
3317 -- handle
3318 -- the filename of this backup in the media management catalog
3319
3320 PROCEDURE proxyBackupArchivedlog(arch_recid IN number,
3321 arch_stamp IN number,
3322 handle IN varchar2);
3323
3324 -- Specify one archived log to be backed up during a proxy copy session.
3325 -- Input Parameters:
3326 -- arch_recid
3327 -- arch_stamp
3328 -- the archivedlog identifiers of a log file to be backed up
3329 -- handle
3330 -- the filename of this backup in the media management catalog
3331
3332 PROCEDURE proxyRestoreDatafile(handle IN varchar2,
3333 file# IN binary_integer,
3334 toname IN varchar2 default NULL);
3335
3336 -- Specify one datafile to be restored during a proxy session. An
3337 -- exclusive access enqueue will be obtained for this file at this time,
3338 -- so that multiple restores of the same file can not run concurrently.
3339 --
3340 -- Input Parameters:
3341 -- handle
3342 -- the filename that was extracted from the v$proxy_datafile.handle
3343 -- column after this file was proxy backed up.
3344 -- file#
3345 -- the absolute file number of the file to be restored
3346 -- toname
3347 -- the OS file name to which the file should be restored. If this is
3348 -- null, then the file will be restored to the name indicated in the
3349 -- controlfile (and, in this case, the controlfile must be mounted).
3350
3351 PROCEDURE proxyRestoreControlfile(handle IN varchar2,
3352 toname IN varchar2);
3353
3354 -- Name a controlfile to be restored with proxy copy.
3355 --
3356 -- Input Parameters
3357 -- handle
3358 -- the filename that was extracted from the v$proxy_datafile.handle
3359 -- column after this file was proxy backed up.
3360 -- toname
3361 -- the OS file name to which the file should be restored.
3362 -- When passed as NULL and database is not mounted, we restore and
3363 -- replicate the controlfiles to all names that match current
3364 -- controlfiles in parameter file.
3365
3366
3367 PROCEDURE proxyRestoreArchivedlog(handle IN varchar2,
3368 thread IN binary_integer,
3369 sequence IN number);
3370
3371 -- Specify one archived log to be restored during a proxy session.
3372 --
3373 -- Input Parameters
3374 -- handle
3375 -- the filename that was extracted from the v$proxy_archivedlog.handle
3376 -- column after this file was proxy backed up.
3377 -- thread
3378 -- sequence
3379 -- these will be used in conjunction with the destination that was
3380 -- passed to proxyBeginRestore (or LOG_ARCHIVE_DEST, if that was not
3381 -- specified) to construct the file name to be restored.
3382
3383 PROCEDURE proxyGo;
3384
3385 -- Called after all the files have been named. Does not return until the
3386 -- proxy copy is complete. All of the data movement is performed here.
3387
3388 FUNCTION proxyQueryBackup(name in varchar2) return binary_integer;
3389 -- check to see if this file can be backed up using proxy copy:
3390
3391 FUNCTION proxyQueryRestore(handle IN varchar2,
3392 toname IN varchar2) return binary_integer;
3393 -- Determine if the indicated datafile can be restored from the specified
3394 -- proxy backup file.
3395 --
3396 -- proxyQueryBackup and proxyQueryRestore each return one of the
3397 -- following values, indicating whether the requested operation can be
3398 -- performed or not.
3399
3400 CAN_PROXY constant binary_integer := 0;
3401 CANNOT_PROXY constant binary_integer := 1;
3402
3403 PROCEDURE proxyCancel;
3404 -- End the proxy conversation. Note that this never stops an
3408 -- called.
3405 -- 'in-progress' backup, because proxyGo blocks until the proxy is
3406 -- complete. This procedure simply clears out the file list if some
3407 -- files have been named for backup or restore but proxyGo was never
3409
3410 PROCEDURE proxyDelete(recid IN number,
3411 stamp IN number,
3412 handle IN varchar2,
3413 params IN varchar2 default NULL);
3414 FUNCTION proxyValidate(recid IN number,
3415 stamp IN number,
3416 handle IN varchar2,
3417 params IN varchar2 default NULL)
3418 return binary_integer;
3419
3420 -- Change proxy backup status, delete from the storage subsystem, or
3421 -- validate that a proxy backup exists in the storage subsystem.
3422
3423 -- proxyValidate changes status in the controlfile to 'A' or 'X'
3424 -- appropriately. The media management catalog is not affected.
3425
3426 -- For proxyChange status=='D', if a controlfile record ID is given, it
3427 -- is marked obsolete so that it will no longer appear in V$PROXY_DATAFILE or
3428 -- V$PROXY_ARCHIVEDLOG. If the stamp in the record does not match the stamp
3429 -- argument, the controlfile record will not be marked as obsolete. The
3430 -- record is marked as obsolete before the OSD is called to do the delete.
3431 -- Thus a failure could result in the backup file continuing to exist while
3432 -- the controlfile record is marked obsolete.
3433
3434 -- A device must be allocated in order to specify the device type. It is
3435 -- acceptable for some device types to not allocate a specifically named
3436 -- device for deleting even though a specific device name is needed for
3437 -- other operations. This is indicated by setting the noio argument to TRUE
3438 -- for the deviceAllocate procedure.
3439 --
3440 -- Input parameters:
3441 -- recid
3442 -- stamp
3443 -- These are the key for the record in the controlfile where the
3444 -- information about the backup piece was recorded. This is the record
3445 -- that will be marked as obsolete. This will either be a record in
3446 -- v$proxy_datafile or v$proxy_archivedlog. Note that these two tables
3447 -- share the same recid space, because they are based on the same
3448 -- underlying controlfile record section (kccpc).
3449 -- handle
3450 -- The handle of the proxy backup to delete. This is only used if the
3451 -- recid/stamp are not found in the controlfile. This
3452 -- field also participates in validation - if the record
3453 -- identified by recid/stamp is found and the handle does not match the
3454 -- handle in that record, then an error is signalled.
3455 -- params
3456 -- This string is simply passed to the sequential file delete OSD. It is
3457 -- completely port and device specific.
3458
3459 PROCEDURE getMaxInfo(mlogf OUT binary_integer
3460 ,mlogm OUT binary_integer
3461 ,mdatf OUT binary_integer
3462 ,minst OUT binary_integer
3463 ,mlogh OUT binary_integer
3464 ,chset OUT varchar2);
3465 -- This procedure is used to obtain the max values for the parameters used
3466 -- in the create controlfile command. These values cannot be obtained
3467 -- from tables, as are only kept in the sga.
3468 --
3469 -- Input parameters:
3470 -- NONE
3471 --
3472 -- Output parameters:
3473 -- mlogf
3474 -- At end will contain the maximum number of logfiles
3475 -- mlogm
3476 -- At end will contain the maximum number of log members
3477 -- mdatf
3478 -- At end will contain the maximum number of datafiles
3479 -- minst
3480 -- At end will contain the maximum number of instances
3481 -- mlogh
3482 -- At end will contain the maximum number of log history
3483 -- chset
3484 -- At end will contain the character set of the database
3485
3486 PROCEDURE zeroDbid(fno IN binary_integer);
3487
3488 -- This procedure is used to update the header of a datafile so that the
3489 -- a new dbid would be calculated later on with a create controlfile
3490 -- statement. This is necessary for the cloning of a database
3491 -- The file to update is identified by the fno input parameter, a special
3492 -- case is allowed when fno == 0, such that all the headers of the datafiles
3493 -- in the control file are zeroed out.
3494 -- Three fields in the datafile header (stored in the first block)
3495 -- are zeroed out:
3496 -- The field that holds the database id
3497 -- The checksum field
3498 -- The bit that signals that the checksum is valid
3499 --
3500 -- There are no return values
3501 --
3502 -- Input parameters:
3503 -- fno
3504 -- Identifies the file number of the datafile that will be modified
3505 -- If it is zero, all datafiles listed in the controlfile are updated.
3506 -- Output parameters:
3507 -- NONE
3508
3509 FUNCTION validateTableSpace( tsid IN binary_integer
3510 ,cSCN IN number )
3511 RETURN binary_integer;
3512
3513 -- This procedure is used to validate that the tablespace has not
3514 -- been recreated when performing TSPITR. To that effect it receives
3515 -- the id of the tablespace and the minimum creation scn of the
3516 -- datafiles at the PIT for the tablespace.
3517 -- This creation scn is checked against the current value stored in
3521 --
3518 -- ts$, if the creation_scn is less than that value, it indicates
3519 -- that the TSPITR is trying to restore to a PIT before the recreation
3520 -- of the database, which is not allowed.
3522 -- Return values
3523 -- 0 if the tablespace has been recreated
3524 -- 1 if the tablespace was not recreated
3525 --
3526 -- Input parameters:
3527 -- tsid
3528 -- Id of the tablespace that is being TSPITRed
3529 -- cSCN
3530 -- Minimum creation SCN of all datafiles of the tablespace at
3531 -- the PIT of the TSPITR
3532 -- Output parameters:
3533 -- NONE
3534
3535 --
3536 -- Modified functions
3537 --
3538
3539 FUNCTION deviceAllocate( type IN varchar2 default NULL
3540 ,name IN varchar2 default NULL
3541 ,ident IN varchar2 default NULL
3542 ,noio IN boolean default FALSE
3543 ,params IN varchar2 default NULL
3544 ,node OUT varchar2
3545 ,dupcnt IN binary_integer
3546 ,trace IN binary_integer default 0)
3547 RETURN varchar2;
3548
3549
3550 --
3551 -- Description and return values can be found with original declaration
3552 -- above. The new arguments are:
3553 -- node
3554 -- The node where this channel is allocated. This is what ksxamn()
3555 -- returns.
3556 --
3557 -- In order to support duplexed channels we need new parameter to
3558 -- deviceAllocate.
3559 --
3560 -- dupcnt
3561 -- This number indicates how many copies of each backup piece should
3562 -- be made. Default is 1, and current maximum is 4.
3563 --
3564 -- trace
3565 -- This number is passed to the underlying media management software.
3566 -- Its meaning is defined by the MMS.
3567 --
3568
3569
3570
3571 --********************************************
3572 -- Backup Conversation Initiation Procedures--
3573 --*******************************************--
3574
3575 PROCEDURE backupSetDataFile( set_stamp OUT number
3576 ,set_count OUT number
3577 ,nochecksum IN boolean default FALSE
3578 ,tag IN varchar2 default NULL
3579 ,incremental IN boolean default FALSE
3580 ,backup_level IN binary_integer default 0
3581 ,check_logical IN boolean);
3582
3583 -- Description and return values can be found with original declaration
3584 -- above. New parameters
3585 --
3586 -- check_logical
3587 -- if set to true indicates that besides physical block validations,
3588 -- logical validations will be performed on each block
3589
3590
3591 PROCEDURE backupPieceCreate( fname IN varchar2
3592 ,pieceno OUT binary_integer
3593 ,done OUT boolean
3594 ,handle OUT varchar2
3595 ,comment OUT varchar2
3596 ,media OUT varchar2
3597 ,concur OUT boolean
3598 ,params IN varchar2 default NULL
3599 ,media_pool IN binary_integer);
3600 -- Description and return values can be found with original declaration
3601 -- above. New parameter:
3602 --
3603 -- media_pool
3604 -- a number from 0-255 whose meaning is defined by rman or by 3rd-party
3605 -- media management software.
3606
3607 PROCEDURE backupPieceCreate( fname IN varchar2
3608 ,pieceno OUT binary_integer
3609 ,done OUT boolean
3610 ,handle OUT varchar2
3611 ,comment OUT varchar2
3612 ,media OUT varchar2
3613 ,concur OUT boolean
3614 ,params IN varchar2 default NULL
3615 ,media_pool IN binary_integer default 0
3616 ,reuse IN boolean);
3617 -- Description and return values can be found with original declaration
3618 -- above. New parameter:
3619 --
3620 -- reuse
3621 -- indicates if the piece should be removed before creating it
3622
3623 PROCEDURE backupBackupPiece( bpname IN varchar2
3624 ,fname IN varchar2
3625 ,handle OUT varchar2
3626 ,comment OUT varchar2
3627 ,media OUT varchar2
3628 ,concur OUT boolean
3629 ,recid OUT number
3630 ,stamp OUT number
3631 ,tag IN varchar2 default NULL
3632 ,params IN varchar2 default NULL
3633 ,media_pool IN binary_integer default 0
3634 ,reuse IN boolean default FALSE
3635 ,check_logical IN boolean);
3636 -- Description and return values can be found with original declaration
3637 -- above. New parameters
3638 --
3639 -- check_logical
3640 -- if set to true indicates that besides physical block validations,
3644 ,fname IN varchar2
3641 -- logical validations will be performed on each block
3642
3643 PROCEDURE copyDataFile( dfnumber IN binary_integer
3645 ,full_name OUT varchar2
3646 ,recid OUT number
3647 ,stamp OUT number
3648 ,max_corrupt IN binary_integer default 0
3649 ,tag IN varchar2 default NULL
3650 ,nochecksum IN boolean default FALSE
3651 ,isbackup IN boolean default FALSE
3652 ,check_logical IN boolean);
3653 -- Description and return values can be found with original declaration
3654 -- above. New parameters
3655 --
3656 -- check_logical
3657 -- if set to true indicates that besides physical block validations,
3658 -- logical validations will be performed on each block
3659
3660
3661
3662
3663 PROCEDURE copyDataFileCopy( copy_recid IN number
3664 ,copy_stamp IN number
3665 ,full_name OUT varchar2
3666 ,recid OUT number
3667 ,stamp OUT number
3668 ,fname IN varchar2 default NULL
3669 ,max_corrupt IN binary_integer default 0
3670 ,tag IN varchar2 default NULL
3671 ,nochecksum IN boolean default FALSE
3672 ,isbackup IN boolean default FALSE
3673 ,check_logical IN boolean);
3674 -- Description and return values can be found with original declaration
3675 -- above. New parameters
3676 --
3677 -- check_logical
3678 -- if set to true indicates that besides physical block validations,
3679 -- logical validations will be performed on each block
3680
3681
3682
3683
3684 PROCEDURE restoreSetDataFile(check_logical IN boolean);
3685 -- Description and return values can be found with original declaration
3686 -- above. New parameters
3687 -- New parameters
3688 --
3689 -- check_logical
3690 -- if set to true indicates that besides physical block validations,
3691 -- logical validations will be performed on each block
3692
3693
3694
3695
3696
3697 PROCEDURE applySetDataFile(check_logical IN boolean);
3698 -- Description and return values can be found with original declaration
3699 -- above. New parameters
3700 -- New parameters
3701 --
3702 -- check_logical
3703 -- if set to true indicates that besides physical block validations,
3704 -- logical validations will be performed on each block
3705
3706
3707
3708
3709
3710 FUNCTION scanDataFile(dfnumber IN binary_integer,
3711 max_corrupt IN binary_integer default 0,
3712 update_fuzziness IN boolean default true,
3713 check_logical IN boolean)
3714 return number;
3715 -- Description and return values can be found with original declaration
3716 -- above. New parameters
3717 --
3718 -- check_logical
3719 -- if set to true indicates that besides physical block validations,
3720 -- logical validations will be performed on each block
3721
3722
3723
3724
3725
3726 FUNCTION scanDataFileCopy(recid IN number,
3727 stamp IN number,
3728 max_corrupt IN binary_integer default 0,
3729 isbackup IN boolean default FALSE,
3730 update_fuzziness IN boolean default true,
3731 check_logical IN boolean)
3732 return number;
3733 -- Description and return values can be found with original declaration
3734 -- above. New parameters
3735 --
3736 -- check_logical
3737 -- if set to true indicates that besides physical block validations,
3738 -- logical validations will be performed on each block
3739
3740
3741
3742
3743
3744 PROCEDURE restoreDataFileTo( dfnumber IN binary_integer
3745 ,toname IN varchar2 default NULL
3746 ,max_corrupt IN binary_integer);
3747 -- Description and return values can be found with original declaration
3748 -- above. New parameters
3749 --
3750 -- max_corrupt
3751 -- maximum number of corruptions allowed on datafile
3752
3753
3754
3755
3756 PROCEDURE applyDataFileTo( dfnumber IN binary_integer
3757 ,toname IN varchar2 default NULL
3758 ,fuzziness_hint IN number default 0
3759 ,max_corrupt IN binary_integer);
3760 -- Description and return values can be found with original declaration
3761 -- above. New parameters
3762 --
3763 -- max_corrupt
3764 -- maximum number of corruptions allowed on datafile
3765
3766 --
3767 -- NEW FUNCTIONS
3768 --
3769
3770 FUNCTION deviceQuery(question IN binary_integer) return varchar2;
3771
3772 DEVICEQUERY_VENDOR constant binary_integer := 0;
3773 DEVICEQUERY_PROXY constant binary_integer := 1;
3774 DEVICEQUERY_MAXSIZE constant binary_integer := 2;
3775 DEVICEQUERY_MAXPROXY constant binary_integer := 3;
3779 -- Request information about the device
3776 DEVICEQUERY_VENDORTYPE constant binary_integer := 4;
3777
3778
3780 -- Input parameters:
3781 -- question
3782 -- One of the above constants, which identifies the type of information
3783 -- desired.
3784 -- Returns:
3785 -- A character string containing the requested information:
3786 -- DEVICEQUERY_VENDOR
3787 -- For non-DISK devices, the vendor identification string.
3788 -- For DISK devices, NULL.
3789 -- DEVICEQUERY_PROXY
3790 -- "0": proxy copy is not supported.
3791 -- "1": proxy copy is supported.
3792 -- "2": proxy copy is supported, but can't be used because
3793 -- COMPATIBLE must be >= 8.1.0.
3794 -- DEVICEQUERY_MAXSIZE
3795 -- Maximum backup piece size, in kilobytes.
3796 -- Returns 0 if there is no size limit.
3797 -- DEVICEQUERY_MAXPROXY
3798 -- Maximum number of files which should be proxy copied
3799 -- in a single session.
3800 -- DEVICEQUERY_VENDORTYPE
3801 -- Type of SBT library, in case it is Oracle proprietary
3802 -- "1": Oracle Secure Backup.
3803 -- "2": HTTP SBT for ODBLRA.
3804 -- "3": OSBWS library.
3805 -- "4": Oracle library, using OSB as vendor description.
3806 -- See bug 6749185.
3807 --
3808 -- Exceptions:
3809 -- None
3810 --
3811 -- Values returned by deviceQuery
3812
3813 DEVICEQUERY_OSB constant binary_integer := 1;
3814 DEVICEQUERY_BA constant binary_integer := 2;
3815 DEVICEQUERY_AWS constant binary_integer := 3;
3816 DEVICEQUERY_OPC constant binary_integer := 4;
3817 DEVICEQUERY_DEF constant binary_integer := 5;
3818
3819 -- To allow for duplexed backup sets 2 new functions are used
3820 -- These functions are only used if actually having copies
3821 -- backupPieceCrtDupSet sets the name of the copy specified by copy_n
3822 -- into the device context for later usage
3823 -- backupPieceCrtDupGet gets the output information (media, handle and
3824 -- comment) for the copy specified by copy_n and places it in the
3825 -- output variables. This information is retrieved from the device
3826 -- context and was created when the piece/copy was created by
3827 -- backupPieceCreate
3828
3829 PROCEDURE backupPieceCrtDupSet( copy_n IN binary_integer
3830 ,fname IN varchar2);
3831 -- Input parameters:
3832 -- copy_n
3833 -- specifies the copy number that corresponds to the filename
3834 -- fname
3835 -- Filename of the copy of the backup piece to be created.
3836 -- This will be translated into a file handle after the piece is created.
3837 -- Exceptions:
3838 -- NAME-TOO-LONG (ora-19704)
3839 -- The specified backup piece name is longer than the port-specific
3840 -- maximum file name length.
3841
3842 PROCEDURE backupPieceCrtDupGet( copy_n IN binary_integer
3843 ,handle OUT varchar2
3844 ,comment OUT varchar2
3845 ,media OUT varchar2);
3846 -- Input parameters:
3847 -- copy_n
3848 -- specifies the copy number for which we want the information
3849 -- handle
3850 -- The handle for the backup piece that was created. This is a permanent
3851 -- name that can be used to read this sequential file for restore. It
3852 -- can only be used with the same device type that was allocated at
3853 -- this call.
3854 -- comment
3855 -- The comment for the backup piece. This is any string that the OSD
3856 -- decided was useful. It will be the null string for operating system
3857 -- files.
3858 -- media
3859 -- The media handle returned by the operating system. This is the name
3860 -- of media where the file was created. It is not needed for retrieving
3861 -- the backup piece. For some devices this information will not be
3862 -- provided.
3863
3864
3865 -- See description of deleteBackupPiece for documentation for
3866 -- changeBackupPiece. We have to put new functions at the end.
3867 PROCEDURE changeBackupPiece( recid IN number
3868 ,stamp IN number
3869 ,handle IN varchar2
3870 ,set_stamp IN number
3871 ,set_count IN number
3872 ,pieceno IN binary_integer
3873 ,status IN varchar2 -- 'D','S','A','U','X'
3874 ,params IN varchar2 default NULL );
3875 -- Additional input parameters:
3876 -- status:
3877 -- specifies the new status for this backup piece. These status codes
3878 -- mean the same in all of the xxxChange procedures.
3879 -- D: delete the piece from the media, and mark it deleted in the
3880 -- control file
3881 -- S: Same as D, except that the backup piece exists on device type
3882 -- DISK, regardless of what device type is currently allocated to
3883 -- this session.
3884 -- A: mark the piece in the controlfile as available, do not touch the
3885 -- piece on the media.
3886 -- U: mark the piece in the controlfile as unavailable, do not touch
3887 -- the piece on the media.
3888 -- X: mark the piece in the controlfile as expired, do not touch the
3889 -- piece on the media.
3890 --
3891 --
3892
3893 -- See description of proxyDelete for documentation for
3897 handle IN varchar2,
3894 -- proxyChange. Here we will explain just keep attributes.
3895 PROCEDURE proxyChange(recid IN number,
3896 stamp IN number,
3898 status IN varchar2, -- 'D','A','U','X'
3899 params IN varchar2 default NULL);
3900
3901 -- NOTE: crosscheckBackupPiece is obsolete
3902 -- See description of validateBackupPiece for documentation for
3903 -- crosscheckBackupPiece. We have to put new functions at the end.
3904 -- The main difference between crosscheck* and validate* is that
3905 -- crosscheck* modifies the status to reflect the discovered status
3906 -- of the file/piece.
3907 FUNCTION crosscheckBackupPiece(recid IN number
3908 ,stamp IN number
3909 ,handle IN varchar2
3910 ,set_stamp IN number
3911 ,set_count IN number
3912 ,pieceno IN binary_integer
3913 ,params IN varchar2 default NULL)
3914 return binary_integer;
3915
3916 PROCEDURE reNormalizeAllFileNames;
3917
3918 PROCEDURE cfileMakeAndUseSnapshot(isstby IN boolean);
3919 --
3920 -- See description above
3921 --
3922 -- New Input parameters:
3923 -- isstby
3924 -- If TRUE, indicates that the controlfile to make is a
3925 -- standby controlfile, normal backup otherwise
3926 --
3927
3928 --
3929 -- ADD NEW FUNCTIONS/PROCEDURES OR SIGNATURE CHANGES JUST BEFORE THIS LINE
3930 --
3931
3932
3933 -- backupValidate is called to perform a 'validation backup'. The backup
3934 -- proceeds as normal WRT the input files, but no backup piece is created.
3935 -- The backup conversation must already have been started, and this function
3936 -- is called in place of backupPieceCreate.
3937 PROCEDURE backupValidate;
3938
3939 -- genPieceName is called to produce the name of the piece. It receives
3940 -- a format and various other information to produce a name of the piece
3941 -- as described by the format
3942
3943 FUNCTION genPieceName(pno IN number
3944 ,set_count IN number
3945 ,set_stamp IN number
3946 ,format IN varchar2
3947 ,copyno IN number
3948 ,devtype IN varchar2
3949 ,year IN varchar2
3950 ,month IN varchar2
3951 ,day IN varchar2
3952 ,dbid IN varchar2
3953 ,ndbname IN varchar2
3954 ,pdbname IN varchar2
3955 ,cfseq IN number)
3956 return varchar2;
3957 -- Input parameters:
3958 -- pno
3959 -- Piece number within backup set.
3960 -- set_stamp
3961 -- set_count
3962 -- Backup set identification.
3963 -- format
3964 -- Piece format
3965 -- copyno
3966 -- Copy number for the piece
3967 -- devtype
3968 -- Device type where the piece will be created
3969 -- year
3970 -- Gregorian year when the piece is created
3971 -- month
3972 -- Gregorian month when the piece is created
3973 -- day
3974 -- Gregorian day of the monthe when the piece is created
3975 -- dbid
3976 -- Database identifier
3977 -- ndbname
3978 -- Database name
3979 -- pdbname
3980 -- Padded database name
3981 -- cfseq
3982 -- Controlfile sequence
3983
3984
3985 PROCEDURE backupPieceCreate( fname IN varchar2
3986 ,pieceno OUT binary_integer
3987 ,done OUT boolean
3988 ,handle OUT varchar2
3989 ,comment OUT varchar2
3990 ,media OUT varchar2
3991 ,concur OUT boolean
3992 ,params IN varchar2 default NULL
3993 ,sequence IN binary_integer
3994 ,year IN binary_integer
3995 ,month_day IN binary_integer);
3996
3997 PROCEDURE backupPieceCreate( fname IN varchar2
3998 ,pieceno OUT binary_integer
3999 ,done OUT boolean
4000 ,handle OUT varchar2
4001 ,comment OUT varchar2
4002 ,media OUT varchar2
4003 ,concur OUT boolean
4004 ,params IN varchar2 default NULL
4005 ,media_pool IN binary_integer
4006 ,sequence IN binary_integer
4007 ,year IN binary_integer
4008 ,month_day IN binary_integer);
4009
4010 PROCEDURE backupPieceCreate( fname IN varchar2
4011 ,pieceno OUT binary_integer
4012 ,done OUT boolean
4013 ,handle OUT varchar2
4014 ,comment OUT varchar2
4015 ,media OUT varchar2
4016 ,concur OUT boolean
4020 ,sequence IN binary_integer
4017 ,params IN varchar2 default NULL
4018 ,media_pool IN binary_integer default 0
4019 ,reuse IN boolean
4021 ,year IN binary_integer
4022 ,month_day IN binary_integer);
4023 -- Description and return values can be found with original declaration
4024 -- above. New parameter:
4025 --
4026 -- sequence
4027 -- indicates the sequence for the controlfile autobackup
4028 --
4029 -- year
4030 -- indicates the year for the controlfile autobackup
4031 --
4032 -- day
4033 -- indicates the month-day for the controlfile autobackup
4034
4035
4036 FUNCTION setConfig (name IN varchar2,
4037 value IN varchar2 default NULL)
4038 RETURN binary_integer;
4039
4040 -- setConfig is called to perform a saving of configuration parameters.
4041 -- This procedure sets the Rman configuration.
4042 --
4043 -- Input parameters:
4044 -- name
4045 -- Text which is going to be stored in the first column of
4046 -- the configuration record. It can not be NULL.
4047 -- value
4048 -- Text which is going to be stored in the second column of
4049 -- the configuration record. It can be NULL.
4050 --
4051 -- Return parameters:
4052 -- conf#
4053 -- Configuration number (in fact, row number) for configuration.
4054 --
4055 -- Exceptions:
4056 -- DATABASE-NOT-MOUNTED (ora-1507)
4057 -- The database is not mounted.
4058 -- RMAN-CONF-NAME-TOO-LONG (ora-19677)
4059 -- Name of the configuration value is too long to
4060 -- fit in the control file.
4061 -- RMAN-CONF-VALUE-TOO-LONG (ora-19678)
4062 -- Configuration value specified is too long to fint in control file.
4063
4064 PROCEDURE resetConfig;
4065
4066 -- resetConfig is called to perform a deleting of all rman configurations.
4067 --
4068 -- Exceptions:
4069 -- DATABASE-NOT-MOUNTED (ora-1507)
4070 -- The database is not mounted.
4071
4072 PROCEDURE deleteConfig (conf# IN binary_integer);
4073
4074 -- deleteConfig is called to perform a deleting of RMAN Configuration.
4075 -- This procedure deletes the Rman configuration(s).
4076 --
4077 -- Input parameters:
4078 -- conf#
4079 -- Configuration number which we want to delete.
4080 --
4081 -- Exceptions:
4082 -- DATABASE-NOT-MOUNTED (ora-1507)
4083 -- The database is not mounted.
4084 -- INVALID-CONF-RECORD (ora-19679)
4085 -- Invalid configuration record.
4086
4087
4088 PROCEDURE setDatafileAux( dfnumber IN binary_integer
4089 ,fname IN varchar2 DEFAULT NULL);
4090
4091 -- setDbfileAux sets auxilary filename.
4092 --
4093 -- Input parameters:
4094 -- dfnumber
4095 -- Data file number of a file to alter. This refers to the file that
4096 -- is currently accessible via SQL commands.
4097 -- fname
4098 -- Name of the file to be set as auxfilename.
4099 --
4100 -- Exceptions:
4101 -- DATABASE-NOT-MOUNTED (ora-1507)
4102 -- The database is not mounted.
4103 -- NAME-TOO-LONG (ora-19704)
4104 -- The specified name is longer than the port-specific
4105 -- maximum file name length.
4106 -- FILE-IN-USE (ora-19584)
4107 -- The specified output file is already in use by the database as a
4108 -- datafile, online redo log or auxname for some other file.
4109
4110
4111 PROCEDURE setTablespaceExclude( tsid IN binary_integer
4112 ,flag IN binary_integer);
4113
4114 -- setTablespaceExclude sets tablespace "excluded from backup" flag
4115 --
4116 -- Input parameters:
4117 -- tsid
4118 -- Id of the tablespace that is being altered
4119 -- flag
4120 -- if equal to zero then set "excluded from backup" to NO
4121 -- if equal to one then set "excluded from backup" to YES
4122 --
4123 -- Exceptions:
4124 -- DATABASE-NOT-MOUNTED (ora-1507)
4125 -- The database is not mounted.
4126 --
4127
4128
4129 -- This procedure has same arguments as backupsetArchivedLog. Additional
4130 -- argument tag is added to support tags for archivelog backups
4131 PROCEDURE backupSetArchivedLog( set_stamp OUT number
4132 ,set_count OUT number
4133 ,nochecksum IN boolean default FALSE
4134 ,tag IN varchar2);
4135
4136 PROCEDURE backupBackupPiece( bpname IN varchar2
4137 ,fname IN varchar2
4138 ,handle OUT varchar2
4139 ,comment OUT varchar2
4140 ,media OUT varchar2
4141 ,concur OUT boolean
4142 ,recid OUT number
4143 ,stamp OUT number
4144 ,tag IN varchar2 default NULL
4145 ,params IN varchar2 default NULL
4146 ,media_pool IN binary_integer default 0
4147 ,reuse IN boolean default FALSE
4151 -- above. New parameters
4148 ,check_logical IN boolean
4149 ,copyno IN binary_integer );
4150 -- Description and return values can be found with original declaration
4152 --
4153 -- copyno
4154 -- Record the backup piece copied in x$kccbp as this copy number
4155 --
4156
4157 --
4158 -- bmr procedures and functions
4159 --
4160 -- bmrStart starts a bmr conversation
4161 PROCEDURE bmrStart( save_all_blocks IN boolean,
4162 save_final_blocks IN boolean,
4163 nofileupdate IN boolean);
4164
4165 -- bmrCancel ends/cancels previously started conversation
4166 PROCEDURE bmrCancel;
4167
4168 -- bmrAddBlock add each block in the range (starting from blknumber)
4169 -- to the bmr context
4170 PROCEDURE bmrAddBlock( dfnumber IN binary_integer,
4171 blknumber IN binary_integer,
4172 range IN binary_integer DEFAULT 1 );
4173
4174 -- bmrIntialScan scans for newed blocks and eliminates the one in block list
4175 PROCEDURE bmrInitialScan;
4176
4177 -- bmrGetFile returns file number for which blocks are to be restored
4178 FUNCTION bmrGetFile( firstcall IN boolean )
4179 return number;
4180
4181 -- dba2rfno translates DBA number to block# and relative_file#
4182 PROCEDURE dba2rfno( dbano IN number,
4183 rfno OUT number,
4184 blockno OUT number );
4185
4186 -- This procedure is called to copy blocks from datafilecopy.
4187 PROCEDURE bmrScanDataFileCopy(recid IN number,
4188 stamp IN number);
4189 -- This procedure is called to recover after bmr is setup
4190 PROCEDURE bmrDoMediaRecovery(alname IN varchar2);
4191
4192 PROCEDURE changeDataFileCopy( recid IN number
4193 ,stamp IN number
4194 ,fname IN varchar2
4195 ,dfnumber IN binary_integer
4196 ,resetlogs_change IN number
4197 ,creation_change IN number
4198 ,checkpoint_change IN number
4199 ,blksize IN number
4200 ,new_status IN varchar2 );
4201
4202 PROCEDURE changeArchivedLog(recid IN number
4203 ,stamp IN number
4204 ,fname IN varchar2
4205 ,thread IN number
4206 ,sequence IN number
4207 ,resetlogs_change IN number
4208 ,first_change IN number
4209 ,blksize IN number
4210 ,new_status IN varchar2 );
4211
4212 PROCEDURE backupSetDataFile( set_stamp OUT number
4213 ,set_count OUT number
4214 ,nochecksum IN boolean default FALSE
4215 ,tag IN varchar2 default NULL
4216 ,incremental IN boolean default FALSE
4217 ,backup_level IN binary_integer default 0
4218 ,check_logical IN boolean default FALSE
4219 ,keep_options IN binary_integer
4220 ,keep_until IN number);
4221 -- Description and return values can be found with original declaration
4222 -- above. New parameters
4223 --
4224 -- keep_options
4225 -- if set to non zero than this is one of the following keep backups:
4226 -- 0x0100 - RECOVERABLE
4227 -- 0x0200 - UNRECOVERABLE
4228 -- 0x0400 - CONSISTENT
4229 -- keep_until
4230 -- this option is valid only if keep_option is non zero
4231 -- 0 - forever
4232 -- >0 - time when this backup will expire
4233
4234
4235 PROCEDURE copyDataFile( dfnumber IN binary_integer
4236 ,fname IN varchar2
4237 ,full_name OUT varchar2
4238 ,recid OUT number
4239 ,stamp OUT number
4240 ,max_corrupt IN binary_integer default 0
4241 ,tag IN varchar2 default NULL
4242 ,nochecksum IN boolean default FALSE
4243 ,isbackup IN boolean default FALSE
4244 ,check_logical IN boolean default FALSE
4245 ,keep_options IN binary_integer
4246 ,keep_until IN number);
4247 -- Description and return values can be found with original declaration
4248 -- above. New parameters
4249 --
4250 -- keep_options
4251 -- if set to non zero than this is one of the following keep backups:
4252 -- 0x0100 - RECOVERABLE
4253 -- 0x0200 - UNRECOVERABLE
4254 -- 0x0400 - CONSISTENT
4255 -- keep_until
4256 -- this option is valid only if keep_option is non zero
4257 -- 0 - forever
4258 -- >0 - time when this backup will expire
4259
4260
4261
4262 PROCEDURE copyDataFileCopy( copy_recid IN number
4263 ,copy_stamp IN number
4267 ,fname IN varchar2 default NULL
4264 ,full_name OUT varchar2
4265 ,recid OUT number
4266 ,stamp OUT number
4268 ,max_corrupt IN binary_integer default 0
4269 ,tag IN varchar2 default NULL
4270 ,nochecksum IN boolean default FALSE
4271 ,isbackup IN boolean default FALSE
4272 ,check_logical IN boolean default FALSE
4273 ,keep_options IN binary_integer
4274 ,keep_until IN number);
4275 -- Description and return values can be found with original declaration
4276 -- above. New parameters
4277 --
4278 -- keep_options
4279 -- if set to non zero than this is one of the following keep backups:
4280 -- 0x0100 - RECOVERABLE
4281 -- 0x0200 - UNRECOVERABLE
4282 -- 0x0400 - CONSISTENT
4283 -- keep_until
4284 -- this option is valid only if keep_option is non zero
4285 -- 0 - forever
4286 -- >0 - time when this backup will expire
4287
4288 PROCEDURE proxyBeginBackup( tag IN varchar2 default NULL
4289 ,incremental IN boolean default FALSE
4290 ,media_pool IN binary_integer default 0
4291 ,set_stamp OUT number
4292 ,set_count OUT number
4293 ,keep_options IN binary_integer
4294 ,keep_until IN number );
4295 -- Description and return values can be found with original declaration
4296 -- above. New parameters
4297 --
4298 -- keep_options
4299 -- if set to non zero than this is one of the following keep backups:
4300 -- 0x0100 - RECOVERABLE
4301 -- 0x0200 - UNRECOVERABLE
4302 -- 0x0400 - CONSISTENT
4303 -- keep_until
4304 -- this option is valid only if keep_option is non zero
4305 -- 0 - forever
4306 -- >0 - time when this backup will expire
4307
4308
4309
4310 PROCEDURE proxyChange( recid IN number
4311 ,stamp IN number
4312 ,handle IN varchar2
4313 ,status IN varchar2 -- 'D','A','U','X','K'
4314 ,params IN varchar2 default NULL
4315 ,keep_options IN binary_integer
4316 ,keep_until IN number);
4317 -- Description and return values can be found with original declaration
4318 -- above. New parameters
4319 --
4320 -- keep_options
4321 -- 0x0000 - No keep
4322 -- 0x0100 - RECOVERABLE
4323 -- 0x0200 - UNRECOVERABLE
4324 -- 0x0400 - CONSISTENT
4325 -- keep_until
4326 -- 0 - forever
4327 -- >0 - time when this backup will expire
4328 --
4329
4330 PROCEDURE changeBackupSet( recid IN number
4331 ,stamp IN number
4332 ,set_count IN number
4333 ,keep_options IN binary_integer
4334 ,keep_until IN number );
4335 --
4336 -- Input parameters:
4337 -- recid
4338 -- stamp
4339 -- These are the key for the record in the controlfile where the
4340 -- information about the backup awr was recorded. This is the record
4341 -- count
4342 -- keep_options
4343 -- 0 - No keep
4344 -- 0x0100 - KRMIKEEP_RCVBL
4345 -- 0x0200 - KRMIKEEP_UNRECOV
4346 --- 0x0400 - KRMIKEEP_CONSIST
4347 -- keep_until
4348 -- 0 - forever
4349 -- >0 - time when this backup will expire
4350 --
4351 -- Exceptions:
4352 -- DATABASE-NOT-MOUNTED (ora-1507)
4353 -- The database is not mounted.
4354 -- RECOVERY-CATALOG-ERROR (ora-19633)
4355 -- The validation information passed to this function is out of sync
4356 -- with the information in the controlfile.
4357
4358
4359 PROCEDURE changeDataFileCopy( recid IN number
4360 ,stamp IN number
4361 ,fname IN varchar2
4362 ,dfnumber IN binary_integer
4363 ,resetlogs_change IN number
4364 ,creation_change IN number
4365 ,checkpoint_change IN number
4366 ,blksize IN number
4367 ,new_status IN varchar2
4368 ,keep_options IN binary_integer
4369 ,keep_until IN number );
4370 -- Description and return values can be found with original declaration
4371 -- above. New parameters
4372 --
4373 -- keep_options
4374 -- 0x0000 - No keep
4375 -- 0x0100 - RECOVERABLE
4376 -- 0x0200 - UNRECOVERABLE
4377 -- 0x0400 - CONSISTENT
4378 -- keep_until
4379 -- 0 - forever
4380 -- >0 - time when this backup will expire
4381 --
4382
4383 PROCEDURE incrArchivedLogBackupCount(
4387 ,first_change OUT number
4384 fname IN varchar2
4385 ,thread OUT number
4386 ,sequence OUT number
4388 ,all_logs IN boolean default TRUE );
4389 -- This procedure is called to increment BACKUP_COUNT column
4390 -- in V$ARCHIVED_LOG.
4391 --
4392 -- Input parameters:
4393 -- fname
4394 -- The name of archived log.
4395 -- all_logs
4396 -- If this value is TRUE, backup_count of all records corresponding
4397 -- to logseq, thread, and resetlogs_change of input archived log
4398 -- will be incremented.
4399 -- If this value is FALSE, backup_count of one record that matches
4400 -- input arhived log fname will be incremented.
4401 -- Output parameters:
4402 -- thread
4403 -- Log thread number.
4404 -- sequence
4405 -- Log sequence number.
4406 -- first_change
4407 -- Low SCN.
4408 -- Exceptions:
4409 -- DATABASE-NOT-MOUNTED (ora-1507)
4410 -- The database is not mounted.
4411 -- FNAME-NOT-SPECIFIED (ora-19634)
4412 -- The fname must be specified and may not be null.
4413 -- ARCHIVELOG-NOT-FOUND (ora-19579)
4414 -- Archivedlog corresponding to given fname not found in controlfile.
4415 -- DIFFERENT_RESETLOGS (ora-19658)
4416 -- The file is not valid archived log for this database.
4417 -- FILE-NOT-FOUND (ora-19625)
4418 -- Error identifying archived log.
4419 -- ARCHIVELOG-VALIDATE-ERROR (ora-19582)
4420 -- Error reading archvied log.
4421
4422 PROCEDURE backupArchivedLog( arch_recid IN number
4423 ,arch_stamp IN number
4424 ,duplicate OUT boolean);
4425
4426 PROCEDURE getOMFFileName(tsname IN varchar2
4427 ,omfname OUT varchar2);
4428
4429 -- This procedure returns an OMF file name for a datafile in the given
4430 -- tablespace. The name is suitable for passing to create. The name
4431 -- will have a "%u" in it, which will get replaced when the file is created.
4432 --
4433 -- Input parameters:
4434 -- tsname
4435 -- The name of the file's tablespace.
4436 -- Output parameters:
4437 -- omfname
4438 -- An OMF file name template for a datafile in the given
4439 -- tablespace.
4440 -- Exceptions:
4441
4442 PROCEDURE inspectArchivedLogSeq( log_dest IN varchar2
4443 ,format IN varchar2 DEFAULT NULL
4444 ,thread IN binary_integer
4445 ,sequence IN number
4446 ,full_name OUT varchar2 );
4447
4448 -- This procedure is similar to inspectArchivedLogSeq in functionality
4449 -- except filename to be inspected (fname) is generated from
4450 -- LOG_ARCHIVE_DEST(log_dest), thread and sequence.
4451 --
4452 -- Input parameters:
4453 -- log_dest
4454 -- One of LOG_ARCHIVE_DEST format. This format together with thread
4455 -- and sequence generates name of logfile to be inspected.
4456 -- format
4457 -- format to be combined with log_dest. If format is NULL, then current
4458 -- instance format is used.
4459 -- thread
4460 -- Thread of archived log.
4461 -- sequence
4462 -- sequence of archived log.
4463 --
4464 -- Output parameters:
4465 -- full_name
4466 -- This is the fully expanded name of the file that was inspected. It
4467 -- will also appear in V$ARCHIVED_LOG.
4468 --
4469
4470 PROCEDURE backupPieceCreate( fname IN varchar2
4471 ,pieceno OUT binary_integer
4472 ,done OUT boolean
4473 ,handle OUT varchar2
4474 ,comment OUT varchar2
4475 ,media OUT varchar2
4476 ,concur OUT boolean
4477 ,params IN varchar2 default NULL
4478 ,media_pool IN binary_integer default 0
4479 ,reuse IN boolean default FALSE
4480 ,sequence IN binary_integer
4481 ,year IN binary_integer
4482 ,month_day IN binary_integer
4483 ,archlog_failover OUT boolean);
4484 -- Description and return values can be found with original declaration
4485 -- above. New parameter:
4486 --
4487 -- archlog_failover
4488 -- indicates if server did archivelog failover, user needs to look
4489 -- at alert log for further infomation on corrupted blocks and failover
4490 -- details.
4491
4492 PROCEDURE backupValidate(archlog_failover OUT boolean);
4493 -- Description and return values can be found with original declaration
4494 -- above. New parameter:
4495 --
4496 -- archlog_failover
4497 -- indicates if server did archivelog failover, user needs to look
4498 -- at alert log for further infomation on corrupted blocks and failover
4499 -- details.
4500
4501 FUNCTION validateDataFileCopy(recid IN number
4502 ,stamp IN number
4503 ,fname IN varchar2
4504 ,dfnumber IN binary_integer
4508 ,checkpoint_time IN OUT binary_integer
4505 ,resetlogs_change IN number
4506 ,creation_change IN number
4507 ,checkpoint_change IN OUT number
4509 ,blksize IN number
4510 ,signal IN binary_integer)
4511 return binary_integer;
4512
4513 -- Description and return values can be found with original declaration
4514 -- above. New parameter:
4515 --
4516 -- checkpoint_time
4517 -- Input and output parameter with time when checkpoint was done.
4518 -- signal
4519 -- Ignore catalog delete ignorable error (see krbcdie) if zero,
4520 -- otherwise signal exceptions.
4521 --
4522 -- NOTE: The arguments checkpoint_time and checkpoint_change are both
4523 -- input and output.
4524 --
4525
4526 FUNCTION convertFileName(fname IN varchar2,
4527 ftype IN binary_integer) return varchar2;
4528 -- Converts a filename with the appropiate conversion pattern
4529 -- If there's no conversion, the function returns NULL
4530 --
4531 -- Input parameters
4532 -- fname - Filename to convert
4533 -- ftype - Type of filename, 1 for Datafiles, 2 for Logfiles
4534 --
4535 -- Return value
4536 -- NULL if no conversion
4537 -- Otherwise converted name
4538
4539 PROCEDURE copyControlFile( src_name IN varchar2
4540 ,dest_name IN varchar2
4541 ,recid OUT number
4542 ,stamp OUT number
4543 ,full_name OUT varchar2
4544 ,keep_options IN binary_integer
4545 ,keep_until IN number);
4546
4547 -- Description and return values can be found with original declaration
4548 -- above. New parameters
4549 --
4550 -- keep_options
4551 -- if set to non zero, then this is one of the following keep backups:
4552 -- 0x0100 - RECOVERABLE
4553 -- 0x0200 - UNRECOVERABLE
4554 -- 0x0400 - CONSISTENT
4555 -- keep_until
4556 -- this option is valid only if keep_option is non zero
4557 -- 0 - forever
4558 -- >0 - time when this backup will expire
4559
4560 PROCEDURE backupSpfile;
4561
4562 -- Include the current SPFILE in the backup set.
4563 --
4564 -- Input parameters:
4565 --- NONE
4566 -- Exceptions:
4567 -- CONVERSATION-NOT-ACTIVE (ora-19580)
4568 -- A backup conversation was not started before specifying files.
4569 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
4570 -- The database is in the process of being opened, closed, mounted,
4571 -- or dismounted.
4572 -- DATABASE-NOT-MOUNTED (ora-1507)
4573 -- The database is not mounted.
4574 -- WRONG-CONVERSATION-TYPE (ora-19592)
4575 -- The backup set is not for datafiles, controlfiles and SPFILE.
4576 -- NAMING-PHASE-OVER (ora-19604)
4577 -- backuppiececreate has already been called. No files can be named
4578 -- after piececreate is called.
4579 -- DUPLICATE-SPFILE (ora-19596)
4580 -- The SPFILE has already been specified for backup.
4581 -- NO-SPFILE (ora-19598)
4582 -- The database was not started with SPFILE, so we cannot back up it.
4583 -- RETRYABLE-ERROR (ora-19624)
4584 -- This is a pseudo-error that is placed on top of the stack when an
4585 -- error is signalled but it may be possible to continue the
4586 -- conversation.
4587
4588 PROCEDURE restoreSpfileTo( pfname IN varchar2 default NULL
4589 ,sfname IN varchar2 default NULL);
4590
4591 -- This copies the SPFILE from the backup set to an operating system
4592 -- file.
4593 --
4594 -- Input parameters:
4595 -- pfname
4596 -- Name of the pfile to create or overwrite with the SPFILE data from the
4597 -- backup set. If NULL, then then we will not create the pfile.
4598 -- sfname
4599 -- Name of the SPFILE file to create or overwrite with the SPFILE from
4600 -- the backup set. If NULL, then the file will be restored to the same
4601 -- location from where was backed up.
4602 -- Exceptions:
4603 -- NAME-TOO-LONG (ora-19704)
4604 -- The specified file name is longer than the port-specific
4605 -- maximum file name length.
4606 -- CONVERSATION-NOT-ACTIVE (ora-19580)
4607 -- A restore conversation was not started before specifying files.
4608 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
4609 -- The database is in the process of being opened, closed, mounted,
4610 -- or dismounted.
4611 -- WRONG-CONVERSATION-TYPE (ora-19592)
4612 -- This restore conversation is not for datafiles, controlfiles,
4613 -- and SPFILE.
4614 -- CONVERSATION-IS-VALIDATE-ONLY (ora-19618)
4615 -- No files can be named after restoreValidate has been called.
4616 -- NAMING-PHASE-OVER (ora-19604)
4617 -- The first backup piece has been restored. No more files can be
4618 -- named.
4619 -- SPFILE-IS-ACTIVE (ora-32011)
4620 -- The destination file is the same as the SPFILE specified
4621 -- currently used.
4622
4623 PROCEDURE deleteBackupPiece( recid IN number
4624 ,stamp IN number
4625 ,handle IN varchar2
4626 ,set_stamp IN number
4630 ,force IN binary_integer);
4627 ,set_count IN number
4628 ,pieceno IN binary_integer
4629 ,params IN varchar2 default NULL
4631 -- Additional input parameters:
4632 -- force
4633 -- Flag to allow errors to be ignored
4634
4635 PROCEDURE changeBackupPiece( recid IN number
4636 ,stamp IN number
4637 ,handle IN varchar2
4638 ,set_stamp IN number
4639 ,set_count IN number
4640 ,pieceno IN binary_integer
4641 ,status IN varchar2 -- 'D','S','A','U','X'
4642 ,params IN varchar2 default NULL
4643 ,force IN binary_integer );
4644 -- Additional input parameters:
4645 -- force
4646 -- Flag to allow errors to be ignored
4647
4648 PROCEDURE changeDataFileCopy( recid IN number
4649 ,stamp IN number
4650 ,fname IN varchar2
4651 ,dfnumber IN binary_integer
4652 ,resetlogs_change IN number
4653 ,creation_change IN number
4654 ,checkpoint_change IN number
4655 ,blksize IN number
4656 ,new_status IN varchar2
4657 ,keep_options IN binary_integer
4658 ,keep_until IN number
4659 ,force IN binary_integer);
4660 -- Description and return values can be found with original and
4661 -- modified declaration above. New parameters
4662 --
4663 -- force
4664 -- Flag to allow errors to be ignored
4665 --
4666
4667 PROCEDURE deleteDataFileCopy( recid IN number
4668 ,stamp IN number
4669 ,fname IN varchar2
4670 ,dfnumber IN binary_integer
4671 ,resetlogs_change IN number
4672 ,creation_change IN number
4673 ,checkpoint_change IN number
4674 ,blksize IN number
4675 ,no_delete IN binary_integer
4676 ,force IN binary_integer);
4677 -- Description and return values can be found with original and
4678 -- modified declaration above. New parameters
4679 --
4680 -- force
4681 -- Flag to allow errors to be ignored
4682 --
4683
4684 PROCEDURE changeArchivedLog(recid IN number
4685 ,stamp IN number
4686 ,fname IN varchar2
4687 ,thread IN number
4688 ,sequence IN number
4689 ,resetlogs_change IN number
4690 ,first_change IN number
4691 ,blksize IN number
4692 ,new_status IN varchar2
4693 ,force IN binary_integer );
4694 -- Description and return values can be found with original and
4695 -- modified declaration above. New parameters
4696 --
4697 -- force
4698 -- Flag to allow errors to be ignored
4699 --
4700
4701 PROCEDURE deleteArchivedLog(recid IN number
4702 ,stamp IN number
4703 ,fname IN varchar2
4704 ,thread IN number
4705 ,sequence IN number
4706 ,resetlogs_change IN number
4707 ,first_change IN number
4708 ,blksize IN number
4709 ,force IN binary_integer );
4710 -- Description and return values can be found with original and
4711 -- modified declaration above. New parameters
4712 --
4713 -- force
4714 -- Flag to allow errors to be ignored
4715 --
4716
4717 PROCEDURE proxyChange( recid IN number
4718 ,stamp IN number
4719 ,handle IN varchar2
4720 ,status IN varchar2 -- 'D','A','U','X','K'
4721 ,params IN varchar2 default NULL
4722 ,keep_options IN binary_integer
4723 ,keep_until IN number
4724 ,force IN binary_integer);
4725 -- Description and return values can be found with original declaration
4726 -- above. New parameters
4727 --
4728 -- force
4729 -- Flag to allow errors to be ignored
4730 --
4731
4732 PROCEDURE proxyDelete(recid IN number,
4733 stamp IN number,
4734 handle IN varchar2,
4735 params IN varchar2 default NULL,
4736 force IN binary_integer);
4737 -- Description and return values can be found with original declaration
4741 -- Flag to allow errors to be ignored
4738 -- above. New parameters
4739 --
4740 -- force
4742 --
4743
4744 FUNCTION proxyValonly(recid IN number,
4745 stamp IN number,
4746 handle IN varchar2,
4747 params IN varchar2 default NULL)
4748 return binary_integer;
4749
4750 -- Same as proxyValidate, except that it does not change the status in
4751 -- the controlfile, it just validates.
4752
4753 FUNCTION validateBackupPiece(recid IN number
4754 ,stamp IN number
4755 ,handle IN varchar2
4756 ,set_stamp IN number
4757 ,set_count IN number
4758 ,pieceno IN binary_integer
4759 ,params IN varchar2 default NULL
4760 ,hdl_isdisk IN binary_integer)
4761 return binary_integer;
4762 -- Description and return values can be found with original declaration
4763 -- above. New parameters
4764 --
4765 -- hdl_isdisk
4766 -- TRUE if the backuppiece is from device disk. Used to dynamically
4767 -- allocate a disk context in SBT channel
4768 --
4769
4770 PROCEDURE DoAutoBackup(ncopies OUT binary_integer
4771 ,cfaudate IN DATE default NULL
4772 ,seq IN binary_integer default NULL
4773 ,format IN varchar2 default NULL);
4774 --
4775 -- Generate an Auto backup if autobackup is enabled. If no channel is
4776 -- allocated, a copy of autobackup will be written in controlfile
4777 -- autoformat to disk. Autobackup will contain spfile if instance is started
4778 -- using an server parameter file.
4779 --
4780 -- If connection has already a channel allocated, all attributes of
4781 -- channels like maxopenfiles, rate, etc., except dupcnt, maxpiecesize apply.
4782 --
4783 -- It will always generate one copy of autobackup to disk. If this procedure
4784 -- is executed with tape channel allocated, it generates as many copies as
4785 -- dupcnt. Maxpiecesize is always ignored and assumed to be not set, so
4786 -- that only one backuppiece contains entire backup set.
4787
4788 PROCEDURE AutobackupFlag(flag IN boolean);
4789 -- Above procedure turns OFF/ON Server tracking flag for generating
4790 -- autobackups on structural changes. By default this flag is TRUE;
4791 -- which means server will perform autobackups on structural changes
4792 -- if CONTROLFILE AUTOBACKUP configuration was turned ON.
4793 --
4794 -- This flag will be set to FALSE by RMAN whenever we don't want to generate
4795 -- autobackups on database structural change using ALTER DATABASE or ALTER
4796 -- TABLESPACE commands like during TSPITR.
4797
4798 FUNCTION validateDataFileCopy(recid IN number
4799 ,stamp IN number
4800 ,fname IN varchar2
4801 ,dfnumber IN binary_integer
4802 ,resetlogs_change IN number
4803 ,creation_change IN number
4804 ,checkpoint_change IN number
4805 ,blksize IN number
4806 ,signal IN binary_integer)
4807 return binary_integer;
4808 -- Description and return values can be found with original declaration
4809 -- above. New parameter:
4810 --
4811 -- signal
4812 -- Ignore catalog delete ignorable error (see krbcdie) if zero,
4813 -- otherwise signal exceptions.
4814 --
4815
4816
4817 FUNCTION validateArchivedLog(recid IN number
4818 ,stamp IN number
4819 ,fname IN varchar2
4820 ,thread IN number
4821 ,sequence IN number
4822 ,resetlogs_change IN number
4823 ,first_change IN number
4824 ,blksize IN number
4825 ,signal IN binary_integer)
4826 return binary_integer;
4827 -- Description and return values can be found with original declaration
4828 -- above. New parameter:
4829 --
4830 -- signal
4831 -- Ignore catalog delete ignorable error (see krbcdie) if zero,
4832 -- otherwise signal exceptions.
4833 --
4834
4835 FUNCTION cfileCalcSizeList(
4836 num_ckptprog_recs IN binary_integer default 0
4837 ,num_thread_recs IN binary_integer default 0
4838 ,num_logfile_recs IN binary_integer default 0
4839 ,num_datafile_recs IN binary_integer default 0
4840 ,num_filename_recs IN binary_integer default 0
4841 ,num_tablespace_recs IN binary_integer default 0
4842 ,num_tempfile_recs IN binary_integer default 0
4843 ,num_rmanconfiguration_recs IN binary_integer default 0
4844 ,num_loghistory_recs IN binary_integer default 0
4845 ,num_offlinerange_recs IN binary_integer default 0
4846 ,num_archivedlog_recs IN binary_integer default 0
4850 ,num_backeduplog_recs IN binary_integer default 0
4847 ,num_backupset_recs IN binary_integer default 0
4848 ,num_backuppiece_recs IN binary_integer default 0
4849 ,num_backedupdfile_recs IN binary_integer default 0
4851 ,num_dfilecopy_recs IN binary_integer default 0
4852 ,num_bkdfcorruption_recs IN binary_integer default 0
4853 ,num_dfcopycorruption_recs IN binary_integer default 0
4854 ,num_deletedobject_recs IN binary_integer default 0
4855 ,num_proxy_recs IN binary_integer default 0
4856 ,num_reserved4_recs IN binary_integer default 0
4857 ,num_db2_recs IN binary_integer
4858 ,num_incarnation_recs IN binary_integer)
4859 return binary_integer;
4860
4861 -- Description and return values can be found with original declaration
4862 -- above. New parameter:
4863 --
4864 -- num_db2_recs
4865 -- Number of KCCDEDB2 records. This is ignored internally. It does
4866 -- serve as a easy processing mech in krbicsl
4867 --
4868 -- num_incarnation_recs
4869 -- Number of KCCDEDIR records.
4870 --
4871 -- NOTE: The arguments checkpoint_time and checkpoint_change are both
4872 -- input and output.
4873 --
4874
4875 PROCEDURE resDataFileCopy( cname IN varchar2
4876 ,fname IN varchar2
4877 ,full_name OUT varchar2
4878 ,max_corrupt IN binary_integer default 0
4879 ,check_logical IN boolean
4880 ,blksize IN binary_integer
4881 ,blocks IN binary_integer
4882 ,fno IN binary_integer
4883 ,scnstr IN varchar2
4884 ,rfno IN binary_integer);
4885
4886 --
4887 -- copyDataFileCopy is used to restore a copy for duplicate.
4888
4889 -- This is a special version of copyDataFileCopy, but it is used when
4890 -- performing a duplicate, in this case, there is no controlfile at the
4891 -- duplicate. Thus the special handle used for copies cannot be performed
4892 -- Normally copydatafilecopy receives the recid-stamp of the copy and looks
4893 -- for it in the target controlfile. In this case we have to operate with
4894 -- the input name and the output name only.
4895 -- Input parameters:
4896 -- cname
4897 -- File name of the copy to use.
4898 -- fname
4899 -- File name to copy the image to. This name may not be useable by
4900 -- another process, so it will be expanded.
4901 -- max_corrupt
4902 -- Up to this many corrupt data blocks from this file can appear in the
4903 -- backup. The copy will fail if more blocks are found corrupt.
4904 -- check_logical
4905 -- if set to true indicates that besides physical block validations,
4906 -- logical validations will be performed on each block
4907 -- blksize
4908 -- Block size of the datafile copy.
4909 -- blocks
4910 -- Number of blocks in the datafile copy.
4911 -- fno
4912 -- File number that we are restoring.
4913 -- scnstr
4914 -- Checkpoint SCN of the datafilecopy for priting purposes.
4915 -- rfno
4916 -- Relative file number, required to calculate rdba
4917 -- Output parameters:
4918 -- full_name
4919 -- This is the fully expanded name of the file that was created.
4920
4921 PROCEDURE restoreControlfileTo( cfname IN varchar2
4922 ,isstby IN boolean);
4923 -- Description and return values can be found with original declaration
4924 -- above. New parameters:
4925 --
4926 -- isstby
4927 -- If set to TRUE, then restore should extract standby controlfile.
4928 -- In case that standby controlfile is not found, then the restore will
4929 -- signal error scf_not_in_bs (ORA-19695).
4930 --
4931
4932 FUNCTION cfileCalcSizeList(
4933 num_ckptprog_recs IN binary_integer default 0
4934 ,num_thread_recs IN binary_integer default 0
4935 ,num_logfile_recs IN binary_integer default 0
4936 ,num_datafile_recs IN binary_integer default 0
4937 ,num_filename_recs IN binary_integer default 0
4938 ,num_tablespace_recs IN binary_integer default 0
4939 ,num_tempfile_recs IN binary_integer default 0
4940 ,num_rmanconfiguration_recs IN binary_integer default 0
4941 ,num_loghistory_recs IN binary_integer default 0
4942 ,num_offlinerange_recs IN binary_integer default 0
4943 ,num_archivedlog_recs IN binary_integer default 0
4944 ,num_backupset_recs IN binary_integer default 0
4945 ,num_backuppiece_recs IN binary_integer default 0
4946 ,num_backedupdfile_recs IN binary_integer default 0
4947 ,num_backeduplog_recs IN binary_integer default 0
4948 ,num_dfilecopy_recs IN binary_integer default 0
4949 ,num_bkdfcorruption_recs IN binary_integer default 0
4950 ,num_dfcopycorruption_recs IN binary_integer default 0
4951 ,num_deletedobject_recs IN binary_integer default 0
4955 ,num_incarnation_recs IN binary_integer
4952 ,num_proxy_recs IN binary_integer default 0
4953 ,num_reserved4_recs IN binary_integer default 0
4954 ,num_db2_recs IN binary_integer
4956 ,num_flashback_recs IN binary_integer
4957 ,num_rainfo_recs IN binary_integer
4958 ,num_instrsvt_recs IN binary_integer
4959 ,num_agedfiles_recs IN binary_integer
4960 ,num_rmanstatus_recs IN binary_integer
4961 ,num_threadinst_recs IN binary_integer
4962 ,num_mtr_recs IN binary_integer
4963 ,num_dfh_recs IN binary_integer)
4964 return binary_integer;
4965
4966 -- Description and return values can be found with original declaration
4967 -- above. New parameter:
4968 --
4969 -- num_flashback_recs
4970 -- Number of KCCDEFLS records.
4971 -- num_rainfo_recs
4972 -- Number of KCCDERDI records.
4973 -- num_instrsvt_recs
4974 -- Number of KCCDEIRT records.
4975 -- num_agedfiles_recs
4976 -- Number of KCCDEAGF records.
4977 -- num_rmanstatus_recs
4978 -- Number of KCCDERSR records.
4979 -- num_threadinst_recs
4980 -- Number of KCCDETIR records.
4981 -- num_mtr_recs
4982 -- Number of KCCDEMTR records.
4983 -- num_dfh_recs
4984 -- Number of KCCDEFHR records.
4985 --
4986 -- NOTE: The arguments checkpoint_time and checkpoint_change are both
4987 -- input and output.
4988
4989 PROCEDURE InspectBackupPiece( handle IN varchar2
4990 ,full_handle OUT varchar2
4991 ,recid OUT number
4992 ,stamp OUT number );
4993 -- This procedure reads the header from a backuppiece and creates the
4994 -- corresponding backupset, backuppiece, backup datafile or backup redo
4995 -- log records as if the file had just been created with RMAN backup
4996 -- command.
4997 -- The inspection is done on whatever device is currently allocated, or
4998 -- on disk if no device is allocated.
4999 --
5000 -- Input parameters:
5001 -- handle
5002 -- The handle for the backup piece to inspect. This is a permanent
5003 -- name that can be used to read this sequential file for restore. It
5004 -- can only be used with the same device type that was allocated at
5005 -- this call.
5006 -- Output parameters:
5007 -- full_handle
5008 -- This is the fully expanded handle for the backup piece
5009 -- that was inspected.
5010 -- recid
5011 -- stamp
5012 -- These are the key of the record that is created in the controlfile
5013 -- when the piece is successfully inspected. It can be used to query
5014 -- information about the copy from V$BACKUP_PIECE
5015 -- Exceptions:
5016 -- NAME-TOO-LONG (ora-19704)
5017 -- The specified file name is longer than the port-specific
5018 -- maximum file name length.
5019 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
5020 -- The database is in the process of being opened, closed, mounted,
5021 -- or dismounted.
5022 -- DATABASE-NOT-MOUNTED (ora-1507)
5023 -- The database is not mounted.
5024 -- CANT_IDENTIFY_FILE (ora-19505)
5025 -- The file can't be identified.
5026 -- NOT_A_BACKUP_PIECE (ora-19608)
5027 -- backuppiece header validation failed.
5028 -- IO-ERROR
5029 -- An error occured attempting to read a file.
5030
5031 PROCEDURE backupPieceCreate( fname IN varchar2
5032 ,pieceno OUT binary_integer
5033 ,done OUT boolean
5034 ,handle OUT varchar2
5035 ,comment OUT varchar2
5036 ,media OUT varchar2
5037 ,concur OUT boolean
5038 ,params IN varchar2 default NULL
5039 ,media_pool IN binary_integer default 0
5040 ,reuse IN boolean default FALSE
5041 ,sequence IN binary_integer
5042 ,year IN binary_integer
5043 ,month IN binary_integer
5044 ,day IN binary_integer
5045 ,archlog_failover
5046 OUT boolean
5047 ,deffmt IN binary_integer
5048 ,recid OUT number
5049 ,stamp OUT number
5050 ,tag OUT varchar2);
5051 -- Description and return values can be found with original declaration
5052 -- above. New parameter:
5053 --
5054 -- month - indicates the month of controlfile autobackup
5055 -- day - indicates the day of controlfile autobackup
5056 -- deffmt - indicates if default format is used or not. Serves as a hint
5057 -- to use OMF name.
5058 -- recid - recid of the copy (if one was created)
5059 -- stamp - stamp of the copy (if one was created)
5060 -- tag - tag of the piece/copy which is created
5061 --
5062
5063 PROCEDURE backupBackupPiece( bpname IN varchar2
5064 ,fname IN varchar2
5065 ,handle OUT varchar2
5069 ,recid OUT number
5066 ,comment OUT varchar2
5067 ,media OUT varchar2
5068 ,concur OUT boolean
5070 ,stamp OUT number
5071 ,tag IN varchar2 default NULL
5072 ,params IN varchar2 default NULL
5073 ,media_pool IN binary_integer default 0
5074 ,reuse IN boolean default FALSE
5075 ,check_logical IN boolean
5076 ,copyno IN binary_integer
5077 ,deffmt IN binary_integer
5078 ,copy_recid IN number
5079 ,copy_stamp IN number
5080 ,npieces IN binary_integer );
5081 -- Description and return values can be found with original declaration
5082 -- above. New parameters
5083 --
5084 -- deffmt - indicates if default format is used or not. Serves as a hint
5085 -- to use OMF name.
5086 -- copy_recid
5087 -- copy_stamp
5088 -- the controlfile identifiers of a backuppiece to be backed up.
5089 -- npieces - number of backuppieces in this backupset.
5090 --
5091
5092 PROCEDURE refreshAgedFiles;
5093
5094 PROCEDURE applyDataFileTo( dfnumber IN binary_integer
5095 ,toname IN varchar2 default NULL
5096 ,fuzziness_hint IN number default 0
5097 ,max_corrupt IN binary_integer
5098 ,islevel0 IN binary_integer
5099 ,recid IN number
5100 ,stamp IN number);
5101 -- Description and return values can be found with original declaration
5102 -- above. New parameters
5103 --
5104 -- islevel0
5105 -- >0 if the specified toname is level 0 copy. Otherwise 0.
5106 -- recid, stamp
5107 -- Controlfile record id and stamp associated with this datafilecopy.
5108 -- Pass it as 0 for real-datafiles.
5109
5110 PROCEDURE dba2rfno( dbano IN number,
5111 rfno OUT number,
5112 blockno OUT number,
5113 tsnum IN binary_integer );
5114 --
5115 -- Description can be found with original declaration. New parameter:
5116 --
5117 -- tsnum
5118 -- tablespace number to which DBA belongs
5119 --
5120
5121 PROCEDURE flashbackStart(flashbackSCN IN number,
5122 flashbackTime IN date,
5123 scnBased IN binary_integer,
5124 toBefore IN binary_integer);
5125 --
5126 -- Starts a flashback conversation to flashback the database to
5127 -- given flashbackSCN/flashbackTime.
5128 --
5129 -- flashbackSCN
5130 -- scn to which to flashback.
5131 -- flashbackTime
5132 -- time to which to flashback.
5133 -- scnBased
5134 -- TRUE(>0) if the flashback target is an SCN.
5135 -- FALSE(=0) if flashback target is a timestamp
5136 -- toBefore
5137 -- TRUE(>0) if transaction at SCN/timestamp should be rolled back
5138 -- (user said "flashback to before")
5139 -- FALSE(=0) if transaction at SCN/timestamp should not be rolled back
5140 --
5141
5142
5143 PROCEDURE flashbackAddFile( fileno IN binary_integer );
5144 -- flashbackAddFile adds the given file to the list that needs a flashback.
5145
5146 PROCEDURE flashbackFiles(alname IN varchar2);
5147 -- flashbackFiles does the real work of flashbacking the list
5148 -- added using flashbackAddFile to the SCN specified by flashbackStart.
5149
5150 PROCEDURE flashbackCancel;
5151 -- flashbackCancel destroys the flashback conversation
5152
5153 PROCEDURE restoreSetPiece ( handle IN varchar2
5154 ,tag IN varchar2
5155 ,fromdisk IN boolean
5156 ,recid IN number
5157 ,stamp IN number );
5158 -- restoreSetPiece sets up the handle for restoreBackupPiece to use.
5159 -- When multiple copies of piece exists, call restoreSetPiece to
5160 -- for each copy before calling restoreBackupPiece. This will enable
5161 -- RESTORE FAILOVER feature inside kernel
5162 -- Input parameters:
5163 -- handle
5164 -- The handle of the backup piece to restore from.
5165 -- tag
5166 -- The tag associated with the backup piece.
5167 -- fromdisk
5168 -- TRUE if the backuppiece is from device disk. Used to dynamically
5169 -- allocate a disk context in SBT channel
5170 -- recid, stamp
5171 -- controlfile record id and stamp associated with this handle
5172 --
5173
5174 PROCEDURE restoreBackupPiece( done OUT boolean
5175 ,params IN varchar2 default NULL
5176 ,outhandle OUT varchar2
5177 ,outtag OUT varchar2
5178 ,failover OUT boolean );
5179 -- Description and return values can be found in the original declaration.
5180 --
5181 -- New parameter:
5182 --
5183 -- Output parameters:
5184 -- outhandle
5188 -- outtag
5185 -- The handle of the backup piece used for restore. When multiple copies
5186 -- of backuppiece are set during restore, then this handle is the
5187 -- last one which was used to successfully complete the restore.
5189 -- The tag associated with that handle.
5190 -- failover
5191 -- TRUE when failover to other backuppieces were done due to various
5192 -- reasons like piece-not-found, piece-in-accessible,
5193 -- validation-failed, data-block-corruption etc.
5194 --
5195
5196 FUNCTION fetchFileRestored(firstcall IN boolean
5197 ,proxy IN boolean
5198 ,ftype OUT binary_integer
5199 ,fno OUT binary_integer
5200 ,thread OUT binary_integer
5201 ,sequence OUT number
5202 ,resetSCN OUT number
5203 ,resetStamp OUT number)
5204 return binary_integer;
5205 --
5206 -- fetchFileRestored is used to get the files which were restored
5207 -- successfully by the restore conversation.
5208 -- Returns 0 when there are no more files to be returned, otherwise
5209 -- a non-zero value. This function should be called multiple times
5210 -- to fetch all files there were restored.
5211 --
5212 -- Input parameters:
5213 -- firstcall
5214 -- TRUE if it is first fetch, otherwise FALSE.
5215 -- proxy
5216 -- TRUE if it is a proxy restore, otherwise FALSE
5217 -- Output parameters:
5218 -- ftype
5219 -- file type constant (see KSFD_* constants in ksfd.h)
5220 -- fno
5221 -- datafile number
5222 -- thread, sequence, resetSCN, resetStamp
5223 -- archivelog information
5224 --
5225
5226 PROCEDURE restoreCancel(check_files IN boolean);
5227 -- Description and return values can be found in the original declaration.
5228 --
5229 -- New parameter:
5230 --
5231 -- Input parameters:
5232 -- check_files
5233 -- TRUE to check if all files were restored in the restore conversation.
5234 -- Otherwise, just destroy the conversation.
5235 --
5236
5237 PROCEDURE restoreSetDataFile( check_logical IN boolean
5238 ,cleanup IN boolean);
5239 PROCEDURE applySetDataFile( check_logical IN boolean
5240 ,cleanup IN boolean);
5241 PROCEDURE restoreSetArchivedLog( destination IN varchar2 default NULL
5242 ,cleanup IN boolean);
5243 PROCEDURE proxyBeginRestore( destination IN varchar2 default NULL
5244 ,cleanup IN boolean);
5245 -- Description and return values can be found with original declaration
5246 -- above.
5247 -- New parameters
5248 --
5249 -- Input parameters:
5250 --
5251 -- cleanup
5252 -- TRUE to cleanup restore conversation, otherwise leave the conversation
5253 -- context for further queries.
5254 --
5255
5256 FUNCTION genPieceName(pno IN number
5257 ,set_count IN number
5258 ,set_stamp IN number
5259 ,format IN varchar2
5260 ,copyno IN number
5261 ,devtype IN varchar2
5262 ,year IN binary_integer
5263 ,month IN binary_integer
5264 ,day IN binary_integer
5265 ,dbid IN number
5266 ,ndbname IN varchar2
5267 ,cfseq IN number
5268 ,fileno IN number
5269 ,tsname IN varchar2
5270 ,logseq IN varchar2
5271 ,logthr IN number
5272 ,imagcp IN boolean)
5273 return varchar2;
5274 -- Removed pdbname
5275 -- Added new parameters for creating names:
5276 -- fileno
5277 -- Absolute datafile number
5278 -- tsname
5279 -- Tablespace name to which this datafile belongs
5280 -- logseq
5281 -- Log sequence for archivelogs
5282 -- logthr
5283 -- Log thread for archivelogs
5284 -- imagcp
5285 -- Generate a name for an image copy.
5286
5287
5288 PROCEDURE backupSetDataFile( set_stamp OUT number
5289 ,set_count OUT number
5290 ,nochecksum IN boolean default FALSE
5291 ,tag IN varchar2 default NULL
5292 ,incremental IN boolean default FALSE
5293 ,backup_level IN binary_integer default 0
5294 ,check_logical IN boolean default FALSE
5295 ,keep_options IN binary_integer default 0
5296 ,keep_until IN number default 0
5297 ,imagcp IN boolean
5298 ,convertto IN boolean
5299 ,convertfr IN boolean
5300 ,pltfrmto IN binary_integer
5301 ,pltfrmfr IN binary_integer
5302 ,sameen IN boolean);
5303
5304 -- Description and return values can be found with original declaration
5305 -- above. New parameters
5306
5307 -- imagcp
5311 -- convertfr
5308 -- Do not generate backup pieces, generate image copies.
5309 -- convertto
5310 -- If true indicates that we are doing convert at source.
5312 -- If true indicates that we are doing convert at source.
5313 -- pltfrmto
5314 -- NULL if this is not a convert command, otherwise is the id of the
5315 -- platform we are converting to.
5316 -- pltfrmfr
5317 -- NULL if this is not a convert command, otherwise is the id of the
5318 -- platform we are converting from.
5319 -- sameen
5320 -- If TRUE indicates this is a same endianess conversion
5321 --
5322
5323 FUNCTION getTsNameFromDataFileCopy(fname IN varchar2
5324 ,fno IN number)
5325 return varchar2;
5326
5327 -- Obtains the tablespace name to which this datafilecopy belonged
5328 --
5329 -- Input parameters
5330 -- fname - Datafile copy name
5331 -- fno - Datafile number of the copy
5332 --
5333 -- Return value
5334 -- Error if datafilecopy does not exist
5335 -- Otherwise the tablespace name of this datafilecopy
5336
5337 PROCEDURE backupSetArchivedLog( set_stamp OUT number
5338 ,set_count OUT number
5339 ,nochecksum IN boolean default FALSE
5340 ,tag IN varchar2
5341 ,imagcp IN boolean);
5342
5343 -- Description and return values can be found with original declaration
5344 -- above. New parameters
5345
5346 -- imagcp
5347 -- Do not generate backup pieces, generate image copies.
5348
5349 PROCEDURE backupControlFile( cfname IN varchar2 default NULL,
5350 isstby IN boolean );
5351
5352 -- Description and return values can be found with original declaration
5353 -- above. New parameters:
5354 -- isstby
5355 -- If TRUE, indicates that the controlfile to make is a
5356 -- standby controlfile, normal backup otherwise
5357
5358
5359 FUNCTION convertFileName(fname IN varchar2,
5360 ftype IN binary_integer,
5361 osftype IN boolean) return varchar2;
5362
5363 -- Description and return values can be found with original declaration
5364 -- above. New parameters:
5365 -- osftype
5366 -- If TRUE, indicates that the ftype passed is of KSFD_* type. Otherwise
5367 -- old protocol is followed (see original declaration).
5368 --
5369
5370 PROCEDURE restoreDataFileTo( dfnumber IN binary_integer
5371 ,toname IN varchar2 default NULL
5372 ,max_corrupt IN binary_integer
5373 ,tsname IN varchar2);
5374 -- Description and return values can be found with original declaration
5375 -- above. New parameters
5376 --
5377 -- tsname
5378 -- The name of the tablespace
5379 --
5380 -- restoreDataFileTo creates the output file from a complete backup in the
5381 -- backup set.
5382
5383
5384 PROCEDURE searchFiles(pattern IN OUT varchar2
5385 ,ns IN OUT varchar2
5386 ,ccf IN boolean default FALSE
5387 ,omf IN boolean default FALSE
5388 ,ftype IN varchar2 default NULL);
5389 --
5390 -- This procedure populates X$KRBMSFT with list files that match specified
5391 -- pattern.
5392 --
5393 -- Input parameters:
5394 -- pattern
5395 -- Pattern to search. In case of OMF, it represents OMF location. If
5396 -- parameter is null and omf is true, then pattern will be set to
5397 -- DB_RECOVERY_FILE_DEST.
5398 -- ns
5399 -- Lock name space. Valid only in case of OMF. If parameter is null,
5400 -- it will be to DB_NAME or LOCK_NAME_SPACE.
5401 -- ccf
5402 -- Flag which tells whether to populate krbmsftp [KRMB Search File
5403 -- Table] with files known to the controlfile.
5404 -- omf
5405 -- Flag which tells whether to do OMF or non-OMF search.
5406 -- ftype
5407 -- File type to search for. It can be one of the following:
5408 -- 'A' - Archive logs
5409 -- 'B' - Backups
5410 -- 'U' - aUtobackups
5411 -- For non-OMF case, the filetype is used to manipulate the pattern
5412 -- like adding '/' for archivelog search.
5413 --
5414 -- Exceptions:
5415 -- ra_not_set (-19801)
5416 -- Raised if recovery area is not set.
5417
5418 PROCEDURE processSearchFileTable(catalog IN boolean,
5419 implicit IN binary_integer);
5420 --
5421 -- This procedure will read header for all files from search file table
5422 -- (X$KRBMSFT). If the catalog is TRUE is will also try to catalog them.
5423 --
5424 -- Input parameters:
5425 -- catalog
5426 -- Flag which tell whether the function should catalog files.
5427 -- implicit
5428 -- 0 if user invoked to catalog files. Otherwise, RMAN does
5429 -- implicit cataloging.
5430 --
5431 -- Output parameters:
5432 -- None.
5433 --
5434
5435 FUNCTION findAutSearchFileTable( mustspfile IN boolean
5436 ,until IN number
5437 ,fname OUT varchar2
5441 ,sequence OUT binary_integer
5438 ,year OUT binary_integer
5439 ,month OUT binary_integer
5440 ,day OUT binary_integer
5442 ,ats OUT number)
5443 RETURN boolean;
5444 --
5445 -- This procedure returns auto backup piece from X$KRBMSFT which match the
5446 -- input criteria (mustspfile and until).
5447 --
5448 -- Input parameters:
5449 -- mustspfile
5450 -- Flag which tell whether the returning autobackup should contain
5451 -- SPFILE.
5452 -- until
5453 -- Until timestamp. The autobackup should not be newer than until.
5454 --
5455 -- Output parameters:
5456 -- year
5457 -- Year of the autobackup.
5458 -- month
5459 -- Month of the autobackup.
5460 -- day
5461 -- Day of the autobackup.
5462 -- sequence
5463 -- Sequence of the autobackup.
5464 -- ats
5465 -- Autobackup Time Stamp. This is the timestamp of the autobackup we
5466 -- have found.
5467 --
5468
5469 PROCEDURE bctSwitch(filelist IN varchar2 default NULL);
5470 -- This procedure switches change tracking bitmaps for the specified list
5471 -- of files.
5472 --
5473 -- Input parameters:
5474 -- filelist
5475 -- A list of files in the following format:
5476 -- filelist : filespec |
5477 -- filelist , filespec
5478 --
5479 -- filespec : filenum |
5480 -- filenum - filenum
5481 --
5482 -- The first form of filespec (single file number) causes the specified
5483 -- file to be switched. The second form of filespec (two file numbers,
5484 -- separated by a dash) causes all of the files in the specified range,
5485 -- inclusive, to be switched.
5486 --
5487 -- Specify NULL to switch all files in the database.
5488
5489 PROCEDURE bctSet(parmno IN binary_integer,
5490 numval IN number default null,
5491 charval IN varchar2 default null);
5492
5493 BCTSET_CLEANLIMIT constant binary_integer := 1;
5494 BCTSET_CKPFREQ constant binary_integer := 2;
5495 BCTSET_MAXPEND constant binary_integer := 3;
5496 BCTSET_MAXEXT constant binary_integer := 4;
5497 BCTSET_OPTIONS constant binary_integer := 5;
5498 BCTSET_CTWR_EMPTY_THRESHOLD constant binary_integer := 6;
5499 BCTSET_CTWR_REAP_THRESHOLD constant binary_integer := 7;
5500 BCTSET_CTWR_CIC_SECONDS constant binary_integer := 8;
5501
5502
5503 -- This procedure allows for runtime adjustment of various constants
5504 -- that affect the operation of the CTWR process. This routine should
5505 -- be used only by Oracle support personnel.
5506
5507
5508 PROCEDURE resetDatabase(dbinc_key IN number);
5509 -- resetDatabase is used to change the recovery destination incarnation.
5510 -- refer to krbcrdb() function for restrictions and errors returned.
5511
5512 PROCEDURE proxyRestoreArchivedlog(handle IN varchar2,
5513 thread IN binary_integer,
5514 sequence IN number,
5515 resetlogs_id IN number,
5516 blksize IN binary_integer,
5517 blocks IN number);
5518
5519 -- Specify one archived log to be restored during a proxy session.
5520 --
5521 -- Following parameter added :
5522 -- resetlogs_id -
5523 -- resetlogs timestamp used to construct unique names
5524 -- for archived logs accross incarnations during proxy restores.
5525 -- blksize - block size of archive log to be restored
5526 -- blocks - number of blocks in archivelog log to be restored
5527
5528 PROCEDURE inspectArchivedLog( fname IN varchar2
5529 ,full_name OUT varchar2
5530 ,recid OUT number
5531 ,stamp OUT number
5532 ,change_rdi IN boolean );
5533
5534 -- Specify archived log to inspected.
5535 --
5536 -- Following parameter added :
5537 -- change_rdi
5538 -- boolean value to indicate where recovery destination incarnation
5539 -- can be changed when inspecting this log. This flag is set to FALSE
5540 -- normally when RMAN is inspecting online logs for backup controlfile.
5541
5542 PROCEDURE inspectArchivedLogSeq( log_dest IN varchar2
5543 ,format IN varchar2 DEFAULT NULL
5544 ,thread IN binary_integer
5545 ,sequence IN number
5546 ,full_name OUT varchar2
5547 ,resetlogs_id IN number );
5548
5549 -- Specify archived log to inspected.
5550 --
5551 -- Following parameter added :
5552 -- resetlogs_id
5553 -- Incarnation's resetlogs timestamp.
5554
5555 PROCEDURE createRmanStatusRow( level IN binary_integer
5556 ,parent_id IN number
5557 ,parent_stamp IN number
5558 ,status IN binary_integer
5559 ,command_id IN varchar2
5560 ,operation IN varchar2
5561 ,row_id OUT number
5562 ,row_stamp OUT number);
5563 --
5567 --
5564 -- Creates an row for V$RMAN_STATUS view. The function will create one
5565 -- row in SGA (krbmrsrt [Rman Status Row Table] and create one controlfile
5566 -- record (kccrsr).
5568 -- Input paramters:
5569 -- level
5570 -- The level of the row. For example, if level is 0, then the operation
5571 -- desribed by this row contains all opeations with level=1 with
5572 -- parent_id equal to id of this row. If level is > 0, then
5573 -- patern_id must be specfied.
5574 -- parent_id
5575 -- Valid only if level > 0. Specified the recid of the parent row.
5576 -- parent_stamp
5577 -- Valid only if level > 0. Specified the timestamp of the parent row.
5578 -- status
5579 -- The status of the row.
5580 -- command_id
5581 -- Command id set by the user.
5582 -- operation
5583 -- The name of the operation.
5584 --
5585 -- Output paramters:
5586 -- row_id (OUT)
5587 -- The recid of the newly create row.
5588 -- row_stamp (OU)
5589 -- The timestamp of the newly create row.
5590 --
5591
5592 PROCEDURE updateRmanStatusRow( row_id IN number
5593 ,row_stamp IN number
5594 ,status IN binary_integer);
5595 --
5596 -- Updates a row in the V$RMAN_STATUS view. The function will update the
5597 -- status of the row in the SGA.
5598 --
5599 -- Input paramters:
5600 -- row_id
5601 -- The id of the row which to update
5602 -- row_stamp
5603 -- The stamp of the row which to update
5604 -- status
5605 -- The status of the operation.
5606 --
5607 -- Return value:
5608 -- None.
5609 --
5610
5611 PROCEDURE commitRmanStatusRow( row_id IN number
5612 ,row_stamp IN number
5613 ,mbytes IN number
5614 ,status IN binary_integer);
5615 -- Commits the row into controlfile. The SGA version of the row is saved in
5616 -- the controlfile and the contolfile record is marked as finished.
5617 --
5618 -- Input paramters:
5619 -- row_id
5620 -- The recid of the row to commit
5621 -- row_stamp
5622 -- The timestamp of the row to commit
5623 -- mbytes
5624 -- The amout of MB processed.
5625 -- status
5626 -- The status of the operation.
5627 --
5628 --
5629
5630 PROCEDURE createRmanOutputRow( l0row_id IN number
5631 ,l0row_stamp IN number
5632 ,row_id IN number
5633 ,row_stamp IN number
5634 ,txt IN varchar2);
5635 -- Creates an row in a V$RMAN_OUTPUT view. In other words, the function will
5636 -- create one row in SGA (krbmrort [Rman Outpur Row Table].
5637 --
5638 -- Input paramters:
5639 -- l0row_id
5640 -- The recid of the level 0 row in V$RMAN_STATUS (x$krbmrst/x$kccrsr)
5641 -- l0row_stamp
5642 -- The time stamp of the level 0 row in V$RMAN_STATUS
5643 -- (x$krbmrst/x$kccrsr)
5644 -- row_id
5645 -- The recid of the row in V$RMAN_STATUS (x$krbmrst/x$kccrsr)
5646 -- row_stamp
5647 -- The time stamp of the row in V$RMAN_STATUS (x$krbmrst/x$kccrsr)
5648 -- txt
5649 -- The text of the row
5650 --
5651 -- Return value:
5652 -- Nothing
5653 --
5654 --
5655
5656 PROCEDURE setRmanStatusRowId( rsid IN number
5657 ,rsts IN number);
5658 -- By calling this function all opeartion by this foreground will be
5659 -- associated with a V$RMAN_STATUS row.
5660 --
5661 -- rsid
5662 -- Recid of the RMAN command which is responsible for this conversation.
5663 -- rsts
5664 -- Timestamp of the RMAN command which is responsible for this
5665 -- conversation.
5666 --
5667
5668 PROCEDURE readFileHeader(fname IN varchar2,
5669 dbname OUT varchar2,
5670 dbid OUT number,
5671 tsname OUT varchar2,
5672 fno OUT binary_integer,
5673 nblocks OUT number,
5674 blksize OUT binary_integer,
5675 plid OUT binary_integer,
5676 sameen IN binary_integer);
5677
5678 -- This function is used to obtain information from the file header of
5679 -- a datafile that is being cross-platform converted at the target.
5680 -- In this case the file does not belong to the database (yet) and its
5681 -- block format is not the same of the database that is doing the
5682 -- conversion.
5683 --
5684 -- fname
5685 -- Name of the file that needs to be read.
5686 -- dbname
5687 -- Name of the database from which this file came.
5688 -- dbid
5689 -- dbid of the database from which this file came.
5690 -- tsname
5691 -- Name of the tablespace that this file belongs to.
5692 -- fno
5693 -- Absolute file number that this file had in its original database
5694 -- nblocks
5695 -- number of blocks in the file
5696 -- blksize
5697 -- blocksize of the file
5698 -- plid
5699 -- platform id from the header
5700 -- sameen
5701 -- TRUE if this is a same endianess conversion
5702 --
5703 --
5704 PROCEDURE getDefaultTag(deftag OUT varchar2);
5708 -- the time.
5705
5706 -- Constructs the default tag for backups and image copies.
5707 -- The default tag is a in the ISO 8601 compliance contaning the date and
5709
5710 PROCEDURE switchToCopy( copy_recid IN number
5711 ,copy_stamp IN number
5712 ,catalog IN boolean );
5713 -- Causes the filename in the indicated datafile copy record to become
5714 -- the current named datafile. The file number to rename is taken from
5715 -- the V$DATAFILE_COPY record.
5716 -- Following parameter added :
5717 -- catalog
5718 -- If true, then after the switch, the function will catalog the original
5719 -- file (one which was before the switch in V$DATAFILE) as datafile copy.
5720 --
5721
5722
5723
5724 PROCEDURE convertDataFileCopy(fname IN varchar2,
5725 max_corrupt IN binary_integer default 0);
5726 -- Name one file for conversion at the target database.
5727
5728
5729 PROCEDURE initnamespace;
5730 -- Used for testing to create locations because oratst doesn't support
5731 -- creating locations with uppercase. It initializes controlfile,
5732 -- logfile and datafile locations for db_create_file_dest
5733
5734
5735 PROCEDURE manageAuxInstance( orasid IN varchar2
5736 ,cleanup IN binary_integer);
5737
5738 -- This function is used by RMAN to manage the auxiliary
5739 -- instance for those OSs that require OS setup.
5740 -- If cleanup is FALSE, the tasks could include
5741 -- create 'services'
5742 -- If cleanup is TRUE, the taks could include:
5743 -- remove the 'services'
5744 -- Input parameters:
5745 -- orasid
5746 -- This is the ORACLE_SID of the database that will be created
5747 -- cleanup
5748 -- Non zero indicates to perform cleanup actions.
5749
5750 PROCEDURE getCnctStr( cnctstr OUT varchar2
5751 ,orasid IN varchar2
5752 ,escaped IN boolean);
5753
5754 -- This function obtains from the server the connect string to use
5755 -- as defined in sparams.h; if escaped is TRUE then it performs
5756 -- sosd specific conversion to allow connect string to be passed to
5757 -- RMAN host command.
5758
5759 -- Output parameters:
5760 -- cnctstr
5761 -- This is the connect string that will be returned
5762 -- Input parameters:
5763 -- orasid
5764 -- This is the ORACLE_SID of the database to which we want to connect
5765 -- escaped
5766 -- This indicates if the connect string should be processed to
5767 -- be used by RMAN host command.
5768
5769
5770 VALIDATION_OK constant binary_integer := 0;
5771 VALIDATION_RECORD_NOTFOUND constant binary_integer := 1;
5772 VALIDATION_RECORD_DIFFERENT constant binary_integer := 2;
5773 VALIDATION_FILE_DIFFERENT constant binary_integer := 4;
5774
5775
5776 -- Validate the correctness of the information in the recovery catalog
5777 -- and the controlfile regarding a backup piece, datafile copy, or
5778 -- archived log. Neither the controlfile record nor the physical file itself
5779 -- is deleted. No errors are signalled. The return code contains one or more
5780 -- of the above constants, which tell the caller whether the controlfile
5781 -- record and/or the file itself is valid. These constants are bit-flags,
5782 -- so bitand() must be used to decode the return code's value. The status
5783 -- of the file itself is independant of the status of the record in the
5784 -- controlfile. If the file is not found or does not match the validation
5785 -- data, then the VALIDATE_FILE_DIFFERENT flag will be set. If the
5786 -- record in the controlfile is not found or is different, the corresponding
5787 -- VALIDATE_RECORD_xxx flag will be set. The two VALIDATE_RECORD_xxx flags
5788 -- are mutually exclusive. Thus, the possible return codes from the validate
5789 -- functions are: 0, 1, 2, and 4.
5790 --
5791 -- These procedures do not update the controlfile.
5792 --
5793 -- Input parameters:
5794 -- stamp
5795 -- recid
5796 -- These are the key of the record in the controlfile where the
5797 -- information about the file was recorded.
5798 -- handle
5799 -- fname
5800 -- The name or handle of the file/piece to validate.
5801 -- params
5802 -- This string is simply passed to the sequential file reading OSD. It
5803 -- is completely port and device specific.
5804
5805 -- The remaining parameters are used to determine whether or not the
5806 -- file in question is the correct file.
5807
5808 -- set_stamp
5809 -- set_count
5810 -- Backup set identification.
5811 -- pieceno
5812 -- Piece number within backup set.
5813
5814 FUNCTION validateBackupPiece(recid IN number
5815 ,stamp IN number
5816 ,handle IN varchar2
5817 ,set_stamp IN number
5818 ,set_count IN number
5819 ,pieceno IN binary_integer
5820 ,params IN varchar2 default NULL
5821 ,hdl_isdisk IN binary_integer
5822 ,media OUT varchar2)
5823 return binary_integer;
5824 -- Description and return values can be found with original declaration
5825 -- above. New parameters
5826 --
5827 -- media
5828 -- media handle on which piece exists
5829 --
5833 -- This procedure initializes restore conversation and
5830
5831
5832 PROCEDURE validationStart;
5834 -- the list of backup pieces to validate.
5835 -- Any pieces already in the list will be removed.
5836
5837
5838 PROCEDURE validationAddPiece( recid IN number
5839 ,stamp IN number
5840 ,handle IN varchar2
5841 ,set_stamp IN number
5842 ,set_count IN number
5843 ,pieceno IN number
5844 ,params IN varchar2 default NULL
5845 ,hdl_isdisk IN binary_integer);
5846 -- Adds a backup piece to the list of pieces to validate.
5847
5848
5849 PROCEDURE validationValidate;
5850 -- does the actual validation
5851
5852
5853 PROCEDURE validationNextResult( handle OUT varchar2
5854 ,recid OUT number
5855 ,set_stamp OUT number
5856 ,set_count OUT number
5857 ,pieceno OUT number
5858 ,msca OUT binary_integer
5859 ,m1 OUT varchar2
5860 ,m2 OUT varchar2
5861 ,m3 OUT varchar2
5862 ,m4 OUT varchar2
5863 ,m5 OUT varchar2
5864 ,m6 OUT varchar2
5865 ,m7 OUT varchar2
5866 ,m8 OUT varchar2
5867 ,m9 OUT varchar2
5868 ,m10 OUT varchar2
5869 ,m11 OUT varchar2
5870 ,m12 OUT varchar2
5871 ,m13 OUT varchar2
5872 ,m14 OUT varchar2
5873 ,m15 OUT varchar2
5874 ,m16 OUT varchar2
5875 ,m17 OUT varchar2
5876 ,m18 OUT varchar2
5877 ,m19 OUT varchar2
5878 ,m20 OUT varchar2);
5879 -- Gets the next result
5880 -- If no more results are found, then HANDLE is null. The remaining
5881 -- output variables will have undefined values.
5882 --
5883 -- Description and return values can be found with original declaration
5884 -- above. New parameters
5885 --
5886 -- msca
5887 -- Media Supports Concurrent Access. Set to 1 if the media allows
5888 -- concurrent access by more than one reader (e.g., hard disk), or
5889 -- 0 if it does not (e.g., tape drives).
5890 --
5891 -- m1 - m20
5892 -- These are media handles on which a particular piece is stored.
5893 -- A piece may span any number of tapes, however we limit the
5894 -- number of tapes returned to 20. If a piece spans more than 20
5895 -- tapes, then we return the first 19 and the last tape returned
5896 -- by the media management layer. This is important because we
5897 -- want to remember which tape the channel currently holds when
5898 -- we assign steps.
5899
5900
5901 PROCEDURE validationEnd;
5902 -- This procedure ends the restore conversation.
5903
5904 PROCEDURE backupPieceCreate( fname IN varchar2
5905 ,pieceno OUT binary_integer
5906 ,done OUT boolean
5907 ,handle OUT varchar2
5908 ,comment OUT varchar2
5909 ,media OUT varchar2
5910 ,concur OUT boolean
5911 ,params IN varchar2 default NULL
5912 ,media_pool IN binary_integer default 0
5913 ,reuse IN boolean default FALSE
5914 ,archlog_failover OUT boolean
5915 ,deffmt IN binary_integer
5916 ,recid OUT number
5917 ,stamp OUT number
5918 ,tag OUT varchar2
5919 ,docompress IN boolean);
5920 -- Description and return values can be found with original declaration
5921 -- above. New parameter:
5922 --
5923 -- docompress - compress this backup piece?
5924 --
5925
5926 PROCEDURE getLimit( name IN binary_integer
5927 ,value OUT number );
5928
5929 -- Get a limit to a particular value. This is a generic infra-structure to
5930 -- return values for conversation, after the conversation is destroyed.
5931 -- For the list of possible values <name> can have, refer to the constants
5932 -- defined in setLimit function.
5933 --
5934 -- Input parameters:
5935 -- name
5936 -- The limit number to set. Valid limit numbers are the constants above.
5937 -- value
5938 -- The value of the limit.
5939 -- Exceptions:
5940 -- INVALID-LIMIT-NUMBER (ora-19560)
5941 -- An invalid limit number was specified.
5942 -- DEVICE-NOT-ALLOCATED (ora-19569)
5943 -- This session does not have a device allocated.
5944
5948 --
5945 PROCEDURE clearRecoveryDestFlag(rectype IN binary_integer,
5946 recid IN number,
5947 stamp IN number);
5949 -- Set is_recovery_dest_file='NO' for the given record.
5950 --
5951 -- Input parameters:
5952 -- rectype
5953 -- The record type whose record needs to be cleared.
5954 -- recid, stamp
5955 -- The record-id, stamp to identify the record.
5956
5957 PROCEDURE nidbegin(newdbname IN varchar2,
5958 olddbname IN varchar2,
5959 newdbid IN number,
5960 olddbid IN number,
5961 dorevert IN binary_integer,
5962 dorestart IN binary_integer,
5963 events IN number);
5964
5965 PROCEDURE nidgetnewdbid(dbname IN varchar2,
5966 ndbid OUT number);
5967
5968 PROCEDURE nidend;
5969
5970 PROCEDURE nidprocesscf(chgdbid OUT binary_integer,
5971 chgdbname OUT binary_integer);
5972
5973 PROCEDURE nidprocessdf(fno IN number,
5974 istemp IN binary_integer,
5975 skipped OUT binary_integer,
5976 chgdbid OUT binary_integer,
5977 chgdbname OUT binary_integer);
5978
5979 PROCEDURE isfileNameOMF(fname IN varchar2,
5980 isOMF OUT boolean,
5981 isASM OUT boolean);
5982 --
5983 -- Is given filename belongs to OMF family?
5984 --
5985 -- Input parameters:
5986 -- fname - Name of file in question.
5987 -- isOMF - TRUE if filename belongs to OMF family. Otherwise, FALSE.
5988 -- All filenames with prefix o1_mf (on unix and NT) and ASM
5989 -- system alias are considered as OMF files.
5990 -- isASM - TRUE if filename belongs to ASM family. Otherwise, FALSE.
5991 -- Note that this is TRUE even for ASM user alias.
5992 --
5993
5994 PROCEDURE proxyRestoreDatafile(handle IN varchar2,
5995 file# IN binary_integer,
5996 toname IN varchar2 default NULL,
5997 tsname IN varchar2,
5998 blksize IN binary_integer,
5999 blocks IN number);
6000 -- Following parameter added :
6001 -- tsname - tablespace name to which this datafile belongs
6002 -- blksize - block size of datafile to be restored
6003 -- blocks - number of blocks in datafile to be restored
6004
6005 PROCEDURE proxyRestoreControlfile(handle IN varchar2,
6006 toname IN varchar2,
6007 blksize IN binary_integer,
6008 blocks IN number);
6009 -- Following parameter added :
6010 -- blksize - block size of controlfile to be restored
6011 -- blocks - number of blocks in controlfile to be restored
6012
6013 PROCEDURE clearOnlineLogNames;
6014
6015 -- For TSPITR when AUXILIARY DESTINATION is used, we need to clear all
6016 -- names of the online logs so that they are created in the specified
6017 -- location.
6018 -- This is also used as a procedure to migrate online logs to OMF
6019 -- names using standby migration utility.
6020
6021 PROCEDURE createDatafile(fno IN number,
6022 newomf IN boolean,
6023 recovery IN boolean,
6024 fname IN varchar2 default NULL);
6025 --
6026 -- re-createDatafile for RMAN. Functionally this is same as ALTER
6027 -- DATABASE CREATE DATAFILE from RMAN client point of view, when
6028 -- RMAN is doing recovery (i.e., recovery is TRUE).
6029 -- If called during restore (i.e., recovery is FALSE), then this
6030 -- function creates a datafile and adds datafile copy record to
6031 -- control file instead of updating kccfe datafile record. The
6032 -- created file can be treated same as level 0 datafile copy.
6033 --
6034 -- Input parameters:
6035 -- fno - File number to create.
6036 -- newomf - TRUE if server has to generate a new name for the file
6037 -- created.
6038 -- recovery- TRUE called during recovery.
6039 -- fname - Name of the new file name. Used as input only if newname is
6040 -- FALSE.
6041 -- If input is NULL, the same name as in control file will be
6042 -- attempted to create.
6043
6044 PROCEDURE applyOfflineRange(cfname in varchar2 default null,
6045 dfname in varchar2 default null,
6046 blksize in number default null,
6047 recid in number default null,
6048 stamp in number default null,
6049 fno in binary_integer,
6050 dfrecid in number,
6051 dfstamp in number);
6052
6053 -- Following parameters are added :
6054 -- dfrecid - datafilecopy recid (valid only if dfname is not null)
6055 -- dfstamp - datafilecopy stamp (valid only if dfname is not null)
6056
6057 PROCEDURE resetCfileSection(record_type IN binary_integer );
6058
6059 -- This procedure attempts to reset the circular controlfile section.
6060 --
6061 -- Input parameters:
6062 -- record_type
6063 -- The circular record type whose controlfile section is to be reset.
6064
6068 isTMPLT OUT boolean);
6065 PROCEDURE isfileNameOMF(fname IN varchar2,
6066 isOMF OUT boolean,
6067 isASM OUT boolean,
6069
6070 -- Following parameters are added:
6071 -- isTMPLT - TRUE if fname is a template
6072
6073 FUNCTION fetchFileRestored(firstcall IN boolean
6074 ,proxy IN boolean
6075 ,ftype OUT binary_integer
6076 ,fno OUT binary_integer
6077 ,thread OUT binary_integer
6078 ,sequence OUT number
6079 ,resetSCN OUT number
6080 ,resetStamp OUT number
6081 ,fname OUT varchar2)
6082 return binary_integer;
6083
6084 -- Description and return values can be found with original declaration
6085 -- above. New parameter:
6086 --
6087 -- fname - Return restored filename
6088 --
6089
6090 PROCEDURE resDataFileCopy( cname IN varchar2
6091 ,fname IN varchar2
6092 ,full_name OUT varchar2
6093 ,max_corrupt IN binary_integer default 0
6094 ,check_logical IN boolean
6095 ,blksize IN binary_integer
6096 ,blocks IN binary_integer
6097 ,fno IN binary_integer
6098 ,scnstr IN varchar2
6099 ,rfno IN binary_integer
6100 ,tsname IN varchar2);
6101
6102 -- Description and return values can be found with original declaration
6103 -- above. New parameter:
6104 --
6105 -- tsname - tablespace name to which this file belongs
6106 --
6107
6108 PROCEDURE flashbackStart(flashbackSCN IN number,
6109 flashbackTime IN date,
6110 scnBased IN binary_integer,
6111 toBefore IN binary_integer,
6112 resetSCN IN number,
6113 resetTime IN date);
6114 -- Following parameters are added:
6115 --
6116 -- resetSCN, resetTime - resetlogs branch to which to flashback. Pass a
6117 -- non-NULL value when flashbacked via RESTORE POINT.
6118 -- If SCN/TIME/LOGSEQ was used, pass it as NULL to
6119 -- indicate current incarnation.
6120
6121 PROCEDURE backupSetDataFile( set_stamp OUT number
6122 ,set_count OUT number
6123 ,nochecksum IN boolean default FALSE
6124 ,tag IN varchar2 default NULL
6125 ,incremental IN boolean default FALSE
6126 ,backup_level IN binary_integer default 0
6127 ,check_logical IN boolean default FALSE
6128 ,keep_options IN binary_integer default 0
6129 ,keep_until IN number default 0
6130 ,imagcp IN boolean
6131 ,convertto IN boolean
6132 ,convertfr IN boolean
6133 ,pltfrmto IN binary_integer
6134 ,pltfrmfr IN binary_integer
6135 ,sameen IN boolean
6136 ,convertdb IN boolean);
6137 -- Description and return values can be found with original declaration
6138 -- above. New parameters
6139 --
6140 -- convertdb
6141 -- If TRUE indciates this is doing "convert database"
6142 --
6143
6144 PROCEDURE switchTempfile(tsnum IN number,
6145 tsname IN varchar2,
6146 tfnum IN number,
6147 tfname IN varchar2,
6148 create_time IN date,
6149 create_scn IN number,
6150 blocks IN number,
6151 blocksize IN binary_integer,
6152 rfnum IN number,
6153 exton IN boolean,
6154 isSFT IN boolean,
6155 maxsize IN number,
6156 nextsize IN number);
6157 -- This procedure renames a tempfile record in controlfile section. If
6158 -- tempfile record doesn't exist, then it will add it to. If corresponding
6159 -- tablespace record doesn't exists, then it will also
6160 -- add it to fix controlfile.
6161 --
6162 -- Input parameters:
6163 -- tsnum - tablespace number (same as ts# in data dict)
6164 -- tsname - tablespace name
6165 -- tfnum - temporary file number
6166 -- tfname - temporary file name
6167 -- create_time - its creation time
6168 -- create_scn - and its creation scn
6169 -- blocks - creation file size in # logical blocks
6170 -- blocksize - logical block size for file
6171 -- rfnum - file's tablespace relative file number
6172 -- exton - TRUE - file autoextensible. Otherwise, FALSE
6173 -- isSFT - TRUE - single file tablespace. Otherwise, FALSE
6174 -- maxsize - maximum size to which file can extend in # logical blocks
6178 ,omfname OUT varchar2
6175 -- nextsize - incremental size of file expansion in # logical blocks
6176
6177 PROCEDURE getOMFFileName(tsname IN varchar2
6179 ,isTemp IN boolean);
6180
6181 -- This procedure returns an OMF file name for a datafile in the given
6182 -- tablespace. The name is suitable for passing to create. The name
6183 -- will have a "%u" in it, which will get replaced when the file is created.
6184 --
6185 -- Input parameters:
6186 -- tsname
6187 -- The name of the file's tablespace.
6188 -- Output parameters:
6189 -- omfname
6190 -- An OMF file name template for a datafile in the given
6191 -- tablespace.
6192 -- Exceptions:
6193
6194
6195 PROCEDURE genTransportScript( tscname IN varchar2 default NULL
6196 ,pfformat IN varchar2 default NULL
6197 ,rmtscname IN varchar2 default NULL
6198 ,pfname OUT varchar2
6199 ,newtscname OUT varchar2
6200 ,newrmtscname OUT varchar2);
6201
6202
6203 -- This procedure generates the transport script, pfile and covnert script
6204 -- for transportable db
6205 --
6206 -- Input parameters:
6207 -- tscname
6208 -- The name of the transport script.
6209 -- pfformat
6210 -- The format for the pfile specified by users.
6211 -- rmtscname
6212 -- The name of remote transport script(convert script).
6213 -- pfname
6214 -- The name of generated pfile
6215 -- newtscfname
6216 -- Formatted transport script name
6217 -- newrmtscname
6218 -- Formatted remote transport script name(convert script).
6219
6220 PROCEDURE TransportDBLock(newdbname IN varchar2 default NULL);
6221 -- This procedure sets a lock on transportable db coontext
6222 -- The name of the new database to be created on the target platform
6223 -- can be passed to transportable db context, too.
6224 --
6225 -- Input parameters:
6226 -- newdbname
6227 -- The name of the new database to be created on the target platform.
6228
6229 PROCEDURE TransportDBUnlock;
6230 -- This procedure frees the lock on transportable db context
6231
6232 PROCEDURE backupSetDataFile( set_stamp OUT number
6233 ,set_count OUT number
6234 ,nochecksum IN boolean default FALSE
6235 ,tag IN varchar2 default NULL
6236 ,incremental IN boolean default FALSE
6237 ,backup_level IN binary_integer default 0
6238 ,check_logical IN boolean default FALSE
6239 ,keep_options IN binary_integer default 0
6240 ,keep_until IN number default 0
6241 ,imagcp IN boolean
6242 ,convertto IN boolean
6243 ,convertfr IN boolean
6244 ,pltfrmto IN binary_integer
6245 ,pltfrmfr IN binary_integer
6246 ,sameen IN boolean
6247 ,convertdb IN boolean
6248 ,nocatalog IN boolean);
6249
6250 -- nocatalog
6251 -- If TRUE, do not record the backup meta information in repository.
6252
6253 FUNCTION cfileCalcSizeList(
6254 num_ckptprog_recs IN binary_integer default 0
6255 ,num_thread_recs IN binary_integer default 0
6256 ,num_logfile_recs IN binary_integer default 0
6257 ,num_datafile_recs IN binary_integer default 0
6258 ,num_filename_recs IN binary_integer default 0
6259 ,num_tablespace_recs IN binary_integer default 0
6260 ,num_tempfile_recs IN binary_integer default 0
6261 ,num_rmanconfiguration_recs IN binary_integer default 0
6262 ,num_loghistory_recs IN binary_integer default 0
6263 ,num_offlinerange_recs IN binary_integer default 0
6264 ,num_archivedlog_recs IN binary_integer default 0
6265 ,num_backupset_recs IN binary_integer default 0
6266 ,num_backuppiece_recs IN binary_integer default 0
6267 ,num_backedupdfile_recs IN binary_integer default 0
6268 ,num_backeduplog_recs IN binary_integer default 0
6269 ,num_dfilecopy_recs IN binary_integer default 0
6270 ,num_bkdfcorruption_recs IN binary_integer default 0
6271 ,num_dfcopycorruption_recs IN binary_integer default 0
6272 ,num_deletedobject_recs IN binary_integer default 0
6273 ,num_proxy_recs IN binary_integer default 0
6274 ,num_reserved4_recs IN binary_integer default 0
6275 ,num_db2_recs IN binary_integer
6276 ,num_incarnation_recs IN binary_integer
6277 ,num_flashback_recs IN binary_integer
6278 ,num_rainfo_recs IN binary_integer
6279 ,num_instrsvt_recs IN binary_integer
6280 ,num_agedfiles_recs IN binary_integer
6281 ,num_rmanstatus_recs IN binary_integer
6285 ,num_sdm_recs IN binary_integer
6282 ,num_threadinst_recs IN binary_integer
6283 ,num_mtr_recs IN binary_integer
6284 ,num_dfh_recs IN binary_integer
6286 ,num_grp_recs IN binary_integer
6287 ,num_rp_recs IN binary_integer)
6288 return binary_integer;
6289
6290 -- Description and return values can be found with original declaration
6291 -- above. New parameter:
6292 --
6293 -- num_sdm_recs
6294 -- Number of KCCDESDM records - Standby Database Matrix
6295 -- num_grp_recs
6296 -- Number of KCCDERSP records - Guaranteed restore points
6297 -- num_rp_recs
6298 -- Number of KCCDENRR records - restore points.
6299
6300 PROCEDURE commitRmanStatusRow( row_id IN number
6301 ,row_stamp IN number
6302 ,mbytes IN number
6303 ,status IN binary_integer
6304 ,ibytes IN number
6305 ,obytes IN number
6306 ,odevtype IN varchar2);
6307 -- Following parameters are added:
6308 -- ibytes - input bytes
6309 -- obytes - output bytes
6310
6311 PROCEDURE createRmanStatusRow( level IN binary_integer
6312 ,parent_id IN number
6313 ,parent_stamp IN number
6314 ,status IN binary_integer
6315 ,command_id IN varchar2
6316 ,operation IN varchar2
6317 ,row_id OUT number
6318 ,row_stamp OUT number
6319 ,flags IN binary_integer);
6320 -- Following parameters are added:
6321 -- flags - indicating user interested properties for the command
6322 -- like, DATABASE, DATAFILE, ARCHIVELOG, SPFILE, CONTROLFILE,
6323 -- OPTIMIZATION, etc.
6324 -- see krmk.h / kcc3.h for details on bits usage of the flag
6325
6326 PROCEDURE createRmanOutputRow( l0row_id IN number
6327 ,l0row_stamp IN number
6328 ,row_id IN number
6329 ,row_stamp IN number
6330 ,txt IN varchar2
6331 ,sameline IN binary_integer);
6332
6333 -- Following parameters are added:
6334 -- sameline - indicating client requested output to go to same previous
6335 -- line.
6336
6337 FUNCTION genPieceName(pno IN number
6338 ,set_count IN number
6339 ,set_stamp IN number
6340 ,format IN varchar2
6341 ,copyno IN number
6342 ,devtype IN varchar2
6343 ,year IN binary_integer
6344 ,month IN binary_integer
6345 ,day IN binary_integer
6346 ,dbid IN number
6347 ,ndbname IN varchar2
6348 ,cfseq IN number
6349 ,fileno IN number
6350 ,tsname IN varchar2
6351 ,logseq IN varchar2
6352 ,logthr IN number
6353 ,imagcp IN boolean
6354 ,savepname IN boolean)
6355 return varchar2;
6356 -- New parameters for creating names:
6357 --
6358 -- savepname
6359 -- Save generated pname in SGA
6360
6361
6362 PROCEDURE backupPieceCreate( fname IN varchar2
6363 ,pieceno OUT binary_integer
6364 ,done OUT boolean
6365 ,handle OUT varchar2
6366 ,comment OUT varchar2
6367 ,media OUT varchar2
6368 ,concur OUT boolean
6369 ,params IN varchar2 default NULL
6370 ,media_pool IN binary_integer default 0
6371 ,reuse IN boolean default FALSE
6372 ,archlog_failover OUT boolean
6373 ,deffmt IN binary_integer
6374 ,recid OUT number
6375 ,stamp OUT number
6376 ,tag OUT varchar2
6377 ,docompress IN boolean
6378 ,dest IN binary_integer);
6379 -- Description and return values can be found with original declaration
6380 -- above. New parameter:
6381 --
6382 -- dest - When TRUE (non-zero), format specified is a OMF destination.
6383 -- The output file must be created as a OMF name with the format
6384 -- string as OMF destination. Otherwise, FALSE.
6385
6386 PROCEDURE OracleSbtVersion( isOracle OUT boolean
6387 ,version OUT varchar2);
6388 -- Checks if our SBT tape channel is using Oracle Backup.
6389 -- If so, sets isOracle to TRUE and returns the version number as a
6390 -- text string in the form of "AAA.BBB.CCC.DDD".
6391 --
6392 --
6396 -- version
6393 -- Input parameters:
6394 -- isOracle
6395 -- Is this SBT channel using Oracle Backup?
6397 -- The textual representation of the version string.
6398 -- Returns:
6399 -- If isOracle is TRUE, then version will contain a string in the form
6400 -- of "A.B.C.D", where each of A,B,C,D can be between 0 and 255. If
6401 -- isOracle is false, then the value of this version is undefined.
6402 --
6403 -- Gets the next result
6404 PROCEDURE validationNextResult( handle OUT varchar2
6405 ,recid OUT number
6406 ,set_stamp OUT number
6407 ,set_count OUT number
6408 ,pieceno OUT number
6409 ,msca OUT binary_integer
6410 ,m1 OUT varchar2
6411 ,m2 OUT varchar2
6412 ,m3 OUT varchar2
6413 ,m4 OUT varchar2
6414 ,m5 OUT varchar2
6415 ,m6 OUT varchar2
6416 ,m7 OUT varchar2
6417 ,m8 OUT varchar2
6418 ,m9 OUT varchar2
6419 ,m10 OUT varchar2
6420 ,m11 OUT varchar2
6421 ,m12 OUT varchar2
6422 ,m13 OUT varchar2
6423 ,m14 OUT varchar2
6424 ,m15 OUT varchar2
6425 ,m16 OUT varchar2
6426 ,m17 OUT varchar2
6427 ,m18 OUT varchar2
6428 ,m19 OUT varchar2
6429 ,m20 OUT varchar2
6430 ,attributes OUT binary_integer);
6431 -- Description and return values can be found with original declaration
6432 -- above. New parameters
6433 --
6434 -- attributes
6435 -- Flags to indicate specific attribute of backup file. These constants
6436 -- are bit-flags, so bitand() must be used to decode the value.
6437 -- Values in this attributes are set by OSDS.
6438 --
6439 -- ATTRIBUTE_REMOTE bit set indicates that specific backup file
6440 -- is remote.
6441 ATTRIBUTE_REMOTE constant binary_integer := 1;
6442 -- ATTRIBUTE_NOTFOUND bit set indicates that specific backup file
6443 -- was not found.
6444 ATTRIBUTE_NOTFOUND constant binary_integer := 2;
6445
6446 PROCEDURE validationValidate(flags IN binary_integer);
6447 -- does the actual validation
6448 -- Description and return values can be found with original declaration
6449 -- above. New parameters
6450 --
6451 -- flags
6452 -- flags for specific request.
6453 --
6454 -- VVFLAGS_RECALL bit flag indicate that server should request SBT
6455 -- to recall remote backups for current set of backup files.
6456 VVFLAGS_RECALL constant binary_integer := 1;
6457
6458 PROCEDURE bmrStart( save_all_blocks IN boolean,
6459 save_final_blocks IN boolean,
6460 nofileupdate IN boolean,
6461 doclear IN boolean);
6462 -- Description and return values can be found with original declaration
6463 -- above. New parameter:
6464 --
6465 -- doclear - actually corrupt the block instead of fixing it
6466 -- used as an alternative to bbed
6467 --
6468
6469
6470 PROCEDURE backupPieceRestore(bpname IN varchar2
6471 ,fname IN varchar2
6472 ,handle OUT varchar2
6473 ,recid OUT number
6474 ,stamp OUT number
6475 ,tag IN varchar2 default NULL
6476 ,reuse IN boolean default FALSE
6477 ,check_logical IN boolean);
6478 -- Input parameters:
6479 -- bpname
6480 -- Operating system file name of the existing backup piece. This will be
6481 -- read and copied to sequential media.
6482 -- fname
6483 -- Filename of the backup piece to be created. This will be translated
6484 -- into a file handle after the piece is created.
6485 -- tag
6486 -- The tag stored in the file header of the copied and backed up files,
6487 -- and also in the controlfile records describing those files.
6488 -- reuse
6489 -- indicates if to reuse the output file if exists.
6490 -- check_logical
6491 -- if set to true indicates that besides physical block validations,
6492 -- logical validations will be performed on each block
6493 -- Output parameters:
6494 -- handle
6495 -- The handle for the backup piece that was created. This is a permanent
6496 -- name that can be used to read this sequential file for restore. It
6497 -- can only be used with the same device type that was allocated at
6498 -- this call.
6499 -- recid
6500 -- This is the ID of the record in the controlfile where the
6501 -- information about this backup piece was recorded. It can be used as
6502 -- the primary key to query V$BACKUP_PIECE.
6503 -- stamp
6507 -- time.
6504 -- This is a number that can be used to verify that the row in
6505 -- V$BACKUP_PIECE is really for this backup piece. The stamp combined
6506 -- with recid makes a key that is unique for this backup piece for all
6508 -- Exceptions:
6509 -- NO-INPUT-FILENAME (ora-19605)
6510 -- src_name must be assigned a non-NULL string in copyControlFile.
6511 -- NO-OUTPUT-FILENAME (ora-19574)
6512 -- dest_name must be assigned a non-NULL string in copyControlFile.
6513 -- NAME-TOO-LONG (ora-19704)
6514 -- The specified file name is longer than the port-specific
6515 -- maximum file name length.
6516 -- TAG-TOO-LONG (ora-19705)
6517 -- The tag is longer than the port-specific maximum.
6518 -- DEVICE-PARM-TOO-LONG (ora-19702)
6519 -- The device parameter is longer than the port-specific maximum.
6520 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
6521 -- The database is in the process of being opened, closed, mounted,
6522 -- or dismounted.
6523 -- DATABASE-NOT-MOUNTED (ora-1507)
6524 -- The database is not mounted.
6525 -- FILE-IN-USE (ora-19584)
6526 -- The specified output file is already in use by the database as a
6527 -- datafile or online redo log.
6528 -- DEVICE-NOT-ALLOCATED (ora-19569)
6529 -- This session does not have a device allocated.
6530 -- CANT-IDENTIFY-FILE (ora-19505)
6531 -- The file can not be opened.
6532 -- END-OF-VOLUME (ora-19630)
6533 -- end-of-volume was encountered while copying the backup piece.
6534 -- CORRUPT_BLOCK (ora-19599)
6535 -- A corrupt block was encountered. Corrupt blocks are not tolerated
6536 -- in backup pieces.
6537 -- NOT-A-BACKUP-PIECE (ora-19608)
6538 -- The input file is not recognizable as a backup piece.
6539 -- CORRUPT-DIRECTORY (ora-19610)
6540 -- The backup piece directory is corrupt.
6541 -- IO-ERROR
6542 -- An error occured attempting to read the input file.
6543 -- CREATE-ERROR
6544 -- An error was reported by the OSD to create the sequential file.
6545 -- WRITE-ERROR
6546 -- An error was reported by the sequential write OSD.
6547
6548 PROCEDURE SetParms(p0 IN number DEFAULT NULL,
6549 p1 IN number DEFAULT NULL,
6550 p2 IN number DEFAULT NULL,
6551 p3 IN number DEFAULT NULL,
6552 p4 IN number DEFAULT NULL,
6553 p5 IN varchar2 DEFAULT NULL,
6554 p6 IN varchar2 DEFAULT NULL,
6555 p7 IN varchar2 DEFAULT NULL,
6556 p8 IN varchar2 DEFAULT NULL,
6557 p9 IN varchar2 DEFAULT NULL);
6558
6559 PROCEDURE SetTableSpaceAttr(code IN number,
6560 tsid IN binary_integer,
6561 clear IN binary_integer,
6562 onoff IN binary_integer);
6563
6564 TBS_ATTR_EXCLUDE constant binary_integer := 0;
6565 TBS_ATTR_ENCRYPT constant binary_integer := 1;
6566
6567 PROCEDURE DoAutoBackup(ncopies OUT binary_integer
6568 ,cfaudate IN DATE default NULL
6569 ,seq IN binary_integer default NULL
6570 ,format IN varchar2 default NULL
6571 ,p1 IN binary_integer
6572 ,p2 IN binary_integer
6573 ,p3 IN binary_integer
6574 ,p4 IN varchar2);
6575 -- Description and return values can be found with original declaration
6576 -- above. New parameters
6577 --
6578 -- p1, p2, p3, p4 additional attributes to DoAutoBackup
6579
6580 FUNCTION getDiskGroupName(fname IN varchar2) return varchar2;
6581
6582 -- Given an ASM filename, return the disk group name.
6583 --
6584 -- Input parameters:
6585 -- fname - ASM filename
6586 --
6587 -- Returns the diskgroup name
6588
6589 PROCEDURE backupPieceCreate( fname IN varchar2
6590 ,pieceno OUT binary_integer
6591 ,done OUT boolean
6592 ,handle OUT varchar2
6593 ,comment OUT varchar2
6594 ,media OUT varchar2
6595 ,concur OUT boolean
6596 ,params IN varchar2 default NULL
6597 ,media_pool IN binary_integer default 0
6598 ,reuse IN boolean default FALSE
6599 ,archlog_failover OUT boolean
6600 ,deffmt IN binary_integer
6601 ,recid OUT number
6602 ,stamp OUT number
6603 ,tag OUT varchar2
6604 ,docompress IN boolean
6605 ,dest IN binary_integer
6606 ,post10_2 IN boolean);
6607 -- Description and return values can be found with original declaration
6608 -- above. New parameter:
6609 --
6610 -- post10_2 - If TRUE (non-zero), this means that the rman client is from
6611 -- release 10.2 or higher. Therefore, the krbbx context should
6612 -- not be cleared by the backupPieceCreate procedure. Use the
6613 -- backupCancel procedure for cleanup.
6614
6618 -- Gets a numeric value from the backup piece context.
6615 PROCEDURE pieceContextGetNumber( parmid IN binary_integer
6616 ,value OUT binary_integer);
6617
6619 --
6620 -- Input parameters:
6621 -- parmid
6622 -- Parameter to be retrieved.
6623 --
6624 -- Output parameters:
6625 -- value
6626 -- Value of parameter to be retrieved.
6627 --
6628 -- The valid list of parmid's follows.
6629
6630 -- Get the value of the KRCBAD_KRBBX flag.
6631 SIGNAL_CHANGE_TRACKING_ERROR constant binary_integer := 0;
6632
6633
6634 FUNCTION validateArchivedLog(recid IN number
6635 ,stamp IN number
6636 ,fname IN varchar2
6637 ,thread IN number
6638 ,sequence IN number
6639 ,resetlogs_change IN number
6640 ,first_change IN number
6641 ,blksize IN number
6642 ,signal IN binary_integer
6643 ,terminal IN binary_integer)
6644 return binary_integer;
6645
6646 -- Description and return values can be found with original declaration
6647 -- above. New parameters
6648 --
6649 -- terminal : Log being validated is terminal EOR generated during
6650 -- standby failover operation.
6651
6652 FUNCTION networkFileTransfer(dbname IN varchar2
6653 ,username IN varchar2 default NULL
6654 ,passwd IN varchar2 default NULL
6655 ,srcfile IN varchar2
6656 ,destfile IN varchar2
6657 ,operation IN varchar2)
6658 RETURN boolean;
6659 -- Copies files from/to remote database instnaces.
6660 -- Input parameters:
6661 -- dbname - remote database name
6662 -- username - user name
6663 -- passwd - password
6664 -- srcfile - source file
6665 -- destfile - destination file
6666 -- operation - "read" or "write"
6667 -- Returns TRUE if succsessful. Otherwise, FALSE.
6668
6669 PROCEDURE IncrementRecordStamp (rectype IN binary_integer,
6670 recid IN number,
6671 stamp IN number);
6672
6673 --
6674 -- Increment record stamp for given record type.
6675 --
6676 -- Input parameters:
6677 -- rectype
6678 -- The record type whose record stamp needs to be incremented.
6679 -- recid, stamp
6680 -- The record-id, stamp to identify the record.
6681
6682 PROCEDURE Fault_Injector(funcNo IN number,
6683 funcErr IN number,
6684 funcCounter IN number DEFAULT 1);
6685
6686 --
6687 -- Use this function to simulate any oracle error in a backup_restore
6688 -- function. Used for testing
6689 --
6690 -- Input parameters
6691 -- funcNo
6692 -- The function number (based on the number it uses in icdstart)
6693 -- for which the error will be signaled
6694 -- funcErr
6695 -- The oracle error number to signal
6696 -- funcCounter
6697 -- The number of times the function has to be called before the
6698 -- error is signaled
6699
6700 PROCEDURE initMSB( dfnumber IN number
6701 ,file_size OUT number
6702 ,set_stamp OUT number
6703 ,set_count OUT number);
6704
6705 -- Initialize multi-section backup processing for the specified file.
6706 --
6707 -- dfnumber: file number that will be backed up in multiple sections
6708 -- file_size: file size that needs to be backed up
6709
6710 PROCEDURE setMSB( dfnumber IN number
6711 ,section_size IN number
6712 ,first_section IN number
6713 ,section_count IN number
6714 ,set_stamp IN number
6715 ,set_count IN number
6716 ,pieceno IN number
6717 ,piececnt IN number);
6718
6719 -- Set section size for multi-section backup
6720 --
6721 -- section_size: number of blocks in one section
6722 -- first_section: first section to back up
6723 -- section_count: number of sections to back up
6724 -- set_stamp: set_stamp to use for this backup piece
6725 -- set_count: set_count to use for this backup piece
6726 -- pieceno: piece number to use for this backup piece
6727 -- piececnt: total number of pieces in this multi-section backup set
6728
6729 PROCEDURE initMSR( dfnumber IN number
6730 ,fname OUT varchar2);
6731
6732 -- Initialize file for multi-section full restore
6733 --
6734 -- dfnumber: file being restored
6735 -- fname: name of file
6736
6737 -- Generates an archived log file name valid for a log file with
6738 -- the given thread, sequence, resetlog id. Other values such as
6739 -- db id, activation number, log archive format and destination are
6740 -- taken from the mounted or open instance.
6741 --
6742 -- Input parameters:
6743 -- thread
6744 -- thread number for the log file name
6745 -- sequence
6746 -- sequence number for the log file name
6750 -- Output parameters:
6747 -- rls_id
6748 -- resetlog id for the log file name
6749 --
6751 -- arcName
6752 -- Name of archivelog to be created.
6753 --
6754 -- The valid list of parmid's follows.
6755
6756 PROCEDURE getArcFileName( thread IN number
6757 ,sequence IN number
6758 ,rls_id IN number
6759 ,arcName OUT varchar2);
6760
6761 -- Description and return values can be found with original declaration
6762 -- above. New parameters:
6763 --
6764 -- netalias - SQL*Net service name for remote creations
6765 -- compressalg - compression algorithm
6766 --
6767 PROCEDURE backupPieceCreate( fname IN varchar2
6768 ,pieceno OUT binary_integer
6769 ,done OUT boolean
6770 ,handle OUT varchar2
6771 ,comment OUT varchar2
6772 ,media OUT varchar2
6773 ,concur OUT boolean
6774 ,params IN varchar2 default NULL
6775 ,media_pool IN binary_integer default 0
6776 ,reuse IN boolean default FALSE
6777 ,archlog_failover OUT boolean
6778 ,deffmt IN binary_integer
6779 ,recid OUT number
6780 ,stamp OUT number
6781 ,tag OUT varchar2
6782 ,docompress IN boolean
6783 ,dest IN binary_integer
6784 ,post10_2 IN boolean
6785 ,netalias IN varchar2
6786 ,compressalg IN varchar2);
6787
6788 PROCEDURE cfileMakeAndUseSnapshot( isstby IN boolean
6789 ,source_dbuname IN varchar2
6790 ,dest_cs IN varchar2
6791 ,source_cs IN varchar2
6792 ,for_resync IN boolean);
6793
6794 -- Description and return values can be found with original declaration
6795 -- above.
6796 --
6797 -- The new parameters provide the capability for an instance with
6798 -- connect string "dest_cs" to request the remote instance with the
6799 -- connect string "source_cs" for its current controlfile.
6800 -- The remote instance will copy its current controlfile to the
6801 -- local instance's snapshot controlfile location.
6802 -- The db_unique_name of the remote instance is passed to ensure
6803 -- that we're copying the controlfile from the correct instance .
6804 --
6805 -- New parameters:
6806 -- source_dbuname - db_unique_name of remote database
6807 -- source_cs - SQL*Net service name for database whose CF is to be
6808 -- copied.
6809 -- dest_cs - SQL*Net service name for database which will receive
6810 -- the controlfile.
6811 -- for_resync - snapshot is created for RMAN resync operation
6812 -- NOTE: isstby is not used for remote controlfile copy operations.
6813
6814 PROCEDURE bmrRestoreFromFlashback( limitSCN IN number
6815 ,restoredNum OUT binary_integer);
6816
6817 -- Restore blocks from flashback logs. This function searches
6818 -- flashback logs during block media recovery and restores them
6819 -- if found. BMR conversation should be active when called
6820 --
6821 -- Input parameters:
6822 -- limitSCN
6823 -- Stop SCN of the flashback log search
6824 --
6825 -- Output parameters:
6826 -- restoredNum
6827 -- Number of restored blocks
6828
6829 PROCEDURE backupValidate(archlog_failover OUT boolean
6830 ,nocleanup IN boolean);
6831 -- Description can be found with original declaration above.
6832 --
6833 -- New parameters
6834 -- nocleanup: Pass it as TRUE if to keep backup conversation context
6835 -- at end of successful validation. Otherwise, FALSE.
6836 --
6837
6838 PROCEDURE getBlockStat(blockStatTable OUT blockStatTable_t);
6839 --
6840 -- Copy all the statictics that was collected during a backup command.
6841 --
6842 -- Parameters:
6843 -- blockStatTable: copy block statistics into this table.
6844 --
6845
6846 PROCEDURE validateBlock(blockRangeTable IN blockRangeTable_t);
6847 -- validateBlock adds the specified block range to the backup
6848 -- context for validation.
6849
6850 PROCEDURE backupSetDataFile( set_stamp OUT number
6851 ,set_count OUT number
6852 ,nochecksum IN boolean default FALSE
6853 ,tag IN varchar2 default NULL
6854 ,incremental IN boolean default FALSE
6855 ,backup_level IN binary_integer default 0
6856 ,check_logical IN boolean default FALSE
6857 ,keep_options IN binary_integer default 0
6858 ,keep_until IN number default 0
6859 ,imagcp IN boolean
6860 ,convertto IN boolean
6864 ,sameen IN boolean
6861 ,convertfr IN boolean
6862 ,pltfrmto IN binary_integer
6863 ,pltfrmfr IN binary_integer
6865 ,convertdb IN boolean
6866 ,nocatalog IN boolean
6867 ,validate IN boolean
6868 ,validateblk IN boolean
6869 ,hdrupd IN OUT boolean);
6870
6871 -- Description can be found with original declaration above.
6872 --
6873 -- New parameters
6874 -- validate: Pass it as TRUE if this is a validate conversation context
6875 -- validateblk: Pass it as TRUE if this is a validate block conversation
6876 -- hdrupd: If FALSE as input, header update of locally managed files
6877 -- will be not performed. If set to TRUE as input, datafile
6878 -- header checks will be done and hdrupd will be set accordingly.
6879 -- If TRUE as output, then datafile header update is required.
6880 --
6881
6882 PROCEDURE backupSetArchivedLog( set_stamp OUT number
6883 ,set_count OUT number
6884 ,nochecksum IN boolean default FALSE
6885 ,tag IN varchar2
6886 ,imagcp IN boolean
6887 ,validate IN boolean);
6888
6889 -- Description can be found with original declaration above.
6890 --
6891 -- New parameters
6892 -- validate: Pass it as TRUE if this is a validate conversation context
6893 --
6894
6895 -- Obsoleted in 12.1 -- New record sections are not updated anymore
6896
6897 FUNCTION cfileCalcSizeList(
6898 num_ckptprog_recs IN binary_integer default 0
6899 ,num_thread_recs IN binary_integer default 0
6900 ,num_logfile_recs IN binary_integer default 0
6901 ,num_datafile_recs IN binary_integer default 0
6902 ,num_filename_recs IN binary_integer default 0
6903 ,num_tablespace_recs IN binary_integer default 0
6904 ,num_tempfile_recs IN binary_integer default 0
6905 ,num_rmanconfiguration_recs IN binary_integer default 0
6906 ,num_loghistory_recs IN binary_integer default 0
6907 ,num_offlinerange_recs IN binary_integer default 0
6908 ,num_archivedlog_recs IN binary_integer default 0
6909 ,num_backupset_recs IN binary_integer default 0
6910 ,num_backuppiece_recs IN binary_integer default 0
6911 ,num_backedupdfile_recs IN binary_integer default 0
6912 ,num_backeduplog_recs IN binary_integer default 0
6913 ,num_dfilecopy_recs IN binary_integer default 0
6914 ,num_bkdfcorruption_recs IN binary_integer default 0
6915 ,num_dfcopycorruption_recs IN binary_integer default 0
6916 ,num_deletedobject_recs IN binary_integer default 0
6917 ,num_proxy_recs IN binary_integer default 0
6918 ,num_reserved4_recs IN binary_integer default 0
6919 ,num_db2_recs IN binary_integer
6920 ,num_incarnation_recs IN binary_integer
6921 ,num_flashback_recs IN binary_integer
6922 ,num_rainfo_recs IN binary_integer
6923 ,num_instrsvt_recs IN binary_integer
6924 ,num_agedfiles_recs IN binary_integer
6925 ,num_rmanstatus_recs IN binary_integer
6926 ,num_threadinst_recs IN binary_integer
6927 ,num_mtr_recs IN binary_integer
6928 ,num_dfh_recs IN binary_integer
6929 ,num_sdm_recs IN binary_integer
6930 ,num_grp_recs IN binary_integer
6931 ,num_rp_recs IN binary_integer
6932 ,num_bcr_recs IN binary_integer
6933 ,num_acm_recs IN binary_integer
6934 ,num_rlr_recs IN binary_integer)
6935 return binary_integer;
6936
6937 -- Description and return values can be found with original declaration
6938 -- above. New parameter:
6939 --
6940 -- num_bcr_recs
6941 -- Number of KCCDEBCR records - Block Corruption Records
6942 -- num_acm_recs
6943 -- Number of KCCDEACM records
6944 -- num_rlr_recs
6945 -- Number of KCCDERLR records
6946
6947 PROCEDURE VssBackedRecord (rectype IN binary_integer,
6948 recid IN number,
6949 stamp IN number);
6950
6951 --
6952 -- All the record with stamp less than input stamp value are
6953 -- backed up by VSS infrastructure.
6954 --
6955 -- Input parameters:
6956 -- rectype
6957 -- The record type that are backed by VSS.
6958 -- recid, stamp
6959 -- The record-id, stamp to identify the last record.
6960
6961
6962 PROCEDURE backupSetArchivedLog( set_stamp OUT number
6963 ,set_count OUT number
6964 ,nochecksum IN boolean default FALSE
6965 ,tag IN varchar2
6969 ,keep_until IN number);
6966 ,imagcp IN boolean
6967 ,validate IN boolean
6968 ,keep_options IN binary_integer
6970 -- Description and return values can be found with original declaration
6971 -- above.
6972 -- New parameters
6973 -- keep_options: Bit mask indicating LOGS/NOLOGS/BACKUP_LOGS(consistent)
6974 -- keep_until: Time when the backup expires
6975
6976
6977 PROCEDURE ir_icd_start(fn IN number);
6978 --
6979 -- This procedure is called at begining of DBMS_IR interface. It is same
6980 -- as icdStart in prvtbkrs.pls that increments the RPC count and sets the
6981 -- v$session.action field to STARTED.
6982 -- This is used so that RMAN can issue RPC call against DBMS_IR interface
6983 -- and DBMS_BACKUP_RESTORE in the same session.
6984 --
6985 -- Input parameters:
6986 --
6987 -- fn - unique number that identifies the function call.
6988 --
6989
6990 PROCEDURE ir_icd_finish;
6991 --
6992 -- This procedure is called at end of DBMS_IR interface. It is same as
6993 -- icdFinish in prvtbkrs.pls that sets the current RPC count as FINISHED
6994 -- in v$session.action.
6995 -- This is used so that RMAN can issue RPC call against DBMS_IR interface
6996 -- and DBMS_BACKUP_RESTORE in the same session.
6997 --
6998
6999 FUNCTION UpdateHeaders return boolean;
7000 --
7001 -- This procedure is called by rman when datafile headers of locally
7002 -- managed datafiles need to be updated after the database compatibility
7003 -- has been upgraded to 10.2 or above.
7004 -- This procedure can take several minutes for thousands of datafiles.
7005 -- Only one channel update the headers while the other channels block
7006 -- waiting for the enqueue.
7007 -- RETURNS
7008 -- TRUE if no errors during update
7009 -- FALSE otherwise
7010 --
7011
7012 PROCEDURE cleanupBackupRecords;
7013 --
7014 -- This procedure is called by rman at end of delete/uncatalog command to
7015 -- mark bdf/bsf/brl/bs as deleted for which no backuppieces exists. This
7016 -- would save the processing time of query in nocatalog.
7017 --
7018
7019 PROCEDURE readArchivedLogHeader( fname IN varchar2
7020 ,full_name OUT varchar2
7021 ,thread OUT number
7022 ,sequence OUT number
7023 ,first_change OUT number
7024 ,next_change OUT number
7025 ,resetlogs_change OUT number
7026 ,resetlogs_time OUT date);
7027
7028 -- This procedure reads the header of a archived redo log and returns
7029 -- thread, sequence, first_change# and next_change#. No controlfile record
7030 -- is added.
7031 --
7032 -- Input parameters:
7033 -- fname
7034 -- File name of the archived log to inspect. This name may not be
7035 -- useable by another process, so it will be expanded.
7036 -- Output parameters:
7037 -- full_name
7038 -- This is the fully expanded name of the file that was inspected. It
7039 -- will also appear in V$ARCHIVED_LOG.
7040 -- thread, sequence, first_change, next_change
7041 -- thread, sequence, first_change and next_change present in
7042 -- archivelog header.
7043 -- resetlogs_change and resetlogs_time
7044 -- resetlogs information stored in archivelog header.
7045
7046 PROCEDURE processSearchFileTable(catalog IN boolean,
7047 implicit IN binary_integer,
7048 forftype IN binary_integer);
7049 --
7050 -- Description can be found with original declaration above.
7051 --
7052 -- New parameters
7053 -- forftype: one of KSFD filetypes to process. If all supported
7054 -- filetype has to be processed, then pass it as UB2MAXVAL.
7055 --
7056
7057 FUNCTION validateArchivedLog(recid IN number
7058 ,stamp IN number
7059 ,fname IN varchar2
7060 ,thread IN number
7061 ,sequence IN number
7062 ,resetlogs_change IN number
7063 ,first_change IN number
7064 ,blksize IN number
7065 ,signal IN binary_integer
7066 ,terminal IN binary_integer
7067 ,foreignal IN binary_integer)
7068 return binary_integer;
7069
7070 -- Description and return values can be found with original declaration
7071 -- above. New parameters
7072 --
7073 -- foreignal - If non-zero, then operate on foreign archived log entry.
7074 -- i.e kccrl that corresponds to v$foreign_archived_log
7075 --
7076
7077 PROCEDURE changeArchivedLog(recid IN number
7078 ,stamp IN number
7079 ,fname IN varchar2
7080 ,thread IN number
7081 ,sequence IN number
7082 ,resetlogs_change IN number
7083 ,first_change IN number
7084 ,blksize IN number
7088
7085 ,new_status IN varchar2
7086 ,force IN binary_integer
7087 ,foreignal IN binary_integer);
7089 -- Description and return values can be found with original and
7090 -- modified declaration above. New parameters
7091 --
7092 -- foreignal - If non-zero, then operate on foreign archived log entry.
7093 -- i.e kccrl that corresponds to v$foreign_archived_log
7094 --
7095
7096 PROCEDURE genTransportScript( tscname IN varchar2 default NULL
7097 ,pfformat IN varchar2 default NULL
7098 ,rmtscname IN varchar2 default NULL
7099 ,pfname OUT varchar2
7100 ,newtscname OUT varchar2
7101 ,newrmtscname OUT varchar2
7102 ,parallelism IN number);
7103
7104 -- Description and return values can be found with original and
7105 -- modified declaration above. New parameters
7106 --
7107 -- parallelism - sets that value in the conversion script
7108 --
7109
7110 FUNCTION remoteSQLExecute (source_dbuname IN varchar2,
7111 source_cs IN varchar2,
7112 stmt IN varchar2) return varchar2;
7113
7114
7115 -- This procedure allows executing a generic SQL statement at the
7116 -- remote database identified by source_cs connect string and source_dbuname
7117 -- db_unique_name parameter. It can be used to execute a simple SQL stmt
7118 -- or a SELECT statement that returns only one row, the value is returned
7119 -- by the function.
7120 --
7121 -- The length of column value can be up to 1024 characters.
7122 --
7123 --
7124 -- Input parameters:
7125 -- source_dbuname - db_unique_name of remote database
7126 -- source_cs - SQL*Net service name for database whose CF is to be
7127 -- copied. No userid/password should be provided.
7128 -- stmt - SQL Statement to execute at database instance
7129 -- identified by source_cs and source_dbuname.
7130
7131 FUNCTION getCkptSCN return number;
7132 -- This procedure is same getCkpt procedure described earlier, but returns
7133 -- only the ckp_scn.
7134
7135
7136 PROCEDURE backupControlFile( cfname IN varchar2 default NULL,
7137 isstby IN boolean,
7138 snapshot_cf IN boolean);
7139
7140 -- Description and return values can be found with original declaration
7141 -- above. New parameters:
7142 -- snapshot_cf
7143 -- Ignored if the cfname is not NULL.
7144 -- If TRUE, indicates that the controlfile to be added is a snapshot
7145 -- controlfile.
7146 -- If FALSE, indicates that the controlfile to be added is current
7147 -- controlfile and backup conversation must be a validate.
7148 --
7149
7150 PROCEDURE cleanupForeignArchivedLogs;
7151 -- This procedure will delete all foreign archivelogs created in FRA from
7152 -- disk as well as from the controlfile record. This is called when
7153 -- downgrading the database to pre 11 version. We need to cleanup all
7154 -- foreign archivedlogs because pre 11 version doesn't know how to manage
7155 -- foreign archivelogs in FRA.
7156
7157 FUNCTION networkFileTransfer(dbname IN varchar2
7158 ,username IN varchar2 default NULL
7159 ,passwd IN varchar2 default NULL
7160 ,role IN varchar2
7161 ,srcfile IN varchar2
7162 ,destfile IN varchar2
7163 ,operation IN varchar2
7164 ,retcode OUT number)
7165 RETURN boolean;
7166
7167 -- Description and return values can be found with origianl declaration above.
7168 -- New parameters
7169 --
7170 -- role - user role
7171 -- retcode - 0 if successful.
7172 -- 1 to indicate client eror
7173 -- 2 to indicate server error
7174
7175 PROCEDURE backupBackupPiece( bpname IN varchar2
7176 ,fname IN varchar2
7177 ,handle OUT varchar2
7178 ,comment OUT varchar2
7179 ,media OUT varchar2
7180 ,concur OUT boolean
7181 ,recid OUT number
7182 ,stamp OUT number
7183 ,tag IN varchar2 default NULL
7184 ,params IN varchar2 default NULL
7185 ,media_pool IN binary_integer default 0
7186 ,reuse IN boolean default FALSE
7187 ,check_logical IN boolean
7188 ,copyno IN binary_integer
7189 ,deffmt IN binary_integer
7190 ,copy_recid IN number
7191 ,copy_stamp IN number
7192 ,npieces IN binary_integer
7193 ,dest IN binary_integer);
7194 -- Description and return values can be found with original declaration
7195 -- above. New parameters
7196 --
7200
7197 -- dest - indicates if the format is a destination or format. If > 0,
7198 -- then format is the destination and OMF name must be generated.
7199 --
7201 FUNCTION genPieceName(pno IN number
7202 ,set_count IN number
7203 ,set_stamp IN number
7204 ,format IN varchar2
7205 ,copyno IN number
7206 ,devtype IN varchar2
7207 ,year IN binary_integer
7208 ,month IN binary_integer
7209 ,day IN binary_integer
7210 ,dbid IN number
7211 ,ndbname IN varchar2
7212 ,cfseq IN number
7213 ,fileno IN number
7214 ,tsname IN varchar2
7215 ,logseq IN varchar2
7216 ,logthr IN number
7217 ,imagcp IN boolean
7218 ,savepname IN boolean
7219 ,fname IN varchar2
7220 ,forcnvrt IN boolean)
7221 return varchar2;
7222 -- New parameters for creating names:
7223 --
7224 -- fname
7225 -- original file name
7226
7227 FUNCTION canKeepDatafiles RETURN binary_integer;
7228 -- This function checks if the compatible setting is high enough to allow
7229 -- the usage of KEEP DATAFILES subclause in DROP TABLESPACE. This function
7230 -- always returns TRUE since Oracle 12g.
7231
7232 PROCEDURE setDbUniqNameTspitr(dbuname IN varchar2);
7233 -- This procedure sets (or resets if dbuname is NULL) the sga variable
7234 -- krbdbutspitr, used to force a db_unique_name for ASM datafiles.
7235
7236 FUNCTION bmrRestoreFromStandby(validate IN boolean) return number;
7237
7238 -- Restore blocks from standby. This function establishes a connection
7239 -- to standby that is open during block media recovery and retrieves the
7240 -- block. BMR conversation should be active when called
7241 --
7242 -- Returns the number of restored blocks
7243 --
7244
7245 PROCEDURE flashbackControlfile(flashbackSCN IN number);
7246 --
7247 -- Flashes back the controlfile to a given SCN.
7248 --
7249 -- flashbackSCN
7250 -- scn to which to flashback. SCN is equivalent to the "until
7251 -- change" SCN for media recovery.
7252
7253 PROCEDURE inspectDataFileCopy( fname IN varchar2
7254 ,full_name OUT varchar2
7255 ,recid OUT number
7256 ,stamp OUT number
7257 ,tag IN varchar2 default NULL
7258 ,isbackup IN boolean default FALSE
7259 ,change_rdi IN boolean);
7260 -- New parameters:
7261 --
7262 -- change_rdi
7263 -- boolean value to indicate where recovery destination incarnation
7264 -- can be changed when inspecting this copy. This flag is set to FALSE
7265 -- normally when RMAN is inspecting datafilecopies for TSPITR.
7266
7267 FUNCTION DuplicateFileExists RETURN binary_integer;
7268 -- This function check if a ?/dbs/[email protected] file exists from
7269 -- a previous failed duplication.
7270 -- If it exists, it is read into the PGA memory of the channel and
7271 -- the function returns a non zero value.
7272 -- If the file does not exist, the function returns a zero value and
7273 -- the file is created in anticipation of a duplicate run.
7274 -- If there is any error during the opening or reading of the file, the
7275 -- failure is logged in the trace file but no error is signaled, however
7276 -- the return value will be zero.
7277
7278 FUNCTION getDuplicatedDatafilecopy(fno IN number,
7279 newname IN varchar2,
7280 crescn IN number,
7281 untscn IN number,
7282 dbid IN number,
7283 dbname IN varchar2,
7284 fname OUT varchar2,
7285 ckpscn OUT number)
7286 RETURN binary_integer;
7287 -- This function returns a non zero value if the filenumber is found in the
7288 -- ?/dbs/[email protected] file, the name in the datafilecopy
7289 -- matches the newname (for non-OMF newnames), the datafilecopy refers
7290 -- to an existing datafilecopy, the creation scn of the datafilecopy has
7291 -- to match the creation scn of the datafilecopy, the checkpoint of the
7292 -- datafilecopy is before the until scn, the dbid and the dbname of the
7293 -- datafilecopy should also match. If all these checks pass, then the
7294 -- datafilecopy name and checkpoint scn is returned to the caller together
7295 -- with the non-zero return value.
7296 -- If the filenumber is not found or the datafilecopy does not match the
7297 -- newname (for non-OMF newnames) or the datafilecopy fails any of the
7298 -- validations, then a zero value is returned and the fname/ckpscn parameters
7299 -- are invalid.
7300 -- Whenever an error is found during the lookup of the datafilecopy, the
7301 -- failure is logged in the trace file but no error is signaled, however
7302 -- the return value will be zero, fname/ckpscn in this case are invalid.
7303
7304 PROCEDURE writeDuplicatedDatafilecopy(fno IN number,
7305 fname IN varchar2);
7306 -- This procedure writes one record to the ?/dbs/[email protected] file and
7307 -- flushes the record to disk.
7311 PROCEDURE removeDuplicateFile;
7308 -- If the write fails the failure is logged in the trace file but no error
7309 -- is signaled.
7310
7312 -- This procedure removes the ?/dbs/[email protected] file.
7313 -- If the file cannot be removed the failure is logged in the trace
7314 -- file but no error is signaled.
7315
7316 FUNCTION checkCompressionAlg(algname IN varchar2, asofrel IN number,
7317 isvalid OUT binary_integer,
7318 mincompat OUT varchar2)
7319 return binary_integer;
7320 --
7321 -- Validates that the provided compression algorithm exists for the
7322 -- provided release
7323 -- Returns zero if algorithm name is not found for the specified release.
7324 -- Returns one if valid, output fileds are populated accordingly
7325 --
7326 -- algname
7327 -- name of the algorithm to validate
7328 -- asofrel
7329 -- release to which algname reffers, if 1 it indicates to use the
7330 -- release set in COMPRESSION_RELEASE initialization parameter
7331 -- isvalid
7332 -- 1 if algorithm is valid (compatible and aco requirements met)
7333 -- mincompat
7334 -- mimimum release compatibility required for this algorithm
7335
7336
7337 -- Constants for backupPieceCreate
7338 --
7339 LOPT_FALSE constant binary_integer := 1;
7340 LOPT_TRUE constant binary_integer := 2;
7341
7342 PROCEDURE backupPieceCreate( fname IN varchar2
7343 ,pieceno OUT binary_integer
7344 ,done OUT boolean
7345 ,handle OUT varchar2
7346 ,comment OUT varchar2
7347 ,media OUT varchar2
7348 ,concur OUT boolean
7349 ,params IN varchar2 default NULL
7350 ,media_pool IN binary_integer default 0
7351 ,reuse IN boolean default FALSE
7352 ,archlog_failover OUT boolean
7353 ,deffmt IN binary_integer
7354 ,recid OUT number
7355 ,stamp OUT number
7356 ,tag OUT varchar2
7357 ,docompress IN boolean
7358 ,dest IN binary_integer
7359 ,post10_2 IN boolean
7360 ,netalias IN varchar2
7361 ,compressalg IN varchar2
7362 ,compressasof IN number default 1
7363 ,compresslopt IN binary_integer default
7364 LOPT_TRUE );
7365
7366 -- Description and return values can be found with original declaration
7367 -- above. New parameters:
7368 --
7369 -- compressasof - Release version for compression algorithm
7370 -- compresslopt - Type of optimize for load
7371 --
7372
7373 PROCEDURE clearControlfile;
7374
7375 -- This procedure clears the circular sections of the controlfile to remove
7376 -- all the backups and image copy records and supporting controlfile
7377 -- records. This is done in preparation for a no target, no recovery
7378 -- catalog duplicate, and should not be used lightly.
7379
7380 PROCEDURE switch_primary_bct;
7381
7382 -- This procedure is executed only once per backup at a standby when
7383 -- the backup is an incremental backup and the standby has block change
7384 -- tracking enabled.
7385
7386 FUNCTION networkFileTransfer(dbname IN varchar2
7387 ,username IN varchar2 default NULL
7388 ,passwd IN varchar2 default NULL
7389 ,role IN varchar2
7390 ,srcfile IN varchar2
7391 ,destfile IN varchar2
7392 ,operation IN varchar2
7393 ,ftype_check IN boolean
7394 ,retcode OUT number)
7395 RETURN boolean;
7396 -- Description and return values are with original declaration above.
7397 -- New parameters
7398 --
7399 -- ftype_check - file type check
7400
7401 -- The following function returns the connect identifier using which
7402 -- a specific remote database can be connected.
7403
7404 FUNCTION get_connect_identifier(dbuname IN varchar2)
7405 return varchar2;
7406
7407 PROCEDURE bmrStart( save_all_blocks IN boolean,
7408 save_final_blocks IN boolean,
7409 nofileupdate IN boolean,
7410 doclear IN boolean,
7411 flags_clear IN binary_integer default 0 );
7412 -- Description and return values can be found with original declaration
7413 -- above. New parameter:
7414 --
7415 -- flags_clear - Indicates what kind of clearing should be performed
7416 -- see krbm0.h for details.
7417
7418 FUNCTION rman_usage(diskonly IN boolean,
7419 nondiskonly IN boolean,
7420 encrypted IN boolean,
7421 compalg IN varchar2)
7422 return binary_integer;
7423
7427 -- Parameters:
7424 -- This procedure checks if backups with the specified characteristics
7425 -- are present in the system.
7426 --
7428 -- diskonly - If TRUE indicates that only copies and backups on disk
7429 -- should be considered.
7430 -- nondiskonly - If TRUE indicates that only backups on non disk devices
7431 -- should be considered. It is an error to specify this
7432 -- parameter TRUE is diskonly is also TRUE, only one of them
7433 -- can be specified. It is OK that both are FALSE, as it
7434 -- means that we want any backup.
7435 -- encrypted - If TRUE indicates that we are looking for encrypted
7436 -- backups only. Currently it is an error that any other
7437 -- parameter is specified if this is TRUE.
7438 -- compalg - If not NULL indicates the compression algorithm that
7439 -- the backups should be compressed with. Currently it
7440 -- is an error that any other parameter is specified
7441 -- if this is not NULL.
7442
7443 PROCEDURE restoreControlfileTo( cfname IN varchar2
7444 ,isstby IN boolean
7445 ,nocfconv IN boolean);
7446 -- Description and return values can be found with original declaration
7447 -- above. New parameters:
7448 --
7449 -- nocfconv
7450 -- is set to TRUE when we don't want controfile conversion
7451
7452 PROCEDURE backupBackupPiece( bpname IN varchar2
7453 ,fname IN varchar2
7454 ,handle OUT varchar2
7455 ,comment OUT varchar2
7456 ,media OUT varchar2
7457 ,concur OUT boolean
7458 ,recid OUT number
7459 ,stamp OUT number
7460 ,tag IN varchar2 default NULL
7461 ,params IN varchar2 default NULL
7462 ,media_pool IN binary_integer default 0
7463 ,reuse IN boolean default FALSE
7464 ,check_logical IN boolean
7465 ,copyno IN binary_integer
7466 ,deffmt IN binary_integer
7467 ,copy_recid IN number
7468 ,copy_stamp IN number
7469 ,npieces IN binary_integer
7470 ,dest IN binary_integer
7471 ,pltfrmfr IN binary_integer);
7472 -- Description and return values can be found with original declaration
7473 -- above. New parameters
7474 --
7475 -- pltfrmfr - Id of platfrom to convert from. NULL if no conversion.
7476 -- 0 indicates that the piece is self describing (12.1)
7477
7478 PROCEDURE initFraMetaData;
7479 -- This procedure clears FRA meta-data and re-initializes it by inspecting
7480 -- each FRA file w.r.t current FRA setting. This is invented to re-init
7481 -- FRA meta-data on clone instance. Note that database isn't mounted as
7482 -- CLONE when rman does duplicate. So, this has be to re-initialized
7483 -- using explicit call.
7484 --
7485
7486 PROCEDURE clearUnarchivedLogs;
7487 -- remove non archived entry from archived_log log
7488
7489 PROCEDURE backupValidate(archlog_failover OUT boolean
7490 ,nocleanup IN boolean
7491 ,compress_set IN boolean);
7492 -- Description can be found with original declaration above.
7493 --
7494 -- New parameters
7495 -- compress_set: Pass it as TRUE if validate as compressed backupset.
7496 -- Otherwise, FALSE.
7497 --
7498
7499 PROCEDURE OAMPolledRecord (rectype IN binary_integer,
7500 recid IN number,
7501 stamp IN number);
7502
7503 --
7504 -- The record if belongs to FRA, will be marked as polled by OAM
7505 -- to enable automatic purging of file.
7506 --
7507 -- Input parameters:
7508 -- rectype
7509 -- The record type that are backed by VSS.
7510 -- recid, stamp
7511 -- The record-id, stamp to identify the record.
7512
7513 PROCEDURE copyDataFileCopy( copy_recid IN number
7514 ,copy_stamp IN number
7515 ,full_name OUT varchar2
7516 ,recid OUT number
7517 ,stamp OUT number
7518 ,fname IN varchar2 default NULL
7519 ,max_corrupt IN binary_integer default 0
7520 ,tag IN varchar2 default NULL
7521 ,nochecksum IN boolean default FALSE
7522 ,isbackup IN boolean default FALSE
7523 ,check_logical IN boolean default FALSE
7524 ,inst_restore IN binary_integer);
7525 -- This procedure is the same as copyDataFileCopy with the last
7526 -- two addtional parameters.
7527 --
7528 -- Two new input parameters:
7529 -- inst_restore
7530 -- Whether the instant restore option is exercised
7531 -- The value 0 is for no instant restore
7535 -- See the description of copyDataFileCopy for other parameters.
7532 -- The value 1 is for instant restore full
7533 -- The value 2 is for instant restore sparse
7534 --
7536
7537 PROCEDURE writeTrace(txt IN varchar2);
7538
7539 -- This procedure writes a message to a trace file if krb_trace is enabled
7540 -- Used to help identify trace files created by rman
7541
7542
7543 PROCEDURE setMSC( fname IN varchar2);
7544
7545 -- Set the fname into the backup conversation context.
7546 -- This is used by sections 2-n and setup once
7547 -- by the channel processing section 1.
7548 --
7549 -- Input parameters:
7550 -- fname
7551 -- Shared filename for the multisection copy
7552
7553 PROCEDURE initMSC( fname IN varchar2,
7554 deffmt IN binary_integer,
7555 dest IN binary_integer,
7556 handle OUT varchar2);
7557
7558 -- Front load the file name before backup piece
7559 -- create to get the name of the file, all the
7560 -- channels need to write to on a multi-section copy.
7561
7562 PROCEDURE restoreSetXttfile( pltfrmfr IN binary_integer
7563 ,xttincr IN boolean);
7564
7565 -- This procedure initiates a restore conversation for files that do not
7566 -- belong to this database from backup pieces that are not part of the
7567 -- database to transport a tablespace
7568 --
7569 -- Input parameters:
7570 -- pltfrmfr
7571 -- The id of the platform we are converting this backup piece from
7572 -- NULL if not provided.
7573 -- xttincr
7574 -- TRUE if this is an incremental xtt restore
7575 -- Exceptions:
7576 -- CONVERSATION-ACTIVE (ora-19590)
7577 -- A backup or restore conversation is already active in this session.
7578 -- MULTI-THREADED-SERVER (ora-19550)
7579 -- This session is not connected to a dedicated server.
7580 -- ALTERNATE-CONTROLFILE-OPEN (ora-226)
7581 -- This session's fixed tables are currently re-directed to a snapshot
7582 -- or other alternate controlfile.
7583 -- DATABASE-NOT-MOUNTED (ora-1507)
7584 -- No database is mounted.
7585
7586
7587 PROCEDURE restoreXttFileTo( xtype IN binary_integer
7588 ,xfno IN binary_integer
7589 ,xtsname IN varchar2
7590 ,xfname IN varchar2);
7591
7592 -- Add a file to the restore conversation for files that do not belong
7593 -- to this database that will be restored.
7594 --
7595 -- Input parameters:
7596 -- xtype
7597 -- One of the following values:
7598 -- All files for this backup piece list
7599 XTT_ALL constant binary_integer := 0;
7600
7601 -- Tablespace name is valid in xtsname
7602 XTT_TABLESPACE constant binary_integer := 1;
7603
7604 -- Absolute filenumber is valid in xfno
7605 XTT_FILENO constant binary_integer := 2;
7606
7607 -- xfno
7608 -- Valid only if xtype is XTT_FILENO
7609 -- The absolute file number of the file that will be restored. The
7610 -- absolute file number refers to the file number stored in the
7611 -- backup piece.
7612 -- xtsname
7613 -- Valid only if xtype is XTT_TABLESPACE
7614 -- The name of the tablespace for which the xfname applies.
7615 -- xfname
7616 -- It is interpreted differently depending on xtype.
7617 -- For xtype == XTT_ALL
7618 -- xfname is NULL it means to restore all files to NEW
7619 -- xfname not NULL means this is a format for all files
7620 -- For xtype == XTT_TABLESPACE
7621 -- xfname is NULL it means to restore all files in tablespace to NEW
7622 -- xfname not NULL gives a format for all files in tablespace
7623 -- For xtype == XTT_FILENO
7624 -- xfname is NULL, it is an error
7625 -- xfname is not NULL gives the actual name to which to restore
7626 -- the specified file
7627 -- Exceptions:
7628 -- NAME-TOO-LONG (ora-19704)
7629 -- The specified file name is longer than the port-specific
7630 -- maximum file name length.
7631 -- CONVERSATION-NOT-ACTIVE (ora-19580)
7632 -- A restore conversation was not started before specifying files.
7633 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
7634 -- The database is in the process of being opened, closed, mounted,
7635 -- or dismounted.
7636 -- DATABASE-NOT-MOUNTED (ora-1507)
7637 -- The database is not mounted.
7638 -- WRONG-CONVERSATION-TYPE (ora-19592)
7639 -- This restore conversation is not for foreign files.
7640 -- NAMING-PHASE-OVER (ora-19604)
7641 -- The first backup piece has been restored. No more files can be
7642 -- named.
7643 -- DUPLICATE-DATAFILE (ora-19593)
7644 -- This file has already been specified for restoration.
7645
7646
7647 PROCEDURE XttRestore( handle IN varchar2
7648 ,done OUT boolean);
7649
7650 -- This procedure reads the piece specified as its parameter
7651 -- and writes it contents to the files provided by restoreXttFileTo
7652 -- Input parameters:
7653 -- handle
7654 -- Name of the backup piece to restore.
7655 -- Output parameters:
7656 -- done
7657 -- TRUE if all requested objects have been completely restored, FALSE
7658 -- otherwise.
7659 -- Exceptions:
7660 -- CONVERSATION-NOT-ACTIVE (ora-19580)
7661 -- A restore conversation was not started before specifying files.
7665 -- DATABASE-NOT-MOUNTED (ora-1507)
7662 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
7663 -- The database is in the process of being opened, closed, mounted,
7664 -- or dismounted.
7666 -- The database is not mounted.
7667 -- DEVICE-NOT-ALLOCATED (ora-19569)
7668 -- This session does not have a device allocated.
7669 -- NO-FILES (ora-19581)
7670 -- No files have been specified for restoration so there is nothing
7671 -- to restore.
7672 -- NOT-A-BACKUP-PIECE (ora-19608)
7673 -- The input file is not recognizable as a backup piece.
7674 -- WRONG-BACKUP-SET-TYPE
7675 -- This backup piece is from the wrong type of backup set. It cannot
7676 -- be processed by this conversation.
7677 -- WRONG-SET (ora-19609)
7678 -- The backup piece is not part of the backup set being restored from.
7679 -- WRONG-ORDER (ora-19611)
7680 -- The backup piece was supplied in the wrong order.
7681 -- CORRUPT-DIRECTORY (ora-19610)
7682 -- The backup piece directory is corrupt.
7683 -- FILE-NOT-IN-BACKUP-SET (ora-19615)
7684 -- At least one of the files which were explicitely named for restoration
7685 -- is not found in this backup set. This error is raised only
7686 -- on the first piece of a backup set.
7687 -- DATAFILE-NOT-RESTORED (ora-19612)
7688 -- The indicated file could not be restored, because some of its
7689 -- blocks were corrupt in the backup set.
7690
7691 PROCEDURE backupDmpfile(dmpfile IN varchar2,
7692 blksize IN number,
7693 dpckpscn IN number,
7694 dpckptime IN number,
7695 dprlgscn IN number,
7696 dprlgtime IN number,
7697 dpfno IN number,
7698 dbid IN number);
7699 -- Add a datapump export dumpfile log to the backup set.
7700 -- Input parameters:
7701 -- dmpfile
7702 -- The name of the dumpfile to be included.
7703 -- blksize
7704 -- The blocksize that will be used to backup the datapump dumpfile
7705 -- dpckpscn
7706 -- Checkpoint scn of the datafile representing files in
7707 -- dumpfile
7708 -- dpckptime
7709 -- Checkpoint time of the datafile representing files in
7710 -- dumpfile
7711 -- dprlgscn
7712 -- SCN of the resetlogs of the datafile representing files in
7713 -- dumpfile
7714 -- dprlgtime
7715 -- Timestamp of the resetlogs of the datafile representing files in
7716 -- dumpfile
7717 -- dpfno
7718 -- File number of the datafile representing files in dumpfile
7719 -- dbid
7720 -- The database id to whom the datafiles belong
7721 -- Exceptions:
7722 -- CONVERSATION-NOT-ACTIVE (ora-19580)
7723 -- A backup conversation was not started before specifying files.
7724 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
7725 -- The database is in the process of being opened, closed, mounted,
7726 -- or dismounted.
7727 -- DATABASE-NOT-MOUNTED (ora-1507)
7728 -- The database is not mounted.
7729 -- WRONG-CONVERSATION-TYPE (ora-19592)
7730 -- The backup set is not for datafiles.
7731 -- NAMING-PHASE-OVER (ora-19604)
7732 -- backuppiececreate has already been called. No files can be named
7733 -- after piececreate is called.
7734 -- RECORD-NOT-FOUND (ora-19571)
7735 -- The specified archived log record does not exist.
7736 -- DUPLICATE-DMPFILE (ora-19596)
7737 -- A dumpfile has already been specified for this conversation
7738 -- FILE-NOT-FOUND (ora-19980)
7739 -- The file can not be opened.
7740 -- FILE-VALIDATION-FAILURE (ora-19982)
7741 -- The file is not a dumpfile
7742 -- RETRYABLE-ERROR (ora-19624)
7743 -- This is a pseudo-error that is placed on top of the stack when an
7744 -- error is signalled but it may be possible to continue the
7745 -- conversation.
7746 -- IO-ERROR
7747 -- An error occured attempting to read the file header.
7748
7749 PROCEDURE restoreDmpfile(dmpfile IN varchar2);
7750
7751 -- Add the datapump dump file to the restore conversation when restoring
7752 -- datafiles that do not belong to this database.
7753 --
7754 -- Input parameters:
7755 -- dmpfile
7756 -- The name to which the dumpfile should be restored.
7757 --
7758 -- NAME-TOO-LONG (ora-19704)
7759 -- The specified file name is longer than the port-specific
7760 -- maximum file name length.
7761 -- CONVERSATION-NOT-ACTIVE (ora-19580)
7762 -- A restore conversation was not started before specifying files.
7763 -- CANT-GET-INSTANCE-STATE-ENQUEUE (ora-1155)
7764 -- The database is in the process of being opened, closed, mounted,
7765 -- or dismounted.
7766 -- DATABASE-NOT-MOUNTED (ora-1507)
7767 -- The database is not mounted.
7768 -- WRONG-CONVERSATION-TYPE (ora-19592)
7769 -- This restore conversation is not for foreign files.
7770 -- NAMING-PHASE-OVER (ora-19604)
7771 -- The first backup piece has been restored. No more files can be
7772 -- named.
7773
7774 FUNCTION getXttsName(xfname OUT varchar2) return number;
7775
7776 -- Return the filenumber and the name of the foreign datafile that
7777 -- will be restored as stored in the restore context.
7778 -- When no more files are available, return filenumber of zero
7779 --
7780 -- Output parameters:
7781 -- xfname
7782 -- Name of the foreign datafile restore.
7783
7787 PROCEDURE applySetDataFile( check_logical IN boolean
7784 PROCEDURE restoreSetDataFile( check_logical IN boolean
7785 ,cleanup IN boolean
7786 ,service IN varchar2);
7788 ,cleanup IN boolean
7789 ,service IN varchar2);
7790 PROCEDURE restoreSetArchivedLog( destination IN varchar2
7791 ,cleanup IN boolean
7792 ,service IN varchar2);
7793 -- Description and return values can be found with original declaration
7794 -- above.
7795 -- New parameters
7796 --
7797 -- Input parameters:
7798 -- service
7799 -- The service name from which the piece has to be read.
7800 --
7801
7802 PROCEDURE networkBackupDatafile(dfnumber IN binary_integer);
7803 -- This procedure sets the specified datafile as backup target in
7804 -- remote server.
7805 --
7806 -- Input parameters:
7807 -- dfnumber: file being streamed from remote server.
7808
7809 PROCEDURE networkSetMSB(
7810 dfnumber IN number
7811 ,section_size IN number
7812 ,first_section IN number
7813 ,section_count IN number
7814 ,pieceno IN number
7815 ,piececnt IN number);
7816
7817 -- This procdure sets section size for multi-section backup in remote server
7818 --
7819 -- section_size: number of blocks in one section
7820 -- first_section: first section to back up
7821 -- section_count: number of sections to back up
7822 -- pieceno: piece number to use for this backup piece
7823 -- piececnt: total number of pieces in this multi-section backup set
7824
7825 PROCEDURE networkBackupArchivedLog(
7826 arch_recid IN number
7827 ,arch_stamp IN number);
7828 -- This procedure sets the indicated archivelog as the backup target in
7829 -- remote server.
7830
7831 PROCEDURE networkBackupSpfile;
7832 -- This procedure sets the spfile as a backup target in remote server.
7833
7834
7835 PROCEDURE networkReadFileHeader(service IN varchar2
7836 ,dfnumber IN binary_integer
7837 ,blksize IN number
7838 ,blocks OUT number
7839 ,crescn OUT number
7840 ,rlgscn OUT number
7841 ,ckpscn OUT number
7842 ,afzscn OUT number
7843 ,rfzscn OUT number
7844 ,fhdbi OUT number
7845 ,fhfdbi OUT number
7846 ,fhplus OUT number);
7847 -- This procedure reads the file header from the remote server.
7848 -- Input parameters:
7849 -- service - tns service name from which the header to be read
7850 -- dfnumber - file# to be read. 0 for controlfile
7851 -- blksize - datafile blksize
7852 -- blocks - number of blocks
7853 -- crescn - file creation change#
7854 -- rlgscn - resetlogs change#
7855 -- ckpscn - checkpoint change#
7856 -- afzscn - absolute fuzziness change#
7857 -- rfzscn - recovery fuzzy change#
7858 -- fhdbi - dbid in file header
7859 -- fhfdbi - foreign dbid of plugged in datafile
7860 -- fhplus - plugin change#
7861
7862 PROCEDURE cleanupPgaContext;
7863 -- This procedure cleans up any misc PGA context.
7864 -- As of now, it clears remoteConnection and aux dfc FRA context.
7865 -- Update the above list if you add new calls.
7866
7867 FUNCTION validateTableSpace( tsid IN binary_integer
7868 ,cSCN IN number
7869 ,pdbId IN number)
7870 RETURN binary_integer;
7871 -- Description and return values can be found with original declaration
7872 -- above.
7873 -- New parameters
7874 --
7875 -- Input parameters:
7876 -- pdbId
7877 -- Pluggable Database Id associated with the ts#.
7878 --
7879
7880 PROCEDURE setTablespaceExclude( tsid IN binary_integer
7881 ,flag IN binary_integer
7882 ,pdbid IN number);
7883 -- Description and return values can be found with original declaration
7884 -- above.
7885 -- New parameters
7886 --
7887 -- Input parameters:
7888 -- pdbId
7889 -- Pluggable Database Id associated with the ts#.
7890 --
7891
7892 PROCEDURE setTableSpaceAttr(code IN number,
7893 tsid IN binary_integer,
7894 clear IN binary_integer,
7895 onoff IN binary_integer,
7896 pdbid IN number);
7897 -- Description and return values can be found with original declaration
7898 -- above.
7899 -- New parameters
7900 --
7901 -- Input parameters:
7902 -- pdbId
7903 -- Pluggable Database Id associated with the ts#.
7904 --
7905
7906 PROCEDURE dba2rfno( dbano IN number,
7907 rfno OUT number,
7908 blockno OUT number,
7909 tsnum IN binary_integer,
7910 pdbid IN number);
7911 -- Description and return values can be found with original declaration
7915 -- Input parameters:
7912 -- above.
7913 -- New parameters
7914 --
7916 -- pdbId
7917 -- Pluggable Database Id associated with the ts#.
7918 --
7919
7920 PROCEDURE switchTempfile(tsnum IN number,
7921 tsname IN varchar2,
7922 tfnum IN number,
7923 tfname IN varchar2,
7924 create_time IN date,
7925 create_scn IN number,
7926 blocks IN number,
7927 blocksize IN binary_integer,
7928 rfnum IN number,
7929 exton IN boolean,
7930 isSFT IN boolean,
7931 maxsize IN number,
7932 nextsize IN number,
7933 pdbId IN number);
7934 -- Description and return values can be found with original declaration
7935 -- above.
7936 -- New parameters
7937 --
7938 -- Input parameters:
7939 -- pdbId
7940 -- Pluggable Database Id associated with the ts#.
7941 --
7942
7943 PROCEDURE flashbackStart(flashbackSCN IN number,
7944 flashbackTime IN date,
7945 scnBased IN binary_integer,
7946 toBefore IN binary_integer,
7947 resetSCN IN number,
7948 resetTime IN date,
7949 pdbId IN number);
7950 -- Description and return values can be found with original declaration
7951 -- above.
7952 -- New parameters
7953 --
7954 -- Input parameters:
7955 -- pdbId
7956 -- Pluggable Database Id to flashback. Pass NULL to indicate that
7957 -- the entire CDB has to be flashbacked.
7958 --
7959
7960 PROCEDURE registerAuxDfCopy(pdbname IN varchar2
7961 ,clnscnwrp IN number
7962 ,clnscnbas IN number
7963 ,auxdfcList IN register_auxdfc_list);
7964 -- This procedure reads the header from an operating system datafile copy,
7965 -- and makes a record in the controlfile section V$AUXILIARY_DATAFILE_COPY.
7966 -- This is used later to extract the undo for a PDB during open resetlogs
7967 -- operation of a PDB.
7968 --
7969 -- Input parameters:
7970 -- pdbname
7971 -- PDB name for which this filelist is registered.
7972 -- clnscn
7973 -- PDB clean scn from container$ of clone instance
7974 -- auxdfcList
7975 -- List of auxiliary datafile copy files (filename, file#, tsnum#,
7976 -- blksize)
7977
7978 -- This procedure is executed only once per backup at a standby when
7979 -- the backup is an incremental backup and the standby has block change
7980 -- tracking enabled.
7981
7982 PROCEDURE restoreSetDataFile( check_logical IN boolean
7983 ,cleanup IN boolean
7984 ,service IN varchar2
7985 ,chunksize IN binary_integer
7986 ,rs_flags IN binary_integer);
7987 PROCEDURE applySetDataFile( check_logical IN boolean
7988 ,cleanup IN boolean
7989 ,service IN varchar2
7990 ,chunksize IN binary_integer
7991 ,rs_flags IN binary_integer);
7992 -- Description and return values can be found in the original declaration.
7993 --
7994 -- New parameter:
7995 --
7996 -- Input parameters:
7997 -- chunksize
7998 -- Recovery Server related: size of an individual chunk file. In bytes.
7999 -- rs_compress
8000 -- Recovery Server related: TRUE chunks will contain compressed blocks.
8001 -- rs_full
8002 -- Recovery Server related: TRUE chunks will contain full blocks.
8003 --
8004
8005 PROCEDURE backupBackupPiece( bpname IN varchar2
8006 ,fname IN varchar2
8007 ,handle OUT varchar2
8008 ,comment OUT varchar2
8009 ,media OUT varchar2
8010 ,concur OUT boolean
8011 ,recid OUT number
8012 ,stamp OUT number
8013 ,tag IN varchar2 default NULL
8014 ,params IN varchar2 default NULL
8015 ,media_pool IN binary_integer default 0
8016 ,reuse IN boolean default FALSE
8017 ,check_logical IN boolean
8018 ,copyno IN binary_integer
8019 ,deffmt IN binary_integer
8020 ,copy_recid IN number
8021 ,copy_stamp IN number
8022 ,npieces IN binary_integer
8023 ,dest IN binary_integer
8024 ,pltfrmfr IN binary_integer
8025 ,ors IN boolean
8026 ,bpsize OUT number);
8027 -- Description and return values can be found with original declaration
8028 -- above. New parameters
8029 --
8033 FUNCTION deviceAllocate( type IN varchar2 default NULL
8030 -- ors - indicates if the piece is copied in ORS.
8031 -- bpsize - copied backup piece size
8032
8034 ,name IN varchar2 default NULL
8035 ,ident IN varchar2 default NULL
8036 ,noio IN boolean default FALSE
8037 ,params IN varchar2 default NULL
8038 ,node OUT varchar2
8039 ,dupcnt IN binary_integer
8040 ,trace IN binary_integer default 0
8041 ,allowmts IN boolean
8042 ,ors_lib_key IN number)
8043 RETURN varchar2;
8044 --
8045 -- Description and return values can be found with original declaration
8046 -- above. The new arguments are:
8047 -- allowmts
8048 -- TRUE if to allow device allocation on a MTS session. Otherwise,
8049 -- FALSE.
8050 -- ors_lib_key
8051 -- ORS sbt library identifier. This is passed as non-zero when
8052 -- ORS copies the disk backup to tape.
8053 --
8054
8055 PROCEDURE cfileUseCurrent (allowmts IN BOOLEAN);
8056 --
8057 -- Description can be found with original declaration above.
8058 -- The new arguments are:
8059 -- allowmts
8060 -- TRUE if to allow device allocation on a MTS session. Otherwise,
8061 -- FALSE.
8062 --
8063
8064 FUNCTION getPrimaryConstr RETURN varchar2;
8065 -- This procedure returns the connect string of primary. If executed on
8066 -- primary, then it will return NULL.
8067
8068 FUNCTION getStandbyConstr RETURN varchar2;
8069 -- This procedure returns the connect string of best standby by comparing
8070 -- the applied scn. If executed on standby, it will return the best
8071 -- cascading standby (if any). Otherwise, NULL.
8072
8073 FUNCTION createFraAuxDfCopy(tsname IN varchar2
8074 ,blksize IN number
8075 ,fsize IN number)
8076 RETURN varchar2;
8077 -- This procedure returns an OMF file name for a datafile copy in given
8078 -- tablespace. The OMF name is derived from current FRA location. Instead
8079 -- of returning a template, it really creates a dummy file and returns
8080 -- a complete OMF name that can be later used in a clone database. In
8081 -- addition to creating the file, it reserves FRA disk space.
8082 --
8083 -- Input parameters:
8084 -- tsname
8085 -- The name of the file's tablespace.
8086 -- blksize
8087 -- The block size of the file
8088 -- fsize
8089 -- Number of blocks in the file.
8090
8091
8092 FUNCTION createFraAuxCfCopy(blksize IN number
8093 ,fsize IN number)
8094 RETURN varchar2;
8095 -- This procedure returns an OMF file name for a controlfile copy.
8096 -- The OMF name is derived from current FRA location. Instead
8097 -- of returning a template, it really creates a dummy file and returns
8098 -- a complete OMF name that can be later used in a clone database. In
8099 -- addition to creating the file, it reserves FRA disk space.
8100 --
8101 -- Input parameters:
8102 -- blksize
8103 -- The block size of the file
8104 -- fsize
8105 -- Number of blocks in the file.
8106
8107 PROCEDURE searchFiles(pattern IN OUT varchar2
8108 ,ns IN OUT varchar2
8109 ,ccf IN boolean default FALSE
8110 ,omf IN boolean default FALSE
8111 ,ftype IN varchar2 default NULL
8112 ,onlyfnm IN boolean
8113 ,normfnm IN boolean);
8114 -- Description and return values can be found with original declaration
8115 -- above. New parameters:
8116 --
8117 -- onlyfnm
8118 -- Only return the filenames for each file that is found
8119 -- normfnm
8120 -- Normalize the filenames for each file that is found
8121
8122 FUNCTION deviceAllocate( type IN varchar2 default NULL
8123 ,name IN varchar2 default NULL
8124 ,ident IN varchar2 default NULL
8125 ,noio IN boolean default FALSE
8126 ,params IN varchar2 default NULL
8127 ,node OUT varchar2
8128 ,dupcnt IN binary_integer
8129 ,trace IN binary_integer default 0
8130 ,allowmts IN boolean
8131 ,ors_lib_key IN number
8132 ,db_name IN varchar2)
8133 RETURN varchar2;
8134 --
8135 -- Description and return values can be found with original declaration
8136 -- above. The new arguments are:
8137 -- db_name
8138 -- db_name to use when allocating sbt channel. Otherwise, the database
8139 -- name of this database is used. When AvM backs up PDB files to tape,
8140 -- the db_name of PDB is passed so that the tape vendor recognizes
8141 -- those as PDB backup rather than AvM backup.
8142 --
8143
8144 PROCEDURE createRestorePoint(name IN varchar2,
8145 scn IN number);
8146
8147 --
8148 -- This procedure creates a restore point with the specified SCN. This
8149 -- is little bit diffferent from CREATE RESTORE POINT AS OF SCN command
8153 -- name (IN) - name of the restore point
8150 -- in a way the server trusts the SCN specified and doesn't check whether
8151 -- database has advanced to that scn (on standby).
8152 --
8154 -- scn (IN) - scn associated with the restore point
8155 --
8156
8157 PROCEDURE backupBackupPiece( bpname IN varchar2
8158 ,fname IN varchar2
8159 ,handle OUT varchar2
8160 ,comment OUT varchar2
8161 ,media OUT varchar2
8162 ,concur OUT boolean
8163 ,recid OUT number
8164 ,stamp OUT number
8165 ,tag IN varchar2 default NULL
8166 ,params IN varchar2 default NULL
8167 ,media_pool IN binary_integer default 0
8168 ,reuse IN boolean default FALSE
8169 ,check_logical IN boolean
8170 ,copyno IN binary_integer
8171 ,deffmt IN binary_integer
8172 ,copy_recid IN number
8173 ,copy_stamp IN number
8174 ,npieces IN binary_integer
8175 ,dest IN binary_integer
8176 ,pltfrmfr IN binary_integer
8177 ,ors IN boolean
8178 ,bpsize OUT number
8179 ,template_key IN number);
8180 --
8181 -- Description and return values can be found with original declaration
8182 -- above. The new arguments are:
8183 -- template_key
8184 -- ORS sbt job template identifier. This is passed as non-zero when
8185 -- ORS copies the disk backup to tape.
8186
8187 FUNCTION deviceAllocate( type IN varchar2 default NULL
8188 ,name IN varchar2 default NULL
8189 ,ident IN varchar2 default NULL
8190 ,noio IN boolean default FALSE
8191 ,params IN varchar2 default NULL
8192 ,node OUT varchar2
8193 ,dupcnt IN binary_integer
8194 ,trace IN binary_integer default 0
8195 ,allowmts IN boolean
8196 ,ors_lib_key IN number
8197 ,db_name IN varchar2
8198 ,platform_id IN number)
8199 RETURN varchar2;
8200 --
8201 -- Description and return values can be found with original declaration
8202 -- above. The new arguments are:
8203 -- platform_id
8204 -- platform_id of the backup/restore object. If 0 or null, the
8205 -- platform_id of current database is used. When BA sends backup from
8206 -- upstream to downstream, the platform id of database is passed.
8207 --
8208
8209 PROCEDURE backupBackupPiece( bpname IN varchar2
8210 ,fname IN varchar2
8211 ,handle OUT varchar2
8212 ,comment OUT varchar2
8213 ,media OUT varchar2
8214 ,concur OUT boolean
8215 ,recid OUT number
8216 ,stamp OUT number
8217 ,tag IN varchar2 default NULL
8218 ,params IN varchar2 default NULL
8219 ,media_pool IN binary_integer default 0
8220 ,reuse IN boolean default FALSE
8221 ,check_logical IN boolean
8222 ,copyno IN binary_integer
8223 ,deffmt IN binary_integer
8224 ,copy_recid IN number
8225 ,copy_stamp IN number
8226 ,npieces IN binary_integer
8227 ,dest IN binary_integer
8228 ,pltfrmfr IN binary_integer
8229 ,ors IN boolean
8230 ,bpsize OUT number
8231 ,template_key IN number
8232 ,encrypt IN number
8233 ,enc_algorithm IN number
8234 ,allowTDE IN number
8235 ,password IN varchar2);
8236 --
8237 -- Description and return values can be found with original declaration
8238 -- above. The new arguments are:
8239 -- encrypt flag
8240 -- algorithm used for encryption
8241 -- allow TDE
8242 -- password
8243
8244 FUNCTION createTempXmlFile
8245 RETURN varchar2;
8246 -- This procedure returns a temporary filename.
8247 -- The temporary filename is derived from ?/dbs location.
8248
8249 pragma TIMESTAMP('2004-03-19:13:28:00');
8250 end;
[Home] [Help]