AUTONOMOUS_TRANSACTION Pragma

AUTONOMOUS_TRANSACTION Pragma

The AUTONOMOUS_TRANSACTION pragma changes the way a subprogram works within a transaction. A subprogram marked with this pragma can do SQL operations and commit or roll back those operations, without committing or rolling back the data in the main transaction. For more information, see "Doing Independent Units of Work with Autonomous Transactions" on page 6-35.

Syntax

autonomous_transaction_pragma

PRAGMA AUTONOMOUS_TRANSACTION ;

Keyword and Parameter Description

PRAGMA

Signifies that the statement is a pragma (compiler directive). Pragmas are processed at compile time, not at run time. They pass information to the compiler.

Usage Notes

You can apply this pragma to:

You cannot apply this pragma to an entire package or an entire an object type. Instead, you can apply the pragma to each packaged subprogram or object method.

You can code the pragma anywhere in the declarative section. For readability, code the pragma at the top of the section.

Once started, an autonomous transaction is fully independent. It shares no locks, resources, or commit-dependencies with the main transaction. You can log events, increment retry counters, and so on, even if the main transaction rolls back.

Unlike regular triggers, autonomous triggers can contain transaction control statements such as COMMIT and ROLLBACK, and can issue DDL statements (such as

CREATE and DROP) through the EXECUTE IMMEDIATE statement.

Changes made by an autonomous transaction become visible to other transactions when the autonomous transaction commits. The changes also become visible to the main transaction when it resumes, but only if its isolation level is set to READ COMMITTED (the default). If you set the isolation level of the main transaction to SERIALIZABLE, changes made by its autonomous transactions are not visible to the main transaction when it resumes.

In the main transaction, rolling back to a savepoint located before the call to the autonomous subprogram does not roll back the autonomous transaction. Remember, autonomous transactions are fully independent of the main transaction.

If an autonomous transaction attempts to access a resource held by the main transaction (which cannot resume until the autonomous routine exits), a deadlock can

13-6 PL/SQL User's Guide and Reference

AUTONOMOUS_TRANSACTION Pragma

occur. Oracle raises an exception in the autonomous transaction, which is rolled back if the exception goes unhandled.

If you try to exit an active autonomous transaction without committing or rolling back, Oracle raises an exception. If the exception goes unhandled, or if the transaction ends because of some other unhandled exception, the transaction is rolled back.

Examples

The following example marks a packaged function as autonomous:

CREATE PACKAGE banking AS

FUNCTION balance (acct_id INTEGER) RETURN REAL; END banking;

/

CREATE PACKAGE BODY banking AS

FUNCTION balance (acct_id INTEGER) RETURN REAL IS PRAGMA AUTONOMOUS_TRANSACTION;

my_bal REAL; BEGIN

NULL;

END;

END banking;

/

DROP PACKAGE banking;

The following example lets a trigger issue transaction control statements:

CREATE TABLE anniversaries AS

SELECT DISTINCT TRUNC(hire_date) anniversary FROM employees;

ALTER TABLE anniversaries ADD PRIMARY KEY (anniversary);

CREATE TRIGGER anniversary_trigger

BEFORE INSERT ON employees FOR EACH ROW

DECLARE

PRAGMA AUTONOMOUS_TRANSACTION;

BEGIN

INSERT INTO anniversaries VALUES(TRUNC(:new.hire_date));

--Only commits the preceding INSERT, not the INSERT that fired

--the trigger. COMMIT; EXCEPTION

--If someone else was hired on the same day, we get an exception

--because of duplicate values. That's OK, no action needed. WHEN OTHERS THEN NULL;

END;

/

DROP TRIGGER anniversary_trigger;

DROP TABLE anniversaries;

Related Topics

EXCEPTION_INIT Pragma, RESTRICT_REFERENCES Pragma,

SERIALLY_REUSABLE Pragma

PL/SQL Language Elements 13-7

Blocks

Blocks

The basic program unit in PL/SQL is the block. A PL/SQL block is defined by the keywords DECLARE, BEGIN, EXCEPTION, and END. These keywords partition the block into a declarative part, an executable part, and an exception-handling part. Only the executable part is required. You can nest a block within another block wherever you can place an executable statement. For more information, see "Block Structure" on page 1-4 and "Scope and Visibility of PL/SQL Identifiers" on page 2-14.

Syntax

13-8 PL/SQL User's Guide and Reference

Blocks

item_declaration

collection_declaration constant_declaration cursor_declaration cursor_variable_declaration exception_declaration object_declaration object_ref_declaration record_declaration variable_declaration

sql_statement

commit_statement delete_statement insert_statement lock_table_statement rollback_statement

savepoint_statement

select_statement

set_transaction_statement

update_statement

PL/SQL Language Elements 13-9

Blocks

assignment_statement close_statement execute_immediate_statement exit_statement fetch_statement

forall_statement

statement

Keyword and Parameter Description

base_type

