Merge pull request oracle-samples#73 from stevenfeuerstein/master

All error-related files in one pass

Author: dmcghan

plsql/error-management/basic-error-logging-package.sql

@@ -0,0 +1,83 @@
+/*
+This very, VERY basic error logging package demonstrations the critical elements: use an autonomous 
+transaction to write a row to the error log; call the full suite of error-related built-in functions 
+to gather all generic information; pass in application-specific data for logging.
+*/
+
+-- Error Logging Table
+CREATE TABLE error_log 
+( 
+   log_id       NUMBER GENERATED ALWAYS AS IDENTITY, 
+   created_on   TIMESTAMP WITH LOCAL TIME ZONE, 
+   created_by   VARCHAR2 (100), 
+   errorcode    INTEGER, 
+   callstack    VARCHAR2 (4000), 
+   errorstack   VARCHAR2 (4000), 
+   backtrace    VARCHAR2 (4000), 
+   error_info   VARCHAR2 (4000) 
+);
+
+-- Totally Minimal API for Error Logging
+-- Including an example of providing a name for an un-named system exception 
+-- raised when a FORALL with SAVE EXCEPTIONS encounters at least one failed statement.
+CREATE OR REPLACE PACKAGE error_mgr 
+IS 
+   failure_in_forall   EXCEPTION; 
+ 
+   PRAGMA EXCEPTION_INIT (failure_in_forall, -24381); 
+ 
+   PROCEDURE log_error (app_info_in IN VARCHAR2); 
+END;
+/
+
+-- Log the Error!
+-- Key points: it's an autonomous transaction, which means the row is inserted into the error 
+-- log without also committing other unsaved changes in the session (likely part of a business 
+-- transaction that is in trouble). Plus, I invoke the full set of built-in functions to gather 
+-- system-level information and write to table. Finally, I add the application-specific information.
+
+CREATE OR REPLACE PACKAGE BODY error_mgr 
+IS 
+   PROCEDURE log_error (app_info_in IN VARCHAR2) 
+   IS 
+      PRAGMA AUTONOMOUS_TRANSACTION; 
+      /* Cannot call this function directly in SQL */ 
+      c_code   CONSTANT INTEGER := SQLCODE; 
+   BEGIN 
+      INSERT INTO error_log (created_on, 
+                             created_by, 
+                             errorcode, 
+                             callstack, 
+                             errorstack, 
+                             backtrace, 
+                             error_info) 
+           VALUES (SYSTIMESTAMP, 
+                   USER, 
+                   c_code, 
+                   DBMS_UTILITY.format_call_stack, 
+                   DBMS_UTILITY.format_error_stack, 
+                   DBMS_UTILITY.format_error_backtrace, 
+                   app_info_in); 
+ 
+      COMMIT; 
+   END; 
+END;
+/
+
+-- Try it Out
+DECLARE 
+   l_company_id   INTEGER; 
+BEGIN 
+   IF l_company_id IS NULL 
+   THEN 
+      RAISE VALUE_ERROR; 
+   END IF; 
+EXCEPTION  
+   WHEN OTHERS 
+   THEN 
+      error_mgr.log_error ('Company ID is NULL - not allowed.'); 
+END;
+/
+
+SELECT backtrace, errorstack, callstack FROM error_log;
+

plsql/error-management/dbms-utility-backtrace.sql

