Using INSERT ALL with related tables

In this article I will demonstrate a method where the INSERTALL statement can be used to insert rows into two tables that are related by a foreign key constraint.

The following example was developed and tested using the Pre-Built Oracle Database App Development VM which at the time of this post used Oracle Database 12.1.0.2.0  & SQL Developer 4.0.3.16.  The example was created within the standard HR schema.

First I create two tables:


CREATE TABLE parent_tbl (the_pk    NUMBER PRIMARY KEY,
                         object_id NUMBER);

CREATE TABLE child_tbl (the_pk      NUMBER PRIMARY KEY,
                        the_fk      NUMBER,
                        object_name VARCHAR2(30));

Next I add a foreign to define the relationship between these tables and two sequences used to populate the primary keys:


ALTER TABLE child_tbl
ADD CONSTRAINT child_tbl_fk1 FOREIGN KEY (the_fk)
   REFERENCES parent_tbl (the_pk);

CREATE SEQUENCE parent_tbl_seq;

CREATE SEQUENCE child_tbl_seq START WITH 500;

Next I ensure that the foreign key relationship is working as expected by trying to insert a record into the child table with value for the_fk column that doesn’t exist in parent_tbl:


INSERT INTO child_tbl
(the_pk,
the_fk,
object_name)
VALUES
(child_tbl_seq.nextval,
999,
'SomeObject');

Attempting to run this statement results in the expected error message:

SQL Error: ORA-02291: integrity constraint (HR.CHILD_TBL_FK1) violated - parent key not found

With the tables and relationship between them in place I can now demostrate how to use INSERTALL to insert information from user_objects into the parent and child tables.


INSERT ALL
INTO parent_tbl(the_pk, object_id) 
VALUES (parent_tbl_seq.nextval, 
        object_id)
INTO child_tbl(the_pk, the_fk, object_name) 
VALUES (child_tbl_seq.nextval,
        parent_tbl_seq.currval,
        object_name)
SELECT uo.object_id,
       uo.object_name
FROM user_objects uo
/

Lines 2 – 4 insert into the parent table, note the use of the sequence to populate the primary key.

Lines 5 – 8 insert into the child table, the important part (and the focus of this article) is to understand how the foreign key column, the_fk is populated. It uses currval of the sequence that was used to populate the parent table.

Thanks go to Tom Kyte for coming up with this elegant solution.

Summary

In this article I have demonstrated how to use INSERTALL to insert into two tables that are related by a foreign key.

Acknowledgements

The idea for this article came from Tom Kyte’s answer to this Ask Tom question.

The best lesson I learnt from Steve McConnell

CodeCompleteI was made aware of the book Code Complete by Steve McConnell almost by accident. I was attending an Oracle presentation back in 2001 and the presenter, Steven Feuerstein mentioned the book. I can’t remember what context it was mentioned in but I remembered I had to get a copy.

Reading the first edition of Code Complete became a series of wow moments. As a self taught programmer each chapter heralded a new revelation. I say proudly that this one book has had the biggest positive impact in my professional life as a programmer.

It is therefore very difficult to pick the best lesson I learnt from Steve McConnell. It finally came down to a choice of two; Valid Reasons to Create a Routine and the chapter on Debugging.

In the end I decided that it was Valid Reasons to Create a Routine. I won’t reveal the most important reason here but the answer will surprise you. It’s not to avoid duplicate code BTW.

If you want to know the answer I recommend you buy the book, I already know you will not regret it.

PL/SQL FizzBuzz

One of the popular exercises when learning a new language is to develop a FizzBuzz program.

This is where you print out the all the numbers from 1 to 100 except if a number is a multiple of 3 you print out Fizz and if the number is a multiple of 5 you print out Buzz. If a number is a multiple of both 3 and 5 then you print out FizzBuzz.

I came across this challenge for the first time recently as I learn C# so here is my version of FizzBuzz written in PL/SQL.


DECLARE

   fizz BOOLEAN := FALSE;
   buzz BOOLEAN := FALSE;

BEGIN

   FOR i IN 1 .. 100
   LOOP

      fizz := MOD(i, 3) = 0;
      buzz := MOD(i, 5) = 0;

      CASE

         WHEN fizz AND buzz THEN

            dbms_output.put_line('FizzBuzz');

         WHEN fizz THEN

            dbms_output.put_line('Fizz');

         WHEN buzz THEN

            dbms_output.put_line('Buzz');

         ELSE

            dbms_output.put_line(i);

      END CASE;

   END LOOP;
 
