Oracle DML Error Logging

Not all errors in Oracle are fatal, and that statement applies to data manipulation language statements as well. Even though an error in and of itself may be fatal, when handled properly it becomes benign. The question is this: how do you make an otherwise fatal error benign or harmless? There are at least three ways, two of which you are probably quite familiar with, and a lesser known, but very versatile third method.

The Tried and True Ways

Two methods of capturing DML errors and being able to deal with them in a suitable manner are SQL*Loader and PL/SQL exception handling. If your situation involves uploading data or writing blocks of exception handling code (and only checking for a few errors), then by and large, these manners are suitable. SQL*Loader can provide a wealth of information about a bad record via the log, bad, and discard files, but its usefulness across all DML operations is limited.

PL/SQL exception handling can also capture errors and provide information for feedback, but coding all of the potential places where an integrity error can occur, in addition to keeping track of an exception block’s scope, can grow to be quite tedious. Besides, are you sure you accounted for all of the possible errors? The PL/SQL approach also means having to wrap blocks in an inappropriate manner and repeating the error handling from block to block. The PL/SQL approach also incurs the cost of context switching because of having to switch between SQL and PL/SQL. There has to be a better way, and in this case, there does exist a better way, namely, that of what is referred to as DML error logging.

DML Error Logging Basics

Managing Tables, Chapter 15 of the Administrator’s Guide, explains what takes place during DML error logging.

To use DML error logging, you add a statement clause that specifies the name of an error logging table into which the database records errors encountered during DML operations. When you add this error logging clause to the INSERT statement, certain types of errors no longer terminate and roll back the statement. Instead, each error is logged and the statement continues. You then take corrective action on the erroneous rows at a later time.

The scenario just shown mentions INSERT, but DML error logging applies to UPDATE and DELETE as well. The basic steps (summarized from the documentation) are to:

If you do create an error logging table, you must include all of the mandatory error logging columns (although they can be created in any order). You may optionally create additional columns, which reference the DML table. An important point to keep in mind is that datatypes of the additional columns must be able to capture or handle the datatype of the DML column. For example, don’t make a number column in the error table when the DML table is trying to use VARCHAR2. Do, however, make the error table column datatype VARCHAR2 when dealing with a number in the DML table. Oracle will handle the casting for you (if it can). VARCHAR2(4000) is pretty much the default datatype you should use for typical DML column datatypes.

The mandatory columns in an (again, optional) error table are:

You have two options with respect to creating an error table. The first is to let Oracle do the work for you, and that requires using the DBMS_ERRLOG package. This built-in will not only create the mandatory columns just mentioned, but will also map the target DML table’s columns. The second and decidedly more difficult way is to manually create the logging table via a data definition language (DDL) CREATE TABLE statement. Under the manual method, you are responsible for ensuring the mandatory parts are in place and for mapping any additional columns.

The only real advantage to manually creating an error logging table is that you can name it whatever you want and add (or not) only some of the DML table’s columns. Otherwise, the table is named ERR$_<first 25 characters of the DML table’s name>.

The DBMS_ERRLOG Package

This package, described in Chapter 38 of Oracle® Database PL/SQL Packages and Types Reference, 10g Release 2 (10.2) employs a security model. For the most part, you can create an error logging table for any table (or view) you own. Some of the package’s input parameters can be null, and the only mandatory input parameter is the name of the DML (or target) table. There is only one procedure in this package, and that is the CREATE_ERROR_LOG procedure. To help prevent a datatype mismatch between the DML and error logging table, you may want to consider using the skip_unsupported input parameter (BOOLEAN, default is false, meaning an unsupported column type will cause the procedure to terminate).

Let’s look at an example/use case for DML error logging. To keep things simple, we will use the EMP table in Scott’s schema. The steps below show how easy it is to create the error logging table. Note how all of the columns in EMP have been mapped to VARCHAR2(4000)’s in ERR$_EMP.

SQL> set serveroutput on

SQL> exec DBMS_ERRLOG.CREATE_ERROR_LOG (‘EMP’);

PL/SQL procedure successfully completed.

SQL> desc err$_emp;

 Name                                                        Null?    Type

 ———————————————————– ——– —————-

 ORA_ERR_NUMBER$                                                      NUMBER

 ORA_ERR_MESG$                                                        VARCHAR2(2000)

 ORA_ERR_ROWID$                                                       ROWID

 ORA_ERR_OPTYP$                                                       VARCHAR2(2)

 ORA_ERR_TAG$                                                         VARCHAR2(2000)

 EMPNO                                                                VARCHAR2(4000)

 ENAME                                                                VARCHAR2(4000)

 JOB                                                                  VARCHAR2(4000)

 MGR                                                                  VARCHAR2(4000)

 HIREDATE                                                             VARCHAR2(4000)

 SAL                                                                  VARCHAR2(4000)

 COMM                                                                 VARCHAR2(4000)

 DEPTNO                                                               VARCHAR2(4000)

Now that the error logging table is created, let’s attempt a DML statement which we know will have an error. Try to duplicate the employee named MILLER.

SQL> INSERT INTO emp values (7934,’MILLER’,’CLERK’,7782,’23-JAN-82′,3900,null,20)

  2    LOG ERRORS INTO err$_emp (‘insert example’) REJECT LIMIT 25;

0 rows created.

We failed to insert into EMP, but what is in ERR$_EMP?

As another example, what if the ENAMEs were constrained to be not null? Issue “alter table emp modify (ename not null);” to achieve the desired effect, and then attempt an insert as shown below (with and without the error logging clause).

You have to admit this is much easier than using nested PL/SQL blocks where scope has to be considered to keep an operation running.

In Closing

The utility or usefulness of DML error logging is considerable if your application processes large amounts of records. Instead of (potentially) bombing out after running for hours, you can craft a means of allowing good records to be processed and then come back to problem records at a later time. This approach to programming does not imply you should minimize why an error occurred. Capturing badly formatted data is a clear case of utility, but handling incorrect referential data must be considered as to why or how DML failed.

» See All Articles by Columnist Steve Callan