@@ -0,0 +1,159 @@
+/*
+The DBMS_UTILITY.format_error_backtrace function, added in Oracle Database 10g Release 2, 
+is a critical subprogram to call when logging exceptions. It returns a string that traces 
+the error back to the line on which it was raised! Note: if you re-raise an exception as 
+it propagates up the stack, you will lose the "original" line number. The back trace function 
+always only traces back to the most recently raised exception.
+*/
+
+CREATE OR REPLACE PROCEDURE proc1 
+IS 
+BEGIN 
+   DBMS_OUTPUT.put_line ('running proc1'); 
+   RAISE NO_DATA_FOUND; 
+END; 
+/
+
+CREATE OR REPLACE PROCEDURE proc2 
+IS 
+   l_str   VARCHAR2 (30) := 'calling proc1'; 
+BEGIN 
+   DBMS_OUTPUT.put_line (l_str); 
+   proc1; 
+END; 
+/
+
+CREATE OR REPLACE PROCEDURE proc3 
+IS 
+BEGIN 
+   DBMS_OUTPUT.put_line ('calling proc2'); 
+   proc2; 
+END; 
+/
+
+-- Without Back Trace....
+-- The only way to "see" the line number on which the error was raised was to let the exception go unhandled.
+BEGIN  
+   DBMS_OUTPUT.put_line ('Proc3 -> Proc2 -> Proc1 unhandled');  
+   proc3;  
+END; 
+/
+
+-- Trap and Display Error Stack (Error Message)
+-- Sure, that works fine and is very good info to have, but the error stack (error message) will contain the line number on which the error was raised!
+BEGIN  
+   DBMS_OUTPUT.put_line ('Proc3 -> Proc2 -> Proc1 unhandled');  
+   proc3;  
+EXCEPTION  
+   WHEN OTHERS  
+   THEN  
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_stack);  
+END; 
+/
+
+-- Add Back Trace to Error Handler
+-- Now we trap the exception at the top level subprogram and view both the error stack and the back trace.
+CREATE OR REPLACE PROCEDURE proc3   
+IS   
+BEGIN   
+   DBMS_OUTPUT.put_line ('calling proc2');   
+   proc2;   
+EXCEPTION   
+   WHEN OTHERS   
+   THEN   
+      DBMS_OUTPUT.put_line ('Error backtrace at top level:');   
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_stack);   
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_backtrace);   
+END; 
+/
+
+BEGIN 
+   DBMS_OUTPUT.put_line ('Proc3 -> Proc2 -> Proc1 backtrace'); 
+   proc3; 
+END; 
+/
+
+-- Re-Raise Exception
+-- I show the back trace, but then re-raise.
+CREATE OR REPLACE PROCEDURE proc1   
+IS   
+BEGIN   
+   DBMS_OUTPUT.put_line ('running proc1');   
+   RAISE NO_DATA_FOUND;   
+EXCEPTION   
+   WHEN OTHERS   
+   THEN   
+      DBMS_OUTPUT.put_line ('Error backtrace in block where raised:');   
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_backtrace);   
+      RAISE;   
+END; 
+/
+
+-- Can't Trace All the Way Back
+-- The call to back trace in this upper-level subprogram no longer finds it way back to the line number of the original exception. That was wiped out with the call to RAISE;
+CREATE OR REPLACE PROCEDURE proc3   
+IS   
+BEGIN   
+   DBMS_OUTPUT.put_line ('calling proc2');   
+   proc2;   
+EXCEPTION   
+   WHEN OTHERS   
+   THEN   
+      DBMS_OUTPUT.put_line ('Error backtrace at top level:');   
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_backtrace);   
+END; 
+/
+
+BEGIN 
+   DBMS_OUTPUT.put_line ('Proc3 -> Proc2 -> Proc1, re-reraise in Proc1'); 
+   proc3; 
+END; 
+/
+
+-- Handle and Raise At Every Level
+-- And see how the back trace changes!
+CREATE OR REPLACE PROCEDURE proc1  
+IS  
+BEGIN  
+   DBMS_OUTPUT.put_line ('running proc1');  
+   RAISE NO_DATA_FOUND;  
+EXCEPTION  
+   WHEN OTHERS  
+   THEN  
+      DBMS_OUTPUT.put_line ('Error stack in block where raised:');  
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_backtrace);  
+      RAISE;  
+END; 
+/
+
+CREATE OR REPLACE PROCEDURE proc2 
+IS 
+BEGIN 
+   DBMS_OUTPUT.put_line ('calling proc1'); 
+   proc1; 
+EXCEPTION 
+   WHEN OTHERS 
+   THEN 
+      RAISE VALUE_ERROR; 
+END; 
+/
+
+CREATE OR REPLACE PROCEDURE proc3  
+IS  
+BEGIN  
+   DBMS_OUTPUT.put_line ('calling proc2');  
+   proc2;  
+EXCEPTION  
+   WHEN OTHERS  
+   THEN  
+      DBMS_OUTPUT.put_line ('Error backtrace at top level:');  
+      DBMS_OUTPUT.put_line (DBMS_UTILITY.format_error_backtrace);  
+END; 
+/
+
+BEGIN 
+   DBMS_OUTPUT.put_line 
+           ('Proc3 -> Proc2 -> Proc1, re-reraise in Proc1, raise VE in Proc2'); 
+   proc3; 
+END; 
+/