END;

 

Found a problem with the Oracle Documentation? Report it!

I was recently working through Chapter 9 of the 12c Database 2 Day Developer’s Guide and found the following bug in the sample code.

Here is the original code:

FUNCTION add_department
    ( p_department_name   IN departments.department_name%TYPE,
      p_manager_id        IN departments.manager_id%TYPE )
    RETURN departments.department_id%TYPE
  IS
    l_department_id departments.department_id%TYPE;
  BEGIN
    INSERT INTO departments ( department_id, department_name, manager_id )
    VALUES ( departments_sequence.NEXTVAL, p_department_name, p_manager_id );

    RETURN l_department_id;
  END add_department;

 
The function creates a new department and should return the newly created department id. Except it doesn’t. The variable used to return the newly created department id, l_department_id is never set so it will always returns null.

One solution to this bug is to use the Returning Into clause and the revised code would be:

...
    INSERT INTO departments ( department_id, department_name, manager_id )
    VALUES ( departments_sequence.NEXTVAL, p_department_name, p_manager_id )
    RETURNING department_id INTO l_department_id;
 
    RETURN l_department_id;
...

 
It’s a trivial issue so why I am writing about it? The reason is that seeing this problem I could have easily moved on and finished the chapter but I noticed the Feedback button and thought that others will also encounter this problem and may waste time wondering why the department id is not being returned.

OFeedback

After clicking the feedback button and using my OTN account (you also have the choice of remaining anonymous), describing the issue along with the suggested fix as described above I pressed submit and thought no more about it.

Within 24 hours I had an email reply from someone at Oracle (and someone not using a do_not_reply email address) thanking me for pointing out the error and assuring me it will be fixed in future editions. Whilst it remains to be seen if this will be done, the response to my feedback has left a very positive impression with me which made me glad I made the effort to report this issue.

So if you spot something within the masses of Oracle documentation, report it and help fix those broken windows.

The PL/SQL Continue statement

Introduced in Oracle Database 11.1 The PL/SQL CONTINUE statement allows you to skip the current  loop iteration. It can be used conditionally and unconditionally.

Unconditional Example

BEGIN

   FOR i IN 1 .. 10
   LOOP
 
      IF i = 2
      THEN
         CONTINUE; 
      END IF;
 
      DBMS_OUTPUT.PUT(i || ', ');
 
    END LOOP;

    DBMS_OUTPUT.NEW_LINE;

END;

In the example above, there is no output when the loop executes iteration 2, Running this code shows the following output.

1, 3, 4, 5, 6, 7, 8, 9, 10,

 Conditional Example

BEGIN

   FOR i IN 1 .. 10
   LOOP
 
      CONTINUE WHEN i = 2; 
 
      DBMS_OUTPUT.PUT(i || ', ');
 
   END LOOP;
 
   DBMS_OUTPUT.NEW_LINE;

END;

Again in this example there is no output for iteration 2. Running this code shows the following output.

1, 3, 4, 5, 6, 7, 8, 9, 10,

The conditional use removes the need for the IF statement used in the unconditional example and makes the code more concise without losing readability.

Summary

In this article I have shown with short code examples how to use the PL/SQL Continue statement.

This article has not discussed whether the use of a CONTINUE statement is a bad programming practise, there are already enough arguments discussions about that.

Source: The Continue Statement within the Database documentation 

No surprises with Oracle 12c Identity Column performance

Oracle 12c introduced the Identity Column. You can find out more about this feature in the new features guide and within the CREATE TABLE documentation.

In this article I will use Tom Kyte’s run stats utility to compare the performance of the IDENTITY column with the explicit use of a sequence object. The script below will be used to insert 10,0000, 100,000 and finally a million rows.

The tests were performed using Virtual Box running the pre built Database App Development VM. The database version at this time was 12.1.0.2.0 and all the examples were developed using SQL Developer 4.0.3.16

To support the tests,  the following objects are required. Firstly, a table using the IDENTITY column is created. Note the syntax for creating an IDENTITY column. In addition as I know there will be some large inserts into this table I have adjusted cache size of the sequence accordingly.


CREATE TABLE t_identity(id      NUMBER         GENERATED AS IDENTITY CACHE 1000
                                               CONSTRAINT t_identity_pk PRIMARY KEY,
                        details VARCHAR2(32))
/

Next a table and a sequence which will be used to hold the results of the inserts via a regular Oracle sequence is created. Again the sequence cache size has been increased from the default.

