Chapter 4 User Lock and Transaction Management 4.2 DBMS_TRANSACTION: Interfacing to SQL Transaction Statements The DBMS_TRANSACTION package provides a programmatic interface to a number of the SQL transaction statements. The majority of the DBMS_TRANSACTION programs have SQL equivalents that you can utilize directly from within SQL. For this reason, developers and DBAs may choose to use the direct SQL equivalents rather than these procedures. A number of other procedures and functions have no equivalents, however, and nicely abstract the PL/SQL programmer or database administrator from the internal details managed by the database. 4.2.1 Getting Started with DBMS_TRANSACTION The DBMS_TRANSACTION package is created when the Oracle database is installed. The dbmsutil.sql script (found in the built−in packages source code directory, as described in Chapter 1) contain the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS_TRANSACTION for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. 4.2.1.1 DBMS_TRANSACTION programs Table 4.4 lists the procedures and functions available through DBMS_TRANSACTION, along with their SQL equivalents (if applicable). Table 4.4: DBMS_TRANSACTION Programs Name Description Use in SQL? ADVISE_COMMIT Executes the equivalent of the ALTER SESSION ADVISE COMMIT command. Yes ADVISE_NOTHING Executes the equivalent of the ALTER SESSION ADVISE NOTHING command. Yes ADVISE_ROLLBACK Executes the equivalent of the ALTER SESSION ADVISE ROLLBACK command. Yes BEGIN_DISCRETE_TRANSACTION Sets the discrete transaction mode. No 221 COMMIT Executes the equivalent of the COMMIT command. Yes COMMIT_COMMENT Executes the equivalent of the COMMIT COMMENT command. Yes COMMIT_FORCE Executes the equivalent of the COMMIT FORCE command. Yes LOCAL_TRANSACTION_ID Returns a local (to instance) unique identfier for the current transaction. No PURGE_MIXED Deletes information on a mixed outcome transaction (a possible scenario with two−phase commit). No PURGE_LOST_DB_ENTRY Removes "lost database entries" otherwise used to control recovery in pending two−phase commit operations. No READ_ONLY Executes the equivalent of the SET TRANSACTION READ ONLY command. Yes READ_WRITE Executes the equivalent of the SET TRANSACTION READ WRITE command. Yes ROLLBACK Executes the equivalent of the ROLLBACK command. Yes ROLLBACK_FORCE Executes the equivalent of the ROLLBACK FORCE command. Yes ROLLBACK_SAVEPOINT Executes the equivalent of the ROLLBACK TO command. Yes SAVEPOINT Executes the equivalent of the SAVEPOINT command. Yes STEP_ID Returns a local (to local transaction) unique positive integer that orders the DML operations of a transaction. No SEGMENT Executes the equivalent of the SET TRANSACTION USE ROLLBACK SEGMENT command. Yes 4.2.1.2 DBMS_TRANSACTION exceptions The DBMS_TRANSACTION package gives names (using the EXCEPTION_INIT pragma) to Oracle exceptions −8175 and −8176 as follows: Name Number Description. DISCRETE_TRANSACTION_FAILED −8175 Discrete transaction restriction violated. An attempt was made to perform an action that is not currently supported [Appendix A] What's on the Companion Disk? 4.2.1 Getting Started with DBMS_TRANSACTION 222 in a discrete transaction. Roll back the transaction and retry it as a normal transaction. CONSISTENT_READ_FAILURE −8176 Cannot continue consistent read for the table/index −− no undo records. Oracle encountered an operation that does not generate undo records. Retry the operation with a different snapshot time. If an index is involved, retry the operation without using the index. These exceptions may be raised in calls to the BEGIN_DISCRETE_TRANSACTION procedure. 4.2.2 Advising Oracle About In−Doubt Transactions The DBMS_TRANSACTION advise procedures (ADVISE_COMMIT, ADVISE_NOTHING, and ADVISE_ROLLBACK) specify what in−doubt transaction advice is sent to remote databases during distributed transactions. This advice appears on the remote database in the ADVICE column of the DBA_2PC_PENDING data dictionary view if the distributed transaction becomes in doubt (i.e., a network or machine failure occurs during the commit). The remote database administrator can then review the DBA_2PC_PENDING information and manually commit or roll back in−doubt transactions using the FORCE clause of the COMMIT or ROLLBACK commands. Each call to an ADVISE procedure remains in effect for the duration of that connection or until a different ADVISE procedure call is made. This allows you to send different advice to various remote databases. 4.2.2.1 The DBMS_TRANSACTION.ADVISE_ROLLBACK, and ADVISE_COMMIT procedures Here are the headers for the three advise procedures: PROCEDURE DBMS_TRANSACTION.ADVISE_ROLLBACK; PROCEDURE DBMS_TRANSACTION.ADVISE_NOTHING; PROCEDURE DBMS_TRANSACTION.ADVISE_COMMIT; 4.2.2.1.1 Example In the following example, we address a common data−warehousing scenario. We want to promote daily extract data from our legacy systems to each of our data marts and our corporate data warehouse. First, the extract data is summarized and loaded into a staging database copy of the fact table. Then, this fact table's data is promoted to each of the data marts and the data warehouse. The marketing department wants its data mart loaded very aggressively (i.e., ADVISE_COMMIT). The accounting department, being more conservative, wants its data mart loaded with caution (i.e., ADVISE_ROLLBACK). Finally, management does not have a preference for loading the data warehouse. We could run the following PL/SQL locally from our staging database: BEGIN FOR fact_rec IN (SELECT * FROM fact_load_table) LOOP DBMS_TRANSACTION.ADVISE_COMMIT; INSERT INTO fact_table@marketing_data_mart VALUES (fact_rec.product_id, fact_rec.location_id, fact_record.period_id, fact_rec.numeric_value1); DBMS_TRANSACTION.ADVISE_ROLLBACK; INSERT INTO fact_table@accounting_data_mart VALUES (fact_rec.product_id, fact_rec.location_id, fact_record.period_id, fact_rec.numeric_value1); DBMS_TRANSACTION.ADVISE_NOTHING; [Appendix A] What's on the Companion Disk? 4.2.2 Advising Oracle About In−Doubt Transactions 223 INSERT INTO fact_table@corp_data_warehouse VALUES (fact_rec.product_id, fact_rec.location_id, fact_record.period_id, fact_rec.numeric_value1); COMMIT; END LOOP; END; / 4.2.3 Committing Data The DBMS_TRANSACTION package offers a number of programs you can use to issue COMMITs in your application. 4.2.3.1 The DBMS_TRANSACTION.COMMIT procedure The COMMIT procedure is provided primarily for completeness. It is equivalent to the COMMIT command of PL/SQL. Here's the header for this procedure: PROCEDURE DBMS_TRANSACTION.COMMIT; There is no advantage to using this program instead of the COMMIT command. 4.2.3.2 The DBMS_TRANSACTION.COMMIT_COMMENT procedure The COMMIT_COMMENT procedure specifies what in−doubt transaction comment is sent to remote databases during distributed transactions. The specification for the procedure follows: PROCEDURE DBMS_TRANSACTION.COMMIT_COMMENT (cmnt IN VARCHAR2); This comment (cmnt parameter) appears on the remote database in the TRAN_COMMENT column of the DBA_2PC_PENDING data dictionary view if the distributed transaction becomes in doubt (i.e., a network or machine failure occurs during the commit). The remote database administrator can then review the DBA_2PC_PENDING information and manually commit or roll back in−doubt transactions using the FORCE clause of the COMMIT or ROLLBACK commands. In the following example, we update our previous data mart and data warehouse promotion PL/SQL code to utilize the COMMIT_COMMENT procedure: BEGIN FOR fact_rec IN (SELECT * FROM fact_load_table) LOOP DBMS_TRANSACTION.ADVISE_COMMIT; INSERT INTO fact_table@marketing_data_mart VALUES (fact_rec.product_id, fact_rec.location_id, fact_record.period_id, fact_record.numeric value1); DBMS_TRANSACTION.ADVISE_ROLLBACK; INSERT INTO fact_table@accounting_data_mart VALUES (fact_rec.product_id, fact_rec.location_id, fact_record.period_id, fact_rec.numeric_value1); DBMS_TRANSACTION.ADVISE_NOTHING; INSERT INTO fact_table@corp_data_warehouse VALUES (fact_rec.product_id, fact_rec.location_id, fact_record.period_id, fact_rec.numeric_value1); [Appendix A] What's on the Companion Disk? 4.2.3 Committing Data 224 DBMS_TRANSACTION.COMMIT_COMMENT ('Fact Load for date: '||TO_CHAR(sysdate,'MON−DD−YYYY')); END LOOP; END; / 4.2.3.3 The DBMS_TRANSACTION.COMMIT_FORCE procedure The COMMIT_FORCE procedure manually commits local in doubt, distributed transactions. Here's the specification for the procedure: PROCEDURE DBMS_TRANSACTION.COMMIT_FORCE (xid IN VARCHAR2 ,scn IN VARCHAR2 DEFAULT NULL); Parameters are summarized in the following table. Parameter Description xid The transaction's local or global transaction ID. To find these transaction IDs, query the data dictionary view DBA_2PC_PENDING. scn System change number (SCN) under which to commit the transaction. Specifying a system change number (scn parameter) allows you to commit an in−doubt transaction with the same SCN assigned by other nodes, thus maintaining the synchronized commit time of the distributed transaction. If the scn parameter is omitted, the transaction is committed using the current SCN. Any decisions to force in−doubt transactions should be made after consulting with the database administrator(s) at the remote database location(s). If the decision is made to locally force any transactions, the database administrator should either commit or roll back such transactions (as was done by nodes that successfully resolved the transactions). Otherwise, the administrator should query the DBA_2PC_PENDING view's ADVICE and TRAN_COMMENT columns for further insight. For more information on this topic, see "Manually Overriding In−Doubt Transactions" in the Oracle Corporation document Oracle8 Server Distributed Systems. 4.2.4 Rolling Back Changes The DBMS_TRANSACTION package offers a number of programs you can use to issue rollbacks in your application. 4.2.4.1 The DBMS_TRANSACTION.ROLLBACK procedure The ROLLBACK procedure is provided primarily for completelness. It is equivalent to the ROLLBACK command of PL/SQL. The header for this procedure follows: PROCEDURE DBMS_TRANSACTION.ROLLBACK; There is no advantage to using this program instead of the ROLLBACK command. 4.2.4.2 The DBMS_TRANSACTION.ROLLBACK_FORCE procedure The ROLLBACK_FORCE procedure manually rolls back local in−doubt, distributed transactions. The specification for the procedure is, PROCEDURE DBMS_TRANSACTION.ROLLBACK_FORCE (xid IN VARCHAR2); [Appendix A] What's on the Companion Disk? 4.2.3 Committing Data 225 . DBMS_TRANSACTION The DBMS_TRANSACTION package is created when the Oracle database is installed. The dbmsutil.sql script (found in the built−in packages source code directory, as described in Chapter. information on this topic, see "Manually Overriding In−Doubt Transactions" in the Oracle Corporation document Oracle8 Server Distributed Systems. 4.2.4 Rolling Back Changes The DBMS_TRANSACTION. DBMS_TRANSACTION exceptions The DBMS_TRANSACTION package gives names (using the EXCEPTION_INIT pragma) to Oracle exceptions −8175 and −8176 as follows: Name Number Description. DISCRETE_TRANSACTION_FAILED