1 PACKAGE dbms_pitr IS
2
3 TS_PITR_VERSION CONSTANT varchar2(15) := '8.1.5.0.0';
4
5 ------------------
6 -- Introduction --
7 ------------------
8
9 -- This package contains procedures which get called during the import
10 -- phase and export phase of point-in-time recovery (PITR).
11 --
12 -- During the export phase, EXP calls this package to obtain the text
13 -- of 2 anonymous PL/SQL blocks. The first block goes at the front of
14 -- the .dmp file, and the second block goes at the end. Inbetween the 2
15 -- blocks are the DDL commands created by EXP to reconstruct the dictionary
16 -- for the tablespaces being PITR'd.
17 --
18 -- The emitted PL/SQL code contains calls to other procedures in this
19 -- package. IMP must read each anonymous PL/SQL block from the .dmp file,
20 -- collect it into a single contiguous memory buffer, and then parse
21 -- and execute the PL/SQL block. The parsed SQL statement (the plsql
22 -- anonymous block) must precisely the lines of text that were returned
23 -- to EXP from this package, with no characters added or deleted.
24 --
25 -- The "emit" procedures are intended to be called in the following sequence:
26 --
27 -- dbms_pitr.beginExport;
28 --
29 -- dbms_pitr.selectTablespace('tsname_1'); \
30 -- : > called once per tablespace
31 -- dbms_pitr.selectTablespace('tsname_N'); /
32 --
33 -- dbms_pitr.selectBlock(dbms_pitr.ts_pitr_begin);
34 --
35 -- dbms_pitr.getLine; > called until it returns NULL
36 --
37 -- dbms_pitr.selectBlock(dbms_pitr.ts_pitr_end);
38 --
39 -- dbms_pitr.getLine; > called until it returns NULL
40 --
41 --
42 -- In the exp.dmp file, it would look like:
43 -- dbms_pitr.beginImport;
44 --
45 -- dbms_pitr.adjustCompatibility(...);
46 -- :
47 --
48 -- dbms_pitr.beginTablespace(tsname);
49 -- dbms_pitr.doFileVerify(...);
50 -- :
51 -- dbms_pitr.endTablespace;
52 --
53 -- dbms_pitr.commitPitr;
54 --
55 -- dbms_pitr.endImport;
56
57
58 -------------------------------
59 -- Package Public Exceptions --
60 -------------------------------
61
62 pitr_others EXCEPTION;
63 PRAGMA exception_init(pitr_others, -29300);
64 pitr_others_num NUMBER := -29300;
65
66 wrong_order EXCEPTION;
67 PRAGMA exception_init(wrong_order, -29301);
68 wrong_order_num NUMBER := -29301;
69
70 database_not_open_clone EXCEPTION;
71 PRAGMA exception_init(database_not_open_clone, -29302);
72 database_not_open_clone_num NUMBER := -29302;
73
74 user_not_SYS EXCEPTION;
75 PRAGMA exception_init(user_not_SYS, -29303);
76 user_not_SYS_num NUMBER := -29303;
77
78 wrong_tsname EXCEPTION;
79 PRAGMA exception_init(wrong_tsname, -29304);
80 wrong_tsname_num NUMBER := -29304;
81
82 not_read_only EXCEPTION;
83 PRAGMA exception_init(not_read_only, -29305);
84 not_read_only_num NUMBER := -29305;
85
86 file_offline EXCEPTION;
87 PRAGMA exception_init(file_offline, -29306);
88 file_offline_num NUMBER := -29306;
89
90 file_error EXCEPTION;
91 PRAGMA exception_init(file_error, -29307);
92 file_error_num NUMBER := -29307;
93
94 pitr_check EXCEPTION;
95 PRAGMA exception_init(pitr_check, -29308);
96 pitr_check_num NUMBER := -29308;
97
98 wrong_package_version EXCEPTION;
99 PRAGMA exception_init(wrong_package_version, -29309);
100 wrong_package_version_num NUMBER := -29309;
101
102 not_open_primary EXCEPTION;
103 PRAGMA exception_init(not_open_primary, -29310);
104 not_open_primary_num NUMBER := -29310;
105
106 database_not_match EXCEPTION;
107 PRAGMA exception_init(database_not_match, -29311);
108 database_not_match_num NUMBER := -29311;
109
110 not_compatible EXCEPTION;
111 PRAGMA exception_init(not_compatible, -29312);
112 not_compatible_num NUMBER := -29312;
113
114 ts_twice EXCEPTION;
115 PRAGMA exception_init(ts_twice, -29313);
116 ts_twice_num NUMBER := -29313;
117
118 not_offline_for_recovery EXCEPTION;
119 PRAGMA exception_init(not_offline_for_recovery, -29314);
120 not_offline_for_recovery_num NUMBER := -29314;
121
122 tablespace_recreated EXCEPTION;
123 PRAGMA exception_init(tablespace_recreated, -29315);
124 tablespace_recreated_num NUMBER := -29315;
125
126 file_twice EXCEPTION;
127 PRAGMA exception_init(file_twice, -29316);
128 file_twice_num NUMBER := -29316;
129
130 no_datafile EXCEPTION;
131 PRAGMA exception_init(no_datafile, -29317);
132 no_datafile_num NUMBER := -29317;
133
134 file_online EXCEPTION;
135 PRAGMA exception_init(file_online, -29318);
136 file_online_num NUMBER := -29318;
137
138 import_file_error EXCEPTION;
139 PRAGMA exception_init(import_file_error, -29319);
140 import_file_error_num NUMBER := -29319;
141
142 fileheader_error EXCEPTION;
143 PRAGMA exception_init(fileheader_error, -29320);
144 fileheader_error_num NUMBER := -29320;
145
146 too_many_file EXCEPTION;
147 PRAGMA exception_init(too_many_file, -29321);
148 too_many_file_num NUMBER := -29321;
149
150 -- EXCEPTION;
151 -- PRAGMA exception_init(, -);
152 -- _num NUMBER := -;
153
154
155 -------------------------------------------
156 -- PLSQL Anonymous Block Emit Procedures --
157 -------------------------------------------
158
159 PROCEDURE beginExport;
160
161 -- This procedure initialize all private variables in dbms_pitr package.
162 -- It must be called before any other procedure calls.
163 -- It also checks if database is open clone; if user login as SYS.
164 -- If there is any indoubt txn, the txn is abort.
165 -- It also brings unnecessary tablespaces offline.
166 --
167 -- Exceptions:
168 -- DATABASE_NOT_OPEN_CLONE (ORA-29302)
169 -- database is not open as a clone database.
170 -- USER_NOT_SYS (ORA-29303)
171 -- user does not login as SYS
172 -- PITR_OTHERS (ORA-29300)
173 -- other oracle error.
174
175
176 PROCEDURE selectTablespace( tsname IN varchar2 );
177
178 -- This procedure informs this package that the caller intends to do
179 -- point-in-time recovery on the specified tablespace. This procedure must
180 -- be called once for each tablespace in the recovery set.
181 -- It alter selected tablespace read only, also checks datafiles in the
182 -- selected tablespace.
183 --
184 -- Input parameters:
185 -- tsname
186 -- The tablespace name.
187 --
188 -- Exceptions:
189 -- WRONG_ORDER (ORA-29301)
190 -- wrong dbms_pitr package functions/procedure order.
191 -- WRONG_TSNAME (ORA-29304)
192 -- select tablespace does not exist
193 -- NOT_READ_ONLY (ORA-29305)
194 -- cannot alter the tablespace read only
195 -- FILE_OFFLINE (ORA-29306)
196 -- datafile is not online
197 -- FILE_ERROR (ORA-29307)
198 -- datafile error
199 -- PITR_OTHERS (ORA-29300)
200 -- other oracle error.
201
202 PROCEDURE selectBlock( blockId IN binary_integer );
203
204 -- This procedures selects a particular PL/SQL anonymous block for retrieval.
205 -- The various blocks that may be selected are listed below as constant
206 -- public package variables.
207 -- When select the 1st block, selectBlock would check if there any crossing
208 -- reference objects exist.
209 -- After selectBlock is called, selectBlock cannot be called again until
210 -- getLine gets a NULL return.
211 --
212 -- Input parameters:
213 -- blockId
214 -- One of the public package constants defined below.
215 --
216 -- Exceptions:
217 -- WRONG_ORDER (ORA-29301)
218 -- wrong dbms_pitr package functions/procedure order.
219 -- PITR_CHECK (ORA-29308)
220 -- view TS_PITR_CHECK failure
221 -- PITR_OTHERS (ORA-29300)
222 -- other oracle error.
223
224 ---------------
225 -- Block IDs --
226 ---------------
227
228 TS_PITR_BEGIN CONSTANT BINARY_INTEGER := 1;
229 TS_PITR_END CONSTANT BINARY_INTEGER := 2;
230
231
232 FUNCTION getLine RETURN varchar2;
233
234 -- This function returns the next line of a block that has been
235 -- previously selected for retrieval via selectBlock.
236 --
237 -- Returns:
238 -- The next line of the block. The maximum length of a line is 200
239 -- characters. NULL is returned when all lines of a block have
240 -- been returned.
241 --
242 -- Exceptions:
243 -- WRONG_ORDER (ORA-29301)
244 -- wrong dbms_pitr package functions/procedure order.
245 -- PITR_OTHERS (ORA-29300)
246 -- other oracle error.
247
248 --------------------------------------
249 -- PUBLIC Functions and Procedures --
250 --------------------------------------
251
252 -- The PLSQL code to call the following procedures/functions should
253 -- be obtained only by calling the procedures described above.
254
255
256 PROCEDURE beginImport( packageVersion IN varchar2
257 ,databaseID IN number
258 ,resetSCN IN number
259 ,resetStamp IN number
260 ,highestSCN IN number );
261
262 -- This procedure is called from an anonymous PL/SQL block embedded.
263 -- It checks package version, database ID, resetlog SCN and stamp.
264 -- It also adjusts primary database SCN if necessary, and enable pseudo
265 -- create syntax.
266 --
267 -- Input parameters:
268 -- packageVersion
269 -- The version number of the package that emitted the PL/SQL anonymous
270 -- block.
271 -- databaseID
272 -- 32 bits database ID.
273 -- resetSCN
274 -- Reset SCN expected in primary database.
275 -- resetStamp
276 -- Reset timesatmp expected in primary database.
277 -- highestSCN
278 -- It is the highest clean SCN of the tablespaces in the clone database.
279 -- The production database needs to adjust the SCN if the highest clean
280 -- SCN is larger than the SCN in production database.
281 --
282 -- Exceptions:
283 -- WRONG_ORDER (ORA-29301)
284 -- wrong dbms_pitr package functions/procedure order.
285 -- WRONG_PACKAGE_VERSION (ORA-29309)
286 -- packageVersion does not match the packageVersion in clone.
287 -- NOT_OPEN_PRIMARY (ORA-29310)
288 -- database is either not open or open as a clone.
289 -- DATABASE_NOT_MATCH (ORA-29311)
290 -- databaseID does not match the clone databaseID.
291 -- reset scn and time stamp do not match the previous reset of the clone.
292 -- PITR_OTHERS (ORA-29300)
293 -- other oracle error.
294
295
296 PROCEDURE adjustCompatibility( comID IN varchar2
297 ,comRL IN varchar2 );
298
299 -- This routine checks the primary database compatibility segment.
300 -- If an entry already exists in the clone databasebut not in the primary
301 -- database, then the entry is created.
302 -- If the primary compatible parameter does not recognize the format,
303 -- then an error is returned.
304 --
305 -- This is called once for each entry in the clone database compatibility
306 -- segment other than undo, bootstrap, and the compatibility segment itself.
307 --
308 -- Input parameters:
309 -- comID
310 -- Compatibility type id.
311 -- comRL
312 -- Current release level used by type comID.
313 --
314 -- Exceptions:
315 -- WRONG_ORDER (ORA-29301)
316 -- wrong dbms_pitr package functions/procedure order.
317 -- NOT_COMPATIBLE (ORA-29312)
318 -- current using database is not compatible with the database used
319 -- at the point-in-time
320 -- PITR_OTHERS (ORA-29300)
321 -- other oracle error.
322
323 PROCEDURE beginTablespace( tsid IN binary_integer
324 ,createSCN IN number
325 ,tsBitmap IN number
326 ,tsFlags IN number
327 ,tsSegfno IN number
328 ,tsSegbno IN number
329 ,tsSegsize IN number);
330
331 -- This procedure is called from an anonymous PL/SQL block embedded
332 -- at the beginning of the .dmp file. The anonymous block is parsed
333 -- and executed by IMP.
334 --
335 -- Input parameters:
336 -- tsid
337 -- The tablespace number undergoing point-in-time recovery.
338 -- createSCN
339 -- Tablespace creation SCN.
340 -- tsBitmap
341 -- Is tablespace bitmapped
342 -- tsFlags
343 -- Other flags
344 --
345 -- Exceptions:
346 -- WRONG_ORDER (ORA-29301)
347 -- wrong dbms_pitr package functions/procedure order.
348 -- TS_TWICE (ORA-29313)
349 -- tablespace has been imported already
350 -- NOT_OFFLINE_FOR_RECOVERY (ORA-29314)
351 -- tablespace is not OFFLINE FOR RECOVERY nor READ ONLY
352 -- TABLESPACE_RECREATED (ORA-29315)
353 -- tablespace has been recreated
354 -- PITR_OTHERS (ORA-29300)
355 -- other oracle error.
356
357 PROCEDURE doFileVerify( fno IN binary_integer
358 ,tsid IN binary_integer
359 ,ckptSCN IN number
360 ,resetSCN IN number
361 ,resetStamp IN number
362 ,filesize IN number
363 ,hdba IN number );
364
365 -- This procedure must follow a beginTablespace call. The file must
366 -- be for the tablespace. There must be one call for each datafile
367 -- that is part of the tablespace (in the clone database).
368 -- EXP shoud obtain the text for the call to this procedure by calling
369 -- emitFileVerify.
370 --
371 -- Input parameters:
372 -- fno
373 -- Absolute datafile number
374 -- tsid
375 -- Corresponding tablespace number.
376 -- ckptSCN
377 -- The datafile checkpoint SCN.
378 -- resetSCN
379 -- Reset SCN in file header.
380 -- resetStamp
381 -- Reset timesatmp in file header.
382 -- filesize
383 -- The size of the file in blocks.
384 --
385 -- Exceptions:
386 -- WRONG_ORDER (ORA-29301)
387 -- wrong dbms_pitr package functions/procedure order.
388 -- DATAFILE_TWICE (ORA-29316)
389 -- datafile been imported twice
390 -- NO_DATAFILE (ORA-29317)
391 -- datafile not found
392 -- FILE_ONLINE (ORA-29318)
393 -- datafile online
394 -- IMPORT_FILE_ERROR (ORA-29319)
395 -- datafile header error
396 -- FILEHEADER_ERROR (ORA-29320)
397 -- datafile header error
398 -- PITR_OTHERS (ORA-29300)
399 -- other oracle error.
400
401 PROCEDURE endTablespace( cleanSCN IN number
402 ,resetSCN IN number
403 ,resetStamp IN number );
404
405 -- This procedure must follow the last doFileVerify call. Each
406 -- beginTablespace call must have a matching endTablespace call.
407 -- It builds a list of the files added between the current and the
408 -- recovery point-in-time.
409 --
410 -- Input parameters:
411 -- cleanSCN
412 -- tablespace clean SCN from the clone database.
413 -- resetSCN
414 -- tablespace resetlog SCN from the clone database.
415 -- resetStamp
416 -- tablespace resetlog time stamp from the clone database.
417 --
418 -- Exceptions:
419 -- WRONG_ORDER (ORA-29301)
420 -- wrong dbms_pitr package functions/procedure order.
421 -- PITR_OTHERS (ORA-29300)
422 -- other oracle error.
423
424
425 PROCEDURE commitPitr;
426
427 -- This procedure is called after all tablespaces have been registered
428 -- by beginTablespace and endTablespace. This ICD actually drops the
429 -- tablespaces in tspitr set on production database.
430 --
431 -- Exceptions:
432 -- WRONG_ORDER (ORA-29301)
433 -- wrong dbms_pitr package functions/procedure order.
434 -- PITR_CHECK (ORA-29308)
435 -- view TS_PITR_CHECK failure
436 -- TOO_MANY_FILE (ORA-29321)
437 -- too many datafile added since the point-in-time
438 -- PITR_OTHERS (ORA-29300)
439 -- other oracle error.
440
441
442 PROCEDURE endImport;
443
444 -- This procedure is called from an anonymous PL/SQL block embedded.
445 -- It provides recovery layer an entry point to do what it should do in
446 -- the end of importing. It should be called in the end of IMPORT.
447 -- It does nothing in this version.
448 --
449 -- Exceptions:
450 -- WRONG_ORDER (ORA-29301)
451 -- wrong dbms_pitr package functions/procedure order.
452 -- PITR_OTHERS (ORA-29300)
453 -- other oracle error.
454
455 END dbms_pitr;
[Home] [Help]