CREATE TABLE t_seq(id      NUMBER CONSTRAINT t_seq_pk PRIMARY KEY,
                   details VARCHAR2(32))
/

CREATE SEQUENCE s1 CACHE 1000
/

Below is the test script. As a brief overview, it initialises the call to the runstats package, it then inserts the required number of records into the table with the IDENTITY column.

The runstats package is called again to show that the first part of the processing has finished and the second part is about to start. The second insert is identical to the first one with the exception of the explicit call to the sequence object.

Thanks to Oracle Base for the tip about using TIMESTAMP as a seed to dbms_random. I am not advocating using row by row processing to insert volumes of data of this size in the real world!


BEGIN

   runstats_pkg.rs_start();

END;
/

DECLARE

   l_data VARCHAR2(32);
   l_seed VARCHAR2(32);

BEGIN

   l_seed := TO_CHAR(SYSTIMESTAMP,'YYYYDDMMHH24MISSFFFF');

   dbms_random.seed (val => l_seed);

   FOR i IN 1 .. 1000000
   LOOP

      l_data := dbms_random.string(opt => 'a', len => 32);

      INSERT INTO t_identity(details)
      VALUES(l_data);

   END LOOP;

   COMMIT;

END;
/

BEGIN

   runstats_pkg.rs_middle();

END;
/

DECLARE

   l_data VARCHAR2(32);
   l_seed VARCHAR2(32);

BEGIN

   l_seed := TO_CHAR(SYSTIMESTAMP,'YYYYDDMMHH24MISSFFFF');

   dbms_random.seed (val => l_seed);

   FOR i IN 1 .. 1000000
   LOOP

      l_data := dbms_random.string(opt => 'a', len => 32);

      INSERT INTO t_seq(id,
                        details)
      VALUES(s1.nextval,
             l_data);

   END LOOP;

   COMMIT;

END;
/

BEGIN

   runstats_pkg.rs_stop(1000);

END;
/

Here is the runstats output for each of the runs

10,000 rows inserted


Run1 ran in 106 cpu hsecs
Run2 ran in 105 cpu hsecs
run 1 ran in 100.95% of the time
...
Run1 latches total versus runs -- difference and pct
Run1      Run2      Diff  Pct
171,097   171,432   335   99.80%

100,000 rows inserted


Run1 ran in 1216 cpu hsecs
Run2 ran in 1156 cpu hsecs
run 1 ran in 105.19% of the time
...
Run1 latches total versus runs -- difference and pct
Run1        Run2        Diff      Pct
1,719,582   2,061,024   341,442   83.43%

1,000,000 rows inserted

Run1 ran in 12308 cpu hsecs
Run2 ran in 11835 cpu hsecs
run 1 ran in 104% of the time
...
Run1 latches total versus runs -- difference and pct
Run1         Run2         Diff      Pct
18,480,661   18,761,711   281,050   98.50%

and the difference between the two methods is negligible.

Summary

In this article, using Tom Kyte’s runstats utility, I have invested the performance of the Oracle 12c new feature; IDENTITY column

Acknowledgements

Tom Kyte for his seminal package runstats

 

The most important reason why you should know how to use PL/SQL Conditional Compilation.

….is that when you really need to, it allows you to turn up your applications instrumentation  to 11.

A 30 second PL/SQL Conditional Compilation overview

PL/SQL Conditional compilation was introduced with Oracle Database 10gR2. The official documentation  explains how to use the Conditional Compilation constructs but doesn’t give too many use cases. Fortunately the Oracle White Paper PL/SQL conditional compilation not only covers how to use Conditional Compilation, it also gives a number of use cases and finishes with an in depth case study.

Conditional Compilation allows you to mark your portions of your code so that a preprocessor can determine what will actually be sent to the compiler.  Rather than bore you with more words lets look at a simple example.

CREATE PROCEDURE cc_intro
IS
BEGIN

   $IF sys.dbms_db_version.ver_le_12_1
   $THEN

      dbms_output.put_line('Can use the 12c new features'); 

   $ELSE 

      dbms_output.put_line('Have to use the work arounds'); 

   $END

END cc_intro;

In this example, if the procedure is compiled on a database running 12.1 the first message will appear in the compiled version of the code otherwise the second message will appear.

On line 5 the Conditional Compilation selection directive begins with $IF. The value tested must resolve to a static boolean value such as literals, inquiry directives or as in this example a package constant. Notice that the selection directive finishes with $END and not END IF. Also there is no semi-colon after $END.

