1 PACKAGE dbms_ir AS
2
3 -- DE-HEAD <- tell SED where to cut when generating fixed package
4
5 --*****************************************************************************
6 -- Package Public Types
7 --*****************************************************************************
8
9 --
10 -- Some routines act on a set of failures. This type is for defining the
11 -- input list of failures.
12 --
13 TYPE ir_failure_list_type IS TABLE OF number index by binary_integer;
14
15 --
16 -- Those routines that act on a list of failures will continue with all
17 -- failures even when there is are errors for some of the failures.
18 -- So, we must be able to return the error status for the failures that
19 -- cannot be changed. In those cases we'll return a table of failure/error
20 -- pairs. There will one entry for each failure that could not be changed.
21 --
22
23 TYPE ir_failure_op_error IS RECORD (
24 failureID number,
25 errorCode number );
26
27 TYPE ir_error_list_type IS TABLE OF ir_failure_op_error
28 index by binary_integer;
29
30 --
31 -- adviseDone returns a list of Repair ID, Option Idx
32 --
33 TYPE ir_repair_option_id IS RECORD (
34 repairID number,
35 optionIdx number,
36 spare1 number default NULL,
37 spare2 number default NULL,
38 spare3 number default NULL,
39 spare4 number default NULL,
40 spare5 number default NULL);
41
42 TYPE ir_repair_option_list IS TABLE OF ir_repair_option_id
43 index by binary_integer;
44
45 --
46 -- updateFeasibilityAndImpact can work on a set of repairs.
47 -- This record is for identifying a repair (failureIdx, repairIdx) and
48 -- for supplying the new feasibility and impact information for the
49 -- repair. A table of these is supplied to updateFeasibilityAndImpact.
50 --
51 TYPE ir_repair_feasibility IS RECORD (
52 failureIdx number,
53 repairIdx number,
54 feasibility boolean,
55 dataLoss number default NULL,
56 repairTime number default NULL,
57 spare1 number default NULL,
58 spare2 number default NULL,
59 spare3 number default NULL,
60 spare4 number default NULL,
61 spare5 number default NULL,
62 -- mjs TODO: get max size of impact string
63 impact varchar2(2000) default NULL);
64
65 TYPE ir_repair_feasibility_list IS TABLE OF ir_repair_feasibility
66 index by binary_integer;
67
68 --
69 -- Repair script file can be returned or supplied via one call using
70 -- this array of varchars.
71 --
72 TYPE ir_script_file_type IS TABLE OF varchar2(513) index by binary_integer;
73
74 --*****************************************************************************
75 -- Package Public Exceptions
76 --*****************************************************************************
77
78 internal_error EXCEPTION;
79 PRAGMA exception_init (internal_error, -51190);
80 internal_error_num NUMBER := -51190;
81
82 too_many_opens_error EXCEPTION;
83 PRAGMA exception_init (too_many_opens_error, -51191);
84 too_many_opens_error_num NUMBER := -51191;
85
86 not_open_error EXCEPTION;
87 PRAGMA exception_init (not_open_error, -51192);
88 not_open_error_num NUMBER := -51192;
89
90 invalid_param_error EXCEPTION;
91 PRAGMA exception_init (invalid_param_error, -51193);
92 invalid_param_error_num NUMBER := -51193;
93
94 --*****************************************************************************
95 -- IR List Routines
96 --*****************************************************************************
97
98 -------------------------------------------------------------------------------
99 --
100 -- PROCEDURE reevaluateOpenFailures
101 --
102 -- Description: Reevaluate the status of open IR failures.
103 --
104 -- Parameters: reevaluateCritical - reevaluate all critical open IR failures
105 -- reevaluateHigh - reevaluate all high open IR failures
106 -- reevaluateLow - reevaluate all low open IR failures
107 --
108 -------------------------------------------------------------------------------
109 PROCEDURE reevaluateOpenFailures( reevaluateCritical IN boolean default TRUE
110 ,reevaluateHigh IN boolean default TRUE
111 ,reevaluateLow IN boolean default TRUE );
112
113 -------------------------------------------------------------------------------
114 --
115 -- PROCEDURE reevaluateOpenFailures
116 --
117 -- Description: Reevaluate the status of open IR failures.
118 --
119 -- Parameters: reevaluateCritical -
120 -- 'TRUE' - reevaluate all critital open failures
121 -- 'FALSE' - don't reevaluate critical open failures
122 -- reevaluateHigh -
123 -- 'TRUE' - reevaluate all high open failures
124 -- 'FALSE' - don't reevaluate high open failures
125 -- reevaluateLow -
126 -- 'TRUE' - reevaluate all low open failures
127 -- 'FALSE' - don't reevaluate low open failures
128 -- timeout - maximum number of seconds to run
129 --
130 -------------------------------------------------------------------------------
131 PROCEDURE reevaluateOpenFailures( reevaluateCritical IN varchar
132 ,reevaluateHigh IN varchar
133 ,reevaluateLow IN varchar
134 ,timeout IN varchar );
135
136
137
138 --*****************************************************************************
139 -- IR Change Routines
140 --*****************************************************************************
141
142 --
143 -- Values for newPriority parameter for changePriority routine
144 --
145
146 -- Changing to critical is not allowed at this time
147 IR_FAILURE_CRITICAL constant binary_integer := 1;
148 IR_FAILURE_HIGH constant binary_integer := 2;
149 IR_FAILURE_LOW constant binary_integer := 3;
150
151 -------------------------------------------------------------------------------
152 --
153 -- PROCEDURE changePriority
154 --
155 -- Description: Change the priority of one or more IR failures.
156 -- Will attempt to change all the failures in the list, even
157 -- if errors prevent changing some of the failures.
158 --
159 -- The priority of a 'critical' failure cannot be changed and
160 -- a failure's priority cannot be changed to 'critical'.
161 --
162 -- The priorities of parents and children should remain the
163 -- same, hence the priority of a child failure cannot be
164 -- changed. If the priority of a parent failure is changed,
165 -- then all the children will also be changed to the same
166 -- priority.
167 --
168 -- Parameters: failureList - list of failure identifiers
169 -- newPriority - The new priority for the failures. One of:
170 -- IR_FAILURE_HIGH
171 -- IR_FALURE_LOW
172 -- errorList - failure-id/error pairs for the failures that
173 -- could not be changed.
174 --
175 -------------------------------------------------------------------------------
176 PROCEDURE changePriority( failureList IN ir_failure_list_type
177 ,newPriority IN binary_integer
178 ,errorList OUT ir_error_list_type );
179
180 -------------------------------------------------------------------------------
181 --
182 -- PROCEDURE changePriority
183 --
184 -- Description: See above.
185 --
186 -- Parameters: failureList - comma separated list of failure identifiers
187 -- newPriority - The new priority for the failures. One of:
188 -- IR_FAILURE_HIGH
189 -- IR_FALURE_LOW
190 -- errorID - Identifier for retrieving errors.
191 -- 0, if no errors encountered.
192 --
193 -------------------------------------------------------------------------------
194
195 PROCEDURE changePriority( failureList IN varchar2
196 ,newPriority IN binary_integer
197 ,errorID OUT number );
198
199
200 -------------------------------------------------------------------------------
201 --
202 -- PROCEDURE closeFailures
203 --
204 -- Description: Close one or more IR failures.
205 -- Will attempt to close all the failures in the list, even
206 -- if errors prevent changing some of the failures.
207 -- Closing a parent failure will cause all the children to
208 -- be closed.
209 --
210 -- Parameters: failureList - list of failure identifiers
211 -- errorList - failure-id/error pairs for the failures that
212 -- could not be closed.
213 --
214 -------------------------------------------------------------------------------
215 PROCEDURE closeFailures( failureList IN ir_failure_list_type
216 ,errorList OUT ir_error_list_type );
217
218 -------------------------------------------------------------------------------
219 --
220 -- PROCEDURE closeFailures
221 --
222 -- Description: See above.
223 --
224 -- Parameters: failureList - comma separated list of failure identifiers
225 -- errorList - Identifier fro retrieving errors.
226 -- 0, if no errors encountered.
227 --
228 -------------------------------------------------------------------------------
229 PROCEDURE closeFailures( failureList IN varchar2
230 ,errorID OUT number );
231
232
233 -------------------------------------------------------------------------------
234 --
235 -- PROCEDURE getError
236 --
237 -- Description: Return an error from a previous changePriority() or
238 -- closeFailures() request where the failure list was
239 -- passed in as a comma separated list of failure-ids.
240 --
241 -- Parameters: errorId - an identifier for the error list.
242 -- Returned by changePriority() or closeFailures().
243 -- failureId - the failure for which the command failed.
244 -- errorStr - the error message text.
245 -- done - FALSE if there are more errors to return.
246 -- TRUE if there are no more errors.
247 -- If TRUE, then 'errorStr' will be empty.
248 --
249 -------------------------------------------------------------------------------
250 PROCEDURE getError( errorId IN number
251 ,failureID OUT number
252 ,errorStr OUT varchar2
253 ,done OUT boolean );
254
255 --*****************************************************************************
256 -- IR Advise Routines
257 --*****************************************************************************
258
259 -------------------------------------------------------------------------------
260 --
261 -- PROCEDURE getAdviseID
262 --
263 -- Description: Start an ADVISE command and get the ADVISE identifier.
264 --
265 -- Parameters: failureList - list of failure identifiers
266 -- adviseID - the ADVISE identifier
267 --
268 -------------------------------------------------------------------------------
269 PROCEDURE getAdviseID( failureList IN ir_failure_list_type
270 ,adviseID OUT number );
271
272 -------------------------------------------------------------------------------
273 --
274 -- PROCEDURE getAdviseID
275 --
276 -- Description: Start an ADVISE command and get the ADVISE identifier.
277 --
278 -- Parameters: failureList - comma separted list of failure identifiers
279 -- adviseID - the ADVISE identifier
280 --
281 -------------------------------------------------------------------------------
282 PROCEDURE getAdviseID( failureList IN varchar2
283 ,adviseID OUT number );
284
285 -------------------------------------------------------------------------------
286 --
287 -- PROCEDURE createWorkingRepairSet
288 --
289 -- Description: Create intermediate working repair set for ADVISE command.
290 --
291 -- Parameters: adviseID - the ADVISE identifier
292 --
293 -------------------------------------------------------------------------------
294 PROCEDURE createWorkingRepairSet( adviseID IN number );
295
296 -------------------------------------------------------------------------------
297 --
298 -- PROCEDURE adviseCancel
299 --
300 -- Description: Cancels an ADVISE conversation, releasing the context.
301 -- This needs to be done if a conversation is going to be
302 -- abandoned without successfully completing the command.
303 -- This can be done anytime within the conversation after
304 -- createWorkingRepairSet has been called and before
305 -- adviseDone has been called.
306 --
307 -- Parameters: adviseID - the ADVISE identifier
308 --
309 -------------------------------------------------------------------------------
310 PROCEDURE adviseCancel( adviseID IN number);
311
312 -------------------------------------------------------------------------------
313 --
314 -- PROCEDURE getFeasibilityAndImpact
315 --
316 -- Description: Used by RMAN to get the feasibility and impact of a
317 -- particular repair on the server.
318 --
319 -- Parameters: repairType - The CTS repair type identifier.
320 -- parameterList - Repair parameters as name=value pairs
321 -- feasibility - Returned TRUE if the repair is feasible
322 -- dataLoss - Dataloss (if any) for the repair
323 -- repairTime - Repair time in seconds
324 -- impact - Repair impact text string
325 --
326 -------------------------------------------------------------------------------
327 PROCEDURE getFeasibilityAndImpact( repairType IN binary_integer
328 ,parameterList IN varchar2
329 ,feasibility OUT boolean
330 ,dataLoss OUT number
331 ,repairTime OUT number
332 ,impact OUT varchar2 );
333
334 -------------------------------------------------------------------------------
335 --
336 -- PROCEDURE updateFeasibilityAndImpact
337 --
338 -- Description: Used by RMAN to update the feasibility and impact of
339 -- a set of repairs (which are in the memory of the
340 -- server) during an ADVISE command.
341 --
342 -- Parameters: adviseID - The advise ID of the command.
343 -- repairList - A list of repairs and the associated
344 -- feasibility, dataLoss, repairTime,
345 -- and impact to assign to each.
346 --
347 -------------------------------------------------------------------------------
348 PROCEDURE updateFeasibilityAndImpact(
349 adviseID IN number
350 ,repairList IN ir_repair_feasibility_list );
351
352 -------------------------------------------------------------------------------
353 --
354 -- PROCEDURE consolidateRepair
355 --
356 -- Description: Called by RMAN to consolidate the repair options for
357 -- an ADVISE command.
358 --
359 -- Parameters: adviseID - the ADVISE identifier
360 --
361 -------------------------------------------------------------------------------
362 PROCEDURE consolidateRepair( adviseID IN number );
363
364 -------------------------------------------------------------------------------
365 --
366 -- PROCEDURE updateRepairOption
367 --
368 -- Description: Update an ADVISE repair option with its script name,
369 -- data loss, repair time, and impact.
370 --
374 -- Can be retrieved from x$idr_repair_option.
371 --
372 -- Parameters: adviseID - the ADVISE identifier
373 -- optionIdx - In-memory index of the option.
375 -- scriptName - Name of the repair script.
376 -- dataLoss - Data loss for the repair.
377 -- repairTime - Time (seconds) to do the repair.
378 -- impact - Impact text string.
379 --
380 -------------------------------------------------------------------------------
381 PROCEDURE updateRepairOption( adviseID IN number
382 ,optionIdx IN number
383 ,scriptName IN varchar2
384 ,dataLoss IN number default NULL
385 ,repairTime IN number default NULL
386 ,impact IN varchar2 default NULL);
387
388 -------------------------------------------------------------------------------
389 --
390 -- PROCEDURE adviseDone
391 --
392 -- Description: Called by RMAN to tell the server that an ADVISE has
393 -- completed. Will cause the repair option information to
394 -- be written to disk.
395 --
396 -- Parameters: adviseID - the ADVISE identifier
397 -- generatedRepairs - a list of the repair options generated.
398 -- Each entry includes the identifier
399 -- for the repair when it was written to
400 -- ADR and the index of the repair option
401 -- during the ADVISE.
402 -------------------------------------------------------------------------------
403 PROCEDURE adviseDone( adviseID IN number
404 ,generatedRepairs OUT ir_repair_option_list );
405
406
407 --*****************************************************************************
408 -- IR Repair Routines
409 --*****************************************************************************
410
411 -------------------------------------------------------------------------------
412 --
413 -- PROCEDURE startRepairOption
414 --
415 -- Description: Called prior to executing a repair option. It
416 -- verifies that all the failures associated with the repair
417 -- are still open and then updates the status of the repair
418 -- to indicate that it is running. It does NOT execute the
419 -- repair. It will signal an error if it is not ok to start
420 -- the repair.
421 --
422 -- Parameters: repairID - ID of the repair option to be executed.
423 -- generatedRepairs - a list of the repair options generated
424 -- (ADR repair identifer/repair option index)
425 --
426 -------------------------------------------------------------------------------
427 PROCEDURE startRepairOption( repairID IN number );
428
429 -------------------------------------------------------------------------------
430 --
431 -- PROCEDURE completeRepairOption
432 --
433 -- Description: Called after completing a repair. It updates
434 -- the status of the repair in ADR. If the repair was
435 -- successful it also reevaluates all open failures.
436 --
437 -- Parameters: repairID - ID of the repair option that was
438 -- tried.
439 -- repairSucceeded - TRUE if the repair was successful.
440 --
441 -------------------------------------------------------------------------------
442 PROCEDURE completeRepairOption( repairID IN number
443 ,repairSucceeded IN boolean );
444
445 --*****************************************************************************
446 -- IR Misc Routines
447 --*****************************************************************************
448
449 -------------------------------------------------------------------------------
450 --
451 -- PROCEDURE createScriptFile
452 --
453 -- Description: Called by RMAN to create and open a file to write a repair
454 -- script.
455 --
456 -- Parameters: fileId - An identifier for the open file. Can be used
457 -- to write/read from the file and close it, but
458 -- only from the same session.
459 -- fileName - The name of the file that was created.
460 --
461 -------------------------------------------------------------------------------
462 PROCEDURE createScriptFile( fileID OUT number
463 ,fileName OUT varchar2 );
464
465 -------------------------------------------------------------------------------
466 --
467 -- PROCEDURE openScriptFile
468 --
469 -- Description: Open a repair script file.
470 --
471 -- Parameters: repairID - the repair identifier for the script to open
472 -- fileID - an identifier for the open file. Can be used
473 -- to write/read from the file and close it,
474 -- but only from the same session.
475 --
476 -- Notes: Only one script file can be open at a time from the same session.
477 -------------------------------------------------------------------------------
478 PROCEDURE openScriptFile( repairID IN number
479 ,fileID OUT number );
480
484 --
481 -------------------------------------------------------------------------------
482 --
483 -- PROCEDURE openScriptFile
485 -- Description: Open a repair script file.
486 --
487 -- Parameters: fileName - The name of the script file.
488 -- fileID - an identifier for the open file. Can be used
489 -- to write/read from the file and close it,
490 -- but only from the same session.
491 --
492 -- Notes: Only one script file can be open at a time from the same session.
493 -------------------------------------------------------------------------------
494 PROCEDURE openScriptFile( fileName IN varchar2
495 ,fileID OUT number );
496
497 -------------------------------------------------------------------------------
498 --
499 -- PROCEDURE addLine
500 --
501 -- Description: Write a line to a script file.
502 --
503 -- Parameters: fileID - The identifier for an open file.
504 -- Must have been opened from this session.
505 -- line - Line of text to write.
506 --
507 -------------------------------------------------------------------------------
508 PROCEDURE addLine( fileID IN number
509 ,line IN varchar2 );
510
511
512 -------------------------------------------------------------------------------
513 --
514 -- PROCEDURE getLine
515 --
516 -- Description: Read a line from a script file.
517 --
518 -- Parameters: fileId - an identifier for an open script file.
519 -- Returned by openScriptFile().
520 -- line - The first/next line of text from the file.
521 -- The first line, if this is the first call
522 -- with fileID.
523 -- It may be up to 513 bytes long.
524 -- done - FALSE if there are more lines to return.
525 -- TRUE if there are no more lines.
526 -- If TRUE, then 'line' is undefined.
527 --
528 -------------------------------------------------------------------------------
529 PROCEDURE getLine( fileID IN number
530 ,line OUT varchar2
531 ,done OUT boolean );
532
533
534 -------------------------------------------------------------------------------
535 --
536 -- PROCEDURE writeFile
537 --
538 -- Description: Write multiple lines to a script file.
539 --
540 -- Parameters: fileID - The identifier for an open file.
541 -- Must have been opened from this session.
542 -- contents - The set of lines to write.
543 --
544 -------------------------------------------------------------------------------
545 PROCEDURE writeFile( fileID IN number
546 ,contents IN ir_script_file_type );
547
548 -------------------------------------------------------------------------------
549 --
550 -- PROCEDURE getFile
551 --
552 -- Description: Returns the contents of an IR script file.
553 --
554 -- Parameters: fileId - an identifier for an open script file.
555 -- Returned by openScriptFile().
556 -- contents - The lines from the file.
557 --
558 -------------------------------------------------------------------------------
559 PROCEDURE getFile( fileID IN number
560 ,contents OUT ir_script_file_type );
561
562 -------------------------------------------------------------------------------
563 --
564 -- PROCEDURE getFile
565 --
566 -- Description: Returns the contents of an IR script file.
567 --
568 -- Parameters: fileId - an identifier for an open script file.
569 -- Returned by openScriptFile().
570 -- outBuf - Contains the lines from the file concatentated
571 -- together, each line terminated by a newline
572 -- character, and the whole string NULL
573 -- terminated. outBuf should be at least 32767
574 -- chars long, which is the maximum script size.
575 --
576 -------------------------------------------------------------------------------
577 PROCEDURE getFile( fileID IN number
578 ,outBuf OUT varchar2 );
579
580 -------------------------------------------------------------------------------
581 --
582 -- PROCEDURE closeScriptFile
583 --
584 -- Description: Close a repair script file.
585 --
586 -- Parameters: fileID - an identifier for an open script file.
587 -- Must have been returned from openScriptFile().
588 --
589 -------------------------------------------------------------------------------
590 PROCEDURE closeScriptFile( fileID IN number );
591
592 -------------------------------------------------------------------------------
593 --
594 -- PROCEDURE execSqlScript
595 --
596 -- Description: execute the specified sql script
597 --
598 -- Parameters: filename - sql script location
599 --
600 -------------------------------------------------------------------------------
601 PROCEDURE execSqlScript( filename IN varchar2 );
602
606 --
603 -------------------------------------------------------------------------------
604 --
605 -- PROCEDURE controlfileCheck
607 -- Description: execute IR crosscheck for controlfile
608 --
609 -- Parameters: filename - controlfile name
610 --
611 -- Returns: TRUE if crosscheck is successful. Otherwise, FALSE.
612 --
613 -------------------------------------------------------------------------------
614 FUNCTION controlfileCheck( cfname IN varchar2 ) RETURN boolean;
615
616 -------------------------------------------------------------------------------
617
618 pragma TIMESTAMP('2006-03-17:12:00:00');
619
620 -------------------------------------------------------------------------------
621
622 END;
623
624 -- CUT_HERE <- tell sed where to chop off the rest