Any scalar or user-defined PL/SQL datatype specifier such as CHAR, DATE, or

RECORD.

BEGIN

Signals the start of the executable part of a PL/SQL block, which contains executable statements. A PL/SQL block must contain at least one executable statement (even just the NULL statement).

collection_declaration

Declares a collection (index-by table, nested table, or varray). For the syntax of collection_declaration, see "Collections" on page 13-21.

constant_declaration

Declares a constant. For the syntax of constant_declaration, see "Constants and Variables" on page 13-28.

constraint

Applies only to datatypes that can be constrained such as CHAR and NUMBER. For character datatypes, this specifies a maximum size in bytes. For numeric datatypes, this specifies a maximum precision and scale.

cursor_declaration

Declares an explicit cursor. For the syntax of cursor_declaration, see "Cursors" on page 13-38.

13-10 PL/SQL User's Guide and Reference

Blocks

cursor_variable_declaration

Declares a cursor variable. For the syntax of cursor_variable_declaration, see "Cursor Variables" on page 13-34.

DECLARE

Signals the start of the declarative part of a PL/SQL block, which contains local declarations. Items declared locally exist only within the current block and all its sub-blocks and are not visible to enclosing blocks. The declarative part of a PL/SQL block is optional. It is terminated implicitly by the keyword BEGIN, which introduces the executable part of the block.

PL/SQL does not allow forward references. You must declare an item before referencing it in any other statements. Also, you must declare subprograms at the end of a declarative section after all other program items.

END

Signals the end of a PL/SQL block. It must be the last keyword in a block. Remember, END does not signal the end of a transaction. Just as a block can span multiple transactions, a transaction can span multiple blocks.

EXCEPTION

Signals the start of the exception-handling part of a PL/SQL block. When an exception is raised, normal execution of the block stops and control transfers to the appropriate exception handler. After the exception handler completes, execution proceeds with the statement following the block.

If there is no exception handler for the raised exception in the current block, control passes to the enclosing block. This process repeats until an exception handler is found or there are no more enclosing blocks. If PL/SQL can find no exception handler for the exception, execution stops and an unhandled exception error is returned to the host environment. For more information, see Chapter 10.

exception_declaration

Declares an exception. For the syntax of exception_declaration, see "Exceptions" on page 13-45.

exception_handler

Associates an exception with a sequence of statements, which is executed when that exception is raised. For the syntax of exception_handler, see "Exceptions" on page 13-45.

function_declaration

Declares a function. For the syntax of function_declaration, see "Functions" on page 13-67.

label_name

An undeclared identifier that optionally labels a PL/SQL block. If used, label_name must be enclosed by double angle brackets and must appear at the beginning of the block. Optionally, label_name (not enclosed by angle brackets) can also appear at the end of the block.

A global identifier declared in an enclosing block can be redeclared in a sub-block, in which case the local declaration prevails and the sub-block cannot reference the global

PL/SQL Language Elements 13-11

Blocks

identifier unless you use a block label to qualify the reference, as the following example shows:

<<outer>> DECLARE

x INTEGER; BEGIN

DECLARE

x INTEGER; BEGIN

IF x = outer.x THEN -- refers to global x NULL;

END IF; END;

END outer;

/

object_declaration

Declares an instance of an object type. For the syntax of object_declaration, see "Object Types" on page 13-86.

procedure_declaration

Declares a procedure. For the syntax of procedure_declaration, see "Procedures" on page 13-104.

record_declaration

Declares a user-defined record. For the syntax of record_declaration, see "Records" on page 13-110.

statement

An executable (not declarative) statement that. A sequence of statements can include procedural statements such as RAISE, SQL statements such as UPDATE, and PL/SQL blocks.

PL/SQL statements are free format. That is, they can continue from line to line if you do not split keywords, delimiters, or literals across lines. A semicolon (;) serves as the statement terminator.

subtype_name

A user-defined subtype that was defined using any scalar or user-defined PL/SQL datatype specifier such as CHAR, DATE, or RECORD.

variable_declaration

Declares a variable. For the syntax of variable_declaration, see "Constants and Variables" on page 13-28.

PL/SQL supports a subset of SQL statements that includes data manipulation, cursor control, and transaction control statements but excludes data definition and data control statements such as ALTER, CREATE, GRANT, and REVOKE.

Example

The following PL/SQL block declares some variables, executes statements with calculations and function calls, and handles errors that might occur:

13-12 PL/SQL User's Guide and Reference

Blocks

the_ratio := numerator/denominator; dbms_output.put_line('Ratio = ' || the_ratio);

EXCEPTION

WHEN ZERO_DIVIDE THEN

dbms_output.put_line('Divide-by-zero error: can''t divide ' || numerator || ' by ' || denominator);

WHEN OTHERS THEN dbms_output.put_line('Unexpected error.');

END;

/

Related Topics

Constants and Variables, Exceptions, Functions, Procedures

PL/SQL Language Elements 13-13