Once the procedure has been compiled, you can view the code as the compiler will “see” it using the supplied dbms_preprocessor.print_post_processed_source


BEGIN

   dbms_preprocessor.print_post_processed_source
   (
      object_type => 'PROCEDURE',
      schema_name => USER,
      object_name => 'CC_INTRO'
   );

END;
/

After running on my Oracle 12.1 database the following is seen.

PROCEDURE cc_intro
IS
BEGIN 

 dbms_output.put_line('Can use the 12c new features'); 

END cc_intro;

As expected, only the first message exists in the compiled code.

The most important reason

Following months (weeks, hours or minutes!!) of the various stages of testing,  new changes have finally made it into production. At first everything is great and is ticking along nicely. Until it doesn’t. Strange things start to happen. That thing that can’t happen is happening. To add to the complexity try as you might the problem appears to happen only in production.

You trace the problem back to a routine where perhaps a XML document is created or a collection is populated. Unfortunately you are unable to see what these normally opaque data structures contains and that information could be key to solving the issue.

A method that I have often seen to get round this problem is to wrap code with a standard IF statement as shown in Procedure B below.


CREATE PACKAGE pkg_no_cc
IS

   PROCEDURE a;

END pkg_no_cc;
/

CREATE OR REPLACE PACKAGE BODY pkg_no_cc
IS

   g_debugging BOOLEAN := FALSE;

   PROCEDURE b
   IS 

      TYPE emps_tbl IS TABLE OF employees%ROWTYPE
         INDEX BY PLS_INTEGER;

      l_xml        XMLTYPE;
      l_collection emps_tbl; 

   BEGIN

      -- Expected business logic is here...
      dbms_output.put_line('This is procedure b');

      IF g_debugging = TRUE
      THEN 

         -- see what is in the collection
         FOR i IN 1 .. l_collection.COUNT()
         LOOP

            dbms_output.put_line('see the output of the collection'); 

         END LOOP; 

         -- view the xml
         dbms_output.put_line('the xml: ' || l_xml.getstringval() );

      END IF; 

   END b; 

   PROCEDURE a
   IS
   BEGIN

      dbms_output.put_line('Calling procedure b');

      b();

   END a;

END pkg_no_cc;
/

If the debugging statement within Procedure B survived a Code Review and made it
into production it would cause an overhead, no matter how small (they all add up) every time
Procedure B was invoked. It also would be unlikely that this would be the only occurrence of this type statement within your production code so the overhead would be significant and hence the resistance to allowing this level of information reaching production.

Here is the same package rewritten to take advantage of PL/SQL Conditional Compilation.
Other than the package name change, the only change is the replacement of the IF statement
in Procedure B with Conditional Compilation selection and inquiry directive. At this point the inquiry directive hasn’t been created.

CREATE PACKAGE pkg_with_cc
IS

   PROCEDURE a;

END pkg_with_cc;
/

CREATE OR REPLACE PACKAGE BODY pkg_with_cc
IS

   PROCEDURE b
   IS 

      TYPE emps_tbl IS TABLE OF employees%ROWTYPE
         INDEX BY PLS_INTEGER;

      l_xml XMLTYPE;
      l_collection emps_tbl; 

   BEGIN

      -- Expected business logic is here
      dbms_output.put_line('This is procedure B');

      $IF $$debuging = TRUE
      $THEN 

         -- see what is in the collection
         FOR i IN 1 .. l_collection.COUNT()
         LOOP

            dbms_output.put_line('see the output of the collection'); 

         END LOOP; 

         -- view the xml
         dbms_output.put_line('the xml: ' || l_xml.getstringval() );

      $END  

   END b; 

   PROCEDURE a
   IS
   BEGIN

      dbms_output.put_line('Calling procedure b');

      b();

   END a;

END pkg_with_cc;
/

Using dbms_preprocessor.print_post_processed_source to look at the compiled code


BEGIN

   dbms_preprocessor.print_post_processed_source
   (
      object_type => 'PACKAGE BODY',
      schema_name => USER,
      object_name => 'PKG_WITH_CC'
   );

END;
/

The output shows the debugging code has been stripped out by the PL/SQL preprocessor.


PACKAGE BODY pkg_with_cc
IS

   PROCEDURE b
   IS 

      TYPE emps_tbl IS TABLE OF employees%ROWTYPE
         INDEX BY PLS_INTEGER;

      l_xml XMLTYPE;
      l_collection emps_tbl; 

   BEGIN

      -- Expected business logic is here
      dbms_output.put_line('This is procedure B'); 

   END b; 

   PROCEDURE a
   IS
   BEGIN

      dbms_output.put_line('Calling procedure b');

      b();

   END a;

END pkg_with_cc;
/

Now lets recompile the package body, adding the inquiry directive, debugging at the same time.

ALTER PACKAGE PKG_WITH_CC COMPILE BODY
   PLSQL_CCFLAGS = 'debuging:TRUE' REUSE SETTINGS
/

The debugging literal matches $$debugging used by the procedure B and it is set to TRUE. I have included “REUSE SETTINGS” because it ensures that existing values for PL/SQL warnings or PL/SQL Optimizer Level are not discarded.

Running the dbms_preprocessor.print_post_processed_source and viewing the compiled version of the code we now see that the debugging code is present and ready to help solve the production issue.


...no changes to the other parts of the package

   PROCEDURE b
   IS 

      TYPE emps_tbl IS TABLE OF employees%ROWTYPE
         INDEX BY PLS_INTEGER;

      l_xml XMLTYPE;
      l_collection emps_tbl; 

   BEGIN

      -- Expected business logic is here
      dbms_output.put_line('This is procedure B'); 

      -- see what is in the collection
      FOR i IN 1 .. l_collection.COUNT()
      LOOP

         dbms_output.put_line('see the output of the collection'); 

      END LOOP; 

      -- view the xml
      dbms_output.put_line('the xml: ' || l_xml.tostringval() );

 END b; 

...

Once finished we can remove the debugging code from production by recompiling the package body but this time setting the debugging flag to FALSE

ALTER PACKAGE PKG_WITH_CC COMPILE BODY
   PLSQL_CCFLAGS = 'debuging:FALSE' REUSE SETTINGS
/

Summary

Just to be clear, using Conditional Compilation as described in this post requires recompilation of production code which is not something that should ever been taken lightly and great care should be exercised whenever doing so.

Having the ability to leave debugging code in Production and enable it on demand, is in my
opinion, reason enough to add PL/SQL Conditional Compilation to your developer toolbox. Used judiciously with an instrumented application it further reduces the number of places that bugs can hide.

An introduction to Application Context

The inspiration for this article came from reading Mark Hoxey excellent post on avoiding ORA-04068: existing state of packages has been discarded One of the potential solutions to this problem suggested by Mark is to use Application Context. I didn’t know too much about Application Context so this post is my way of documenting and sharing what I learnt.

What is Application Context?

Application Context a set of name value pairs stored in memory. Each context is essentially a namespace which contains one or more name value pairs. Application Context is a large subject and Oracle list a number of potential uses cases for Application Context.

My goal for this post is not to rewrite the documentation but to provide a walk through of creating an Application Context that could serve as replacement for the constant or variable data that is often duplicated in various package bodies scattered throughout your application.

All the examples in this article were built using Oracle’s pre-built Database App Development Virtual Machine which used Database version 11.2.0.2.

Example

CREATE OR REPLACE CONTEXT user_ctx USING pkg_user_application_context
/

The first line creates an Application Context with the name user_ctx. The USING clause identifies the PL/SQL package that can set or reset the context variables. In this example pkg_user_application_context is used. It is worth mentioning that the package specified by the USING clause does not need to exist at the time when the context is created but it must exist at run time. So the next step is create pkg_user_application_context

CREATE OR REPLACE PACKAGE pkg_user_application_context
IS

 PROCEDURE set_context_values;

END pkg_user_application_context;
/

CREATE OR REPLACE PACKAGE BODY pkg_user_application_context
IS
 PROCEDURE set_context_values
 IS

    ld_hire_date      DATE;
    ln_department     NUMBER(5);
    lv_is_a_manager   VARCHAR2(1);

 BEGIN

 -- Pretend look ups from HR tables happens here...

 DBMS_SESSION.SET_CONTEXT('user_ctx', 'hire_date', TO_CHAR(ld_hire_date, 'YYYYMMDD'));

 DBMS_SESSION.SET_CONTEXT('user_ctx', 'department_id', TO_CHAR(ln_department,'99999'));

 DBMS_SESSION.SET_CONTEXT('user_ctx', 'is_a_manager', lv_is_a_manager);

END pkg_user_application_context;
/

The package body shows a look up of various values from tables (which are not shown to keep the example from becoming too bloated) These values are then used by the call to DBMS_SESSION.SET_CONTEXT to create a number of name value pairs under the context created earlier.

A couple of points worth making; the values are stored as characters so for numbers and dates the appropriate calls to TO_CHAR are required and all the values created belong to the same Application Context, user_ctx

If an attempt is made to change the values of the Application context outside of the package pkg_user_application_context such as the following anonymous block :

BEGIN
   DBMS_SESSION.SET_CONTEXT('user_ctx', 'is_a_manager', 'Y');
END;
/

you will see the  following error message:


ERROR at line 1:
ORA-01031: insufficient privileges
ORA-06512: at "SYS.DBMS_SESSION", line 101
ORA-06512: at line 2   

With both the Application Context and supporting package created we can now go ahead and start using the values within our application:

CREATE OR REPLACE PACKAGE BODY pkg_some_other_package
IS
 PROCEDURE interesting_hr_stuff
 IS

    ld_hire_date      DATE;
    ln_department     NUMBER(5);
    lv_is_a_manager   VARCHAR2(1);

 BEGIN

    ld_hire_date := TO_DATE(SYS_CONTEXT('user_ctx','hire_date'), 'YYYYMMDD');

    ln_department := TO_NUMBER(SYS_CONTEXT('user_ctx','department_id'));

    lv_is_a_manager := SYS_CONTEXT('user_ctx','is_a_manager');

    -- now work with the variables 

 END interesting_hr_stuff

END pkg_some_other_package;
/

The example shows another package (the spec is not shown) where the values are retrieved from the Application Context using the built in SYS_CONTEXT. The values are explicitly converted back to the expected data types and then used within the application.

Summary

In this article I have explained what an Application Context is and demonstrated how to create one use as a replacement for storing information that was previously held in package body constants and variables.

Acknowledgements

Mark Hoxey

Oracle PL/SQL Compiler warning PLW-06009

The PL/SQL Compiler warning “PLW-06009: procedure “string” OTHERS handler does not end in RAISE or RAISE_APPLICATION_ERROR”  was introduced with 11g release 1.

It’s purpose is to alert you to the fact that you have a WHEN OTHERS exception handler and the last statement within it doesn’t contain a RAISE or a RAISE_APPLICATION_ERROR statement.

The first example shows what you will see if you turned the compiler warnings off.

ALTER SESSION SET PLSQL_WARNINGS='DISABLE:ALL'
/

and compile the following procedure:

CREATE OR REPLACE PROCEDURE p
IS
BEGIN
   RAISE no_data_found;
EXCEPTION
   WHEN OTHERS THEN
      NULL;
END p;

The important thing to note is that on line 7 the WHEN OTHERS statement does nothing with the exception, effectively suppressing it.

Creating the procedure in SQLPlus I see a “clean” compile:

1

 

 

 

 

 

 

 

 

Now I will enable PL/SQL Compiler warnings:

ALTER SESSION SET PLSQL_WARNINGS='ENABLE:ALL'
/

and recompile the procedure

ALTER PROCEDURE p COMPILE
/

This time I can see I haven’t had such a “clean” compile:

2

 

 

 

The show errors command displays the following:

3

 

As you can see the PLW-06009 warning is shown. I can then choose ignore the warning or amend the procedure to fix the problem.

If you agree with Tom Kyte and believe that WHEN OTHERS without any kind of RAISE statement is a bug then as with all compiler warnings you can turn the warning into an error and stop the program unit from compiling.

I change the warning to an error: (In this example I am changing the parameter at session level but it can be changed at the instance level)


ALTER SESSION SET PLSQL_warnings = 'ERROR:06009'
/

Now when I try to compile my procedure I see that it is invalid and will not compile until I fix the WHEN OTHERS issue.

5
Here is the revised version of the procedure that fixes the PLW-06009 warning. The only change required was to replace NULL with RAISE on line 9.

CREATE OR REPLACE PROCEDURE p
IS
BEGIN

   RAISE no_data_found;

EXCEPTION
   WHEN OTHERS THEN
      RAISE;
END p;

Running this version of the procedure and I see that the PLW-06009 warning no longer appears.

4

 

More information about PL/SQL compile time warnings can be found in the documentation.

Summary

In this article I have explained what the PLW-06009 compiler warning is and how it can be enabled both as a warning and an error.

Acknowledgements

Tom Kyte

Instrumenting your PL/SQL code

Introduction

