Resuming Execution After a Storage Error Condition

accomplished by committing or rolling back the autonomous transaction before executing the PIPE ROW statement.

See Also: PL/SQL User's Guide and Reference

Resuming Execution After a Storage Error Condition

When a long-running transaction is interrupted by an out-of-space error condition, your application can suspend the statement that encountered the problem and resume it after the space problem is corrected. This capability is known as resumable storage allocation. It lets you avoid time-consuming rollbacks, without the need to split the operation into smaller pieces and write your own code to track its progress.

See Also:

What Operations Can Be Resumed After an Error Condition?

Queries, DML operations, and certain DDL operations can all be resumed if they encounter an out-of-space error. The capability applies if the operation is performed directly by a SQL statement, or if it is performed within a stored procedure, anonymous PL/SQL block, SQL*Loader, or an OCI call such as

OCIStmtExecute().

Operations can be resumed after these kinds of error conditions:

Limitations on Resuming Operations After an Error Condition

Certain storage errors cannot be handled using this technique. In dictionary-managed tablespaces, you cannot resume an operation if you run into the limit for rollback segments, or the maximum number of extents while creating an index or a table. Use locally managed tablespaces and automatic undo management in combination with this feature.

5-38 Oracle Database Application Developer's Guide - Fundamentals

Resuming Execution After a Storage Error Condition

Writing an Application to Handle Suspended Storage Allocation

When an operation is suspended, your application does not receive the usual error code. Instead, perform any logging or notification by coding a trigger to detect the AFTER SUSPEND event and call the functions in the DBMS_RESUMABLE package to get information about the problem. Using this package, you can:

■Parse the error message with the DBMS_RESUMABLE.SPACE_ERROR_INFO function. For details about this function, see PL/SQL Packages and Types Reference.

■Set a new timeout value with the SET_TIMEOUT procedure.

Within the body of the trigger, you can perform any notifications, such as sending a mail message to alert an operator to the space problem.

Alternatively, the DBA can periodically check for suspended statements using the data dictionary views DBA_RESUMABLE, USER_RESUMABLE, and V$_SESSION_ WAIT.

When the space condition is corrected (usually by the DBA), the suspended statement automatically resumes execution. If it is not corrected before the timeout period expires, the operation causes a SERVERERROR exception.

To reduce the chance of out-of-space errors within the trigger itself, you must declare it as an autonomous transaction so that it uses a rollback segment in the SYSTEM tablespace. If the trigger encounters a deadlock condition because of locks held by the suspended statement, the trigger is aborted and your application receives the original error condition, as if it was never suspended. If the trigger encounters an out-of-space condition, the trigger and the suspended statement are rolled back. You can prevent the rollback through an exception handler in the trigger, and just wait for the statement to be resumed.

See Also: Oracle Database Reference for details on the DBA_ RESUMABLE, USER_RESUMABLE, and V$_SESSION_WAIT data dictionary views

Example of Resumable Storage Allocation

This trigger handles applicable storage errors within the database. For some kinds of errors, it aborts the statement and alerts the DBA that this has happened through a mail message. For other errors that might be temporary, it specifies that the statement should wait for eight hours before resuming, with the expectation that the storage problem will be fixed by then.

How Oracle Database Processes SQL Statements 5-39

Resuming Execution After a Storage Error Condition

CREATE OR REPLACE TRIGGER suspend_example AFTER SUSPEND

ON DATABASE DECLARE cur_sid NUMBER;

cur_inst NUMBER; err_type VARCHAR2(64);

object_owner VARCHAR2(64); object_type VARCHAR2(64); table_space_name VARCHAR2(64); object_name VARCHAR2(64); sub_object_name VARCHAR2(64); msg_body VARCHAR2(64); ret_value boolean;

error_txt varchar2(64); mail_conn utl_smtp.connection; BEGIN

SELECT DISTINCT(sid) INTO cur_sid FROM v$mystat; cur_inst := userenv('instance');

ret_value := dbms_resumable.space_error_info(err_type, object_owner, object_ type, table_space_name, object_name, sub_object_name);

IF object_type = 'ROLLBACK SEGMENT' THEN

INSERT INTO sys.rbs_error ( SELECT sql_text, error_msg, suspend_time FROM dba_ resumable WHERE session_id = cur_sid AND instance_id = cur_inst);

SELECT error_msg into error_txt FROM dba_resumable WHERE session_id = cur_sid AND instance_id = cur_inst;

msg_body := 'Subject: Space error occurred: Space limit reached for rollback segment '|| object_name || ' on ' || to_char(SYSDATE, 'Month dd, YYYY, HH:MIam') || '. Error message was: ' || error_txt;

mail_conn := utl_smtp.open_connection('localhost', 25); utl_smtp.helo(mail_conn, 'localhost'); utl_smtp.mail(mail_conn, 'sender@localhost'); utl_smtp.rcpt(mail_conn, 'recipient@localhost'); utl_smtp.data(mail_conn, msg_body); utl_smtp.quit(mail_conn); dbms_resumable.abort(cur_sid);

ELSE dbms_resumable.set_timeout(3600*8); END IF;

COMMIT;

END;

5-40 Oracle Database Application Developer's Guide - Fundamentals