As an exceptional Oracle Developer you already know the value of instrumenting your code. You have read enough of Tom Kyte, Cary Millsap & Steve McConnell to understand that with the correct instrumentation diagnosing problems especially time critical problems (are there any others?) becomes much easier.

So the question is not why you should instrument your code but how. In this article I will explain the installation and use of the PL/SQL Logger which was originally developed by Tyler Muth and is now available on Github.

Installation

Once you have downloaded Logger from Githib and unzip the contents to a directory that can be seen by your Oracle client (I use SQL Plus). navigate to the directory “releases” and expand the folder for the Logger release you wish to install. At the time of writing version 2.1.2 was the latest so that will be the version used in this article.

Whilst you can install logger into an existing schema, I am going to use the supplied @create_user.sql to install Logger into it’s own schema. So start SQL Plus and connect to the database as system or a user with the DBA role and run the following script

@create_user.sql

When prompted to do so, enter the username, tablespace, temporary tablespace and password for the new schema. In this example I have accepted the suggested defaults of logger_user, users and temp respectively.

Now connect to the database as the newly created logger_user and run the installation script:

@logger_install.sql

If you run into problems with the installation it is worth starting with the supplied documentation.

In this article I will be accessing the Logger objects from the standard Oracle HR user so the following grant is required:

GRANT EXECUTE ON logger TO hr
/

Once installation is complete, you can view the status of the logger by running the following command

exec logger.status;

which displays the following:


SQL> exec logger.status;
Project Home Page :
https://github.com/tmuth/Logger---A-PL-SQL-Logging-Utility/
Logger Version : 2.1.2
Debug Level : DEBUG
Capture Call Stack : TRUE
Protect Admin Procedures : TRUE
APEX Tracing : Enabled
SCN Capture : Disabled
Min. Purge Level : DEBUG
Purge Older Than : 7 days
Pref by client_id expire : 12 hours
For all client info see : logger_prefs_by_client_id

PL/SQL procedure successfully completed.

How to use

Below is a procedure that updates the salary of a given employee. Now lets pretend it is part of a overnight batch job and is just one of thousands of procedures that need to run. To the outside world this procedure is a blackbox. Without querying the employee after the procedure has run (and committed) you have no idea what has happened when it was called.


CREATE OR REPLACE PROCEDURE raise_salary
(
   p_emp_id     IN employees.employee_id%TYPE,
   p_new_salary IN employees.salary%TYPE
)
IS
BEGIN

   UPDATE employees e
      SET e.salary = p_new_salary
    WHERE e.employee_id = p_emp_id;

END raise_salary;
/

Lets change that by adding some instrumentation.


CREATE OR REPLACE PROCEDURE raise_salary
(
   p_emp_id     IN employees.employee_id%TYPE,
   p_new_salary IN employees.salary%TYPE
)
IS
BEGIN

 logger_user.logger.log('Start of raise_salary');

 UPDATE employees e
   SET e.salary = p_new_salary
 WHERE e.employee_id = p_emp_id;

 logger_user.logger.log('Number of rows updated: {' || TO_CHAR(SQL%ROWCOUNT) || '}'); 

 logger_user.logger.log('End of raise_salary'); 

END raise_salary;
/

The revised version of the procedure captures some basic information as the start of the procedure, how many rows were updated and finally that the procedure completed successfully.

Even in this simple case it is easy for the real code to be submerged by the instrumentation code. There is no one size fits all solution. Careful consideration is required to decide how much instrumentation is required.

When the procedure is run, one of the Logger views can be queried and the output reviewed:


SELECT text
  FROM logger_user.logger_logs_5_min
/

Here is the output from the revised procedure after it has been run:


TEXT
----------------------------
Start of raise_salary
Number of rows updated: {1}
End of raise_salary

 Level Up

The output from Logger is controlled by the level constant. The level can be set by calling the logger.set_level procedure. In the previous example I have used the log procedure to instrument my routine. This means that the output will insert an entry into the logger_logs table when the logger_level is set to debug.

There are a number of additional log_x routines that you can use with the various logging levels. For instance, log_warning will insert an entry into the logger_logs table when the logger level has been set to “warning”, likewise if you are only interested in capturing errors, you can set the Logger level to error and use the logger_error procedure.

One of the nicest features of the level facility is the ability to turn logging on for specified clients rather than system wide. In the following example, I have turned on debug logging for user 1 whilst user 2 continues to use the system but without instrumentation messages being inserted.

Logger_user session

The following commands are run:

exec logger_user.logger.set_level(p_level => 'OFF')
/

This system wide command turns Logger off. This means currently no instrumentation is being recorded.

exec logger_user.logger.set_level(p_level => 'DEBUG', p_client_id => 'user_one')
/

This command turns on debug logging for the client identifier user_one. (see user one session below for how this is set). This means any instrumentation that uses the logger.log procedure will be inserted into the log table.

The following query will show you the current clients that logging is enable for:

SELECT *
  FROM logger_prefs_by_client_id
/

User_one session

The following command sets the client identifier (this is used by the call to enable logging for this client by the Logger_user session above)


exec dbms_session.set_identifier('user_one');

I then execute the raise_salary procedure and commit.

User_two session

Almost a carbon copy of the user_one session with the exception of the identifier.


exec dbms_session.set_identifier('user_two');

I then execute the raise_salary procedure and commit.

Now when I query the logger table I see the following output which shows that only user_one’s actions have been captured.


SQL> SELECT client_identifier, text
2      FROM logger_user.logger_logs_5_min
3 /

CLIENT_IDENTIFIER TEXT
------------------------------------
user_one Start of raise_salary

user_one Number of rows updated: {1}

user_one End of raise_salary

But wait there is more…

All of the main Logger procedures allow you to give context to the information you are recording. The context would normally be where the message has originated from, i.e. Application, Package etc. The facility is provided by the p_scope parameter. Here is the raise_salary procedure used earlier refactored to include the p_scope parameter.


CREATE OR REPLACE PROCEDURE raise_salary_scope
(
   p_emp_id     IN employees.employee_id%TYPE,
   p_new_salary IN employees.salary%TYPE
)
IS

   l_scope logger_user.logger_logs.scope%type := 'raise_salary_scope';

BEGIN

   logger_user.logger.log('Start', l_scope);

   UPDATE employees e
      SET e.salary = p_new_salary
    WHERE e.employee_id = p_emp_id;

   logger_user.logger.log('Number of rows updated: {' || TO_CHAR(SQL%ROWCOUNT) || '}', l_scope);

   logger_user.logger.log('End', l_scope);

END raise_salary_scope;
/

Each of the calls to the log procedure now has the name of procedure contained within the l_scope parameter passed to it.

The following query shows results of using the scope parameter


SQL> SELECT scope, text
2      FROM logger_user.logger_logs_5_min
3    /

SCOPE                TEXT
------------------------------------------------
raise_salary_scope   Start

raise_salary_scope   Number of rows updated: {1}

raise_salary_scope   End

The logging of parameter values is handled within Logger by using the p_params object. This is easier to show with an example rather than even more text!

Here is the final revision of the raise_salary procedure.


CREATE OR REPLACE PROCEDURE raise_salary_params
(
   p_emp_id     IN employees.employee_id%TYPE,
   p_new_salary IN employees.salary%TYPE
)
IS

   l_scope    logger_user.logger_logs.SCOPE%TYPE := 'raise_salary_scope';
   l_params   logger_user.logger.tab_param;

BEGIN

   logger_user.logger.append_param(l_params, 'p_emp_id', p_emp_id);
   logger_user.logger.append_param(l_params, 'p_new_salary', p_new_salary);

   logger_user.logger.log('Start', l_scope, null, l_params);

   UPDATE employees e
      SET e.salary = p_new_salary
    WHERE e.employee_id = p_emp_id;

   logger_user.logger.log('Number of rows updated: {' || TO_CHAR(SQL%ROWCOUNT) || '}', l_scope);

   logger_user.logger.log('End', l_scope);

END raise_salary_params;
/

The parameters are added to a pre-defined Logger associative array and that array is included in the first call to the log procedure.

The parameters are stored in the extra column and the following query shows how to display them.


SQL> SELECT text, extra
2      FROM logger_user.logger_logs_5_min
3    /

TEXT                         EXTRA
---------------------------------------------------------------------------------
Start                        *** Parameters *** p_emp_id: 100 p_new_salary: 4500

Number of rows updated: {1}

End

Summary

There is no getting away from the fact that the instrumentation is an overhead to your application. Trying to find the balance between too much and too little information that is to be captured, the extra code you need to develop and then the extra resources required to execute the larger code base all need to be carefully considered.

My opinion is that this is a price I am willing to pay. When bad things happen and you are under pressure to track down the cause you will find the problem far quicker with code that is telling you what exactly is happening. Compare this with the alternative. Peering into an enormous black box armed only with guesses.

Acknowledgements

Tyler Muth

Martin Giffy D’Souza