The PL/SQL data dictionary: Make views work for you

Part 10 in a series of articles on understanding and using PL/SQL for accessing Oracle Database

PL/SQL is one of the core technologies at Oracle and is essential to leveraging the full potential of Oracle Database. PL/SQL combines the relational data access capabilities of the Structured Query Language with a flexible embedded procedural language, and it executes complex queries and programmatic logic run inside the database engine itself. This enhances the agility, efficiency, and performance of database-driven applications.

Steven Feuerstein, one of the industry’s best-respected and most prolific experts in PL/SQL, wrote a 12-part tutorial series on the language. Those articles, first published in 2011, have been among the most popular ever published on the Oracle website and continue to find new readers and enthusiasts in the database community. Beginning with the first installment, the entire series is being updated and republished; please enjoy!

If you’re reading this article, there’s a really good chance that you or your colleagues write PL/SQL code. Lots of it. Which means that you also will at least occasionally need to analyze that code, answering questions such as

• On which database objects does my program depend?
• Which of my packages contain calls to a subprogram in another package or a reference to a global variable?
• Do any of my subprograms contain parameters whose data types should not be used?
• Are all of my subprograms compiled with a sufficiently high level of optimization?

You can, of course, always use the search feature of your editor or integrated development environment to look through multiple database objects and files to find specific chunks of text. But those techniques won’t be enough to answer all of the above questions and many more challenges you will encounter.

Don’t despair! One of the most lovely aspects of writing PL/SQL code and compiling that code into the database is that Oracle Database offers a set of views—known collectively as the data dictionary—that enable you to use the SQL and PL/SQL languages to get answers to just about any question you have about your code. Table 1 offers a high-level overview of the data dictionary views most often used to manage PL/SQL code.

Table 1: Useful views for PL/SQL programmers

This article explores many of the views mentioned in Table 1, describing the most useful columns in the views and offering examples of how you can put those views to use.

Data dictionary fundamentals

The data dictionary consists of many tables and views created by the database instance. User schemas generally have no privileges on these tables; Oracle Database grants only SELECT access on the views.

Most data dictionary views come in three versions:

• The USER view: Information about database objects owned by the schema to which you are connected.
• The ALL view: Information about database objects to which the currently connected schema has access.
• The DBA view: Unrestricted information about all the database objects in a database instance. By the way, non-DBA schemas usually have no authority to query DBA views.

Let’s look at an example. Suppose I want to obtain a list of the objects—tables, views, packages, and so on—defined in the database.

The following query returns all the objects defined in my schema:

SELECT * FROM user_objects

The following query returns all the objects that are defined in my schema or for which I have been granted the privilege to use those objects in some way:

SELECT * FROM all_objects

Finally, the following query returns a list of all the objects defined in the database instance—if I have the authority to select from the view:

SELECT * FROM dba_objects

Usually the only difference between the USER view and the ALL view is that the latter contains one extra column, OWNER, that shows which schema owns the object.

The remainder of this article provides examples based on the USER view.

Display information about stored objects

The USER_OBJECTS view contains a row for every database object owned by your schema. The most commonly used columns are

• OBJECT_NAME: Name of the object
• OBJECT_TYPE: Type of the object, such as PACKAGE, FUNCTION, or TRIGGER
• STATUS: Status of the object—VALID or INVALID
• LAST_DDL_TIME: Time stamp indicating the last time this object was changed

Here are some examples of queries against USER_OBJECTS.

• Show the names of all tables in my schema:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT object_name
    FROM user_objects
   WHERE object_type = 'TABLE'
   ORDER BY object_name

• Show the names of all objects whose status is invalid:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT object_type, object_name
    FROM user_objects
   WHERE status = 'INVALID'
   ORDER BY object_type, object_name

  The status of a program unit (PL/SQL package, procedure, or function) is set to INVALID if a database object on which it depends is changed. That program unit must then be recompiled (which Oracle Database will often do automatically the next time you try to use that program unit).
• Show all objects that have been changed today:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT object_type, object_name, 
         last_ddl_time
    FROM user_objects
   WHERE last_ddl_time >= TRUNC (SYSDATE)
   ORDER BY object_type, object_name

Display and search source code

All the program unit source code you’ve compiled into the database is accessible through the USER_SOURCE view, whose columns are

• NAME: Name of the object
• TYPE: Type of the object (ranging from PL/SQL program units to Java source and trigger source)
• LINE: Number of the line of the source code
• TEXT: Text of the source code

You can write queries against USER_SOURCE to

• Find all the program units that call a particular subprogram of a package
• Verify that coding standards are being followed
• Find all occurrences of a literal value that needs to be changed

Here is an example: I need to change the parameter list and code of a procedure named CALC_TOTALS in the SALES_MGR package. I’d like to find out where this procedure is called, outside of the SALES_MGR package itself.

SELECT name, line, text
  FROM user_source
 WHERE UPPER (text) 
  LIKE '%SALES_MGR.CALC_TOTALS%'
 ORDER BY name, line

Of course, this query will also find comments that contain this string, and there could be invocations of CALC_TOTALS that are not found, such as

SALES_MGR.

CALC_TOTALS

Assuming, however, that you don’t write or format your code to break up subprogram calls like that, the query will do a pretty good job of identifying the places in your code you need to review.

And for an Oracle Database 11g instance, you could use the PL/Scope feature. See more about that later in this article.

Compiler settings of stored code

The USER_PLSQL_OBJECT_SETTINGS view provides information about compiler settings of stored PL/SQL objects. Key columns are

• PLSQL_OPTIMIZE_LEVEL: Optimization level that was used to compile the object
• PLSQL_CODE_TYPE: Compilation mode for the object
• PLSQL_DEBUG: Whether or not the object was compiled for debugging
• PLSQL_WARNINGS: Compiler warning settings that were used to compile the object
• NLS_LENGTH_SEMANTICS: NLS length semantics that were used to compile the object

Here are some examples of queries against USER_PLSQL_OBJECT_SETTINGS.

• Find all the program units that are not taking sufficient advantage of compile-time optimization in Oracle Database:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT name
    FROM user_plsql_object_settings
   WHERE plsql_optimize_level < 2

  An optimization level of 0 means no optimization at all. An optimization level of 1 means a minimal amount of optimization. Neither of these levels should be seen in a production environment.

• Identify all programs for which compile-time warnings (which provide feedback on the quality of your code) are disabled:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT name, plsql_warnings
    FROM user_plsql_object_settings
   WHERE plsql_warnings LIKE '%DISABLE%';

Detailed information about procedures and functions

The USER_PROCEDURES view provides information about all functions and procedures, both schema-level and those defined within packages, in your schema. Columns of this view are

• AUTHID: Shows whether a procedure or a function is defined as an invoker rights (CURRENT_USER) or definer rights (DEFINER) program unit
• DETERMINISTIC: Set to YES if the function is defined to be deterministic, which theoretically means that the value returned by the function is determined completely by the function’s argument values
• PIPELINED: Set to YES if the function is defined as a pipelined function, which means that it can be executed in parallel as part of a parallel query
• OVERLOAD: Set to a positive number if this subprogram is overloaded, which means that there are at least two subprograms with this name in the same package

Here are some examples of queries against USER_PROCEDURES.

• Find all the procedures and functions that will run under invoker rights (the privileges of the invoker of the program are used at runtime to resolve references to database objects such as tables):
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT   object_name
         , procedure_name 
      FROM user_procedures
     WHERE authid = 'CURRENT_USER'
  ORDER BY object_name, procedure_name

• Show all the functions declared to be deterministic:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT   object_name
         , procedure_name 
      FROM user_procedures
     WHERE deterministic = 'YES'
  ORDER BY object_name, procedure_name

Analyze and modify the trigger state

If you work with database triggers, USER_TRIGGERS, which contains a row for each trigger defined in your schema, will come in handy. Key columns are

• TRIGGER_NAME: The name of the trigger
• TRIGGER_TYPE: A string that shows if this is a BEFORE or AFTER trigger and whether it is a row- or statement-level trigger (in a trigger that is fired before an INSERT statement, for example, the value of this column is BEFORE STATEMENT)
• TRIGGERING_EVENT: The type of SQL operation—such as INSERT, INSERT OR UPDATE, DELETE OR UPDATE—that will cause the trigger to fire
• TABLE_NAME: The name of the table on which the trigger is defined
• STATUS: The status of the trigger—ENABLED or DISABLED
• WHEN_CLAUSE: An optional clause you can use to avoid unnecessary execution of the trigger body
• TRIGGER_BODY: The code executed when the trigger fires

Here are some examples of queries against USER_TRIGGERS.

• Find all disabled triggers:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT *
    FROM user_triggers 
   WHERE status = 'DISABLED'

• Find all row-level triggers defined on the EMPLOYEES table:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT *
    FROM user_triggers 
   WHERE table_name = 'EMPLOYEES'
     AND trigger_type LIKE '%EACH ROW'

• Find all triggers that fire when an UPDATE operation is performed:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT *
    FROM user_triggers 
   WHERE triggering_event LIKE '%UPDATE%'

One limitation in the USER_TRIGGERS view is that the TRIGGER_BODY column type is LONG, which means that it cannot be used in a SQL comparison.

Suppose, for example, that I want to find all the triggers whose trigger body contains the string “emp”. The following query, unfortunately, fails and produces an ORA-00932 error:

SELECT *
  FROM user_triggers
 WHERE trigger_body LIKE '%emp%'

So if you do want to search the contents of trigger bodies, you will need to use PL/SQL, in a block like this:

BEGIN
  FOR rec IN (SELECT * 
              FROM user_triggers)
  LOOP
    IF rec.trigger_body LIKE '%emp%'
    THEN
      DBMS_OUTPUT.put_line (
        'Found in ' || rec.trigger_name);
    END IF;
  END LOOP;
END;

Note that the USER_TRIGGER_COLS view keeps track of the columns that are referenced inside a trigger body.

Object dependency analysis

The USER_DEPENDENCIES view describes the dependencies between the procedures, packages, functions, package bodies, and triggers accessible to the current user. You can use it to perform impact analysis on your code, as in the following: How many programs will need to be changed if I change this table?

Key columns in this view are

• NAME: Name of the object
• TYPE: Type of the object
• REFERENCED_OWNER: Owner of the referenced object
• REFERENCED_NAME: Name of the referenced object
• REFERENCED_TYPE: Type of the referenced object

Here are some examples of queries against USER_DEPENDENCIES.

• Find all the objects that depend on (reference) the EMPLOYEES table:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT type, name 
     FROM user_dependencies
    WHERE  referenced_name = 'EMPLOYEES'
  ORDER BY type, name

• Find all the objects in the current schema on which the ORDER_MGR package depends:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT referenced_type
       , referenced_name 
      FROM user_dependencies
     WHERE name = 'ORDER_MGR'
       AND referenced_owner = USER
  ORDER BY referenced_type, 
           referenced_name

A best practice that I, and others, strongly recommend is to avoid repeating SQL statements by “hiding” those statements inside a procedure or a function. Let’s look at an example and then at how the USER_DEPENDENCIES view can help us identify violations of this best practice.

It is very common in PL/SQL code to find many queries that retrieve a single row for a primary key. Here’s a PL/SQL example with a query that uses the standard Oracle Database EMPLOYEES table:

PROCEDURE process_employee (
   employee_id_in IN INTEGER)
IS
   l_name   VARCHAR2 (100);
BEGIN
   SELECT last_name
     INTO l_name
     FROM employees
    WHERE employee_id = employee_id_in;
END;

Instead of writing this query each time, I suggest writing a function once that contains this query and returns the desired value. Then you can call the function as needed. Assuming that I have created a package named EMPLOYEES_API with a function named LAST_NAME, the above procedure can be changed to

PROCEDURE process_employee (
   employee_id_in IN INTEGER)
IS
   l_name   VARCHAR2 (100);
BEGIN
   l_name := 
      employees_api.
        last_name (employee_id_in);
END;

Now if I ever need to change the query for any reason (such as to take advantage of Oracle Database 11g’s function result cache feature), I’ll be able to make the change in one place, rather than having to find all occurrences of the query in my application code.

So suppose my development team has added this best practice to its coding standards: The only PL/SQL program units that should contain SQL statements are packages that end with the suffix _API.

I can then write a query against USER_DEPENDENCIES that identifies all program units that violate this rule:

SELECT name,
       TYPE,
       referenced_owner,
       referenced_name
  FROM user_dependencies
 WHERE     TYPE IN
              ('PACKAGE',
               'PACKAGE BODY',
               'PROCEDURE',
               'FUNCTION',
               'TRIGGER',
               'TYPE')
   AND referenced_type = 'TABLE'
   AND name NOT LIKE '%\_API' ESCAPE '\'
ORDER BY name
       , referenced_owner
       , referenced_name

Analyze argument information

USER_ARGUMENTS is a very useful view for PL/SQL programmers. It contains information about the arguments (also known as parameters) of each of the stored programs in your schema. It offers, simultaneously, a wealth of nicely parsed information and a complex structure. Key columns are

• OBJECT_NAME: The name of the procedure or function
• PACKAGE_NAME: The name of the package in which the procedure or function is defined
• ARGUMENT_NAME: The name of the argument
• POSITION: The position of the argument in the parameter list (if 0, this is the RETURN clause of a function)
• IN_OUT: The mode of the argument—IN, OUT, or IN OUT
• DATA_TYPE: The data type of the argument
• DATA_LEVEL: The nesting depth of the argument for composite types (for example, if one of your arguments’ data types is a record, USER_ARGUMENTS will have a row for this argument with a DATA_LEVEL of 0 and then a row for each field in the record with a DATA_LEVEL of 1)

Here are some examples of queries against USER_ARGUMENTS.

• Find all programs that have an argument of type LONG. This is the data type that was used to store large strings (more than 4,000 characters) in past versions of Oracle Database. Now the database uses large object types such as character large object (CLOB). Oracle recommends that any usages of LONG be converted to CLOB. USER_ARGUMENTS makes it easy to find all such usages in parameter lists:
  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

  SELECT object_name
       , package_name
       , argument_name
    FROM user_arguments
   WHERE data_type = ‘LONG’

• Find all functions that have an OUT or an IN OUT argument. A recommendation you will hear from many programming experts is that functions should contain only IN arguments. A function with an OUT or an IN OUT argument cannot be called inside a SQL statement, and it cannot be used in a function-based index. If you need to return multiple pieces of information, use a procedure or return a record. Listing 1 demonstrates a query that will identify all functions defined in packages that violate this best practice, and Table 2 provide details about what the query does.

  Code listing 1: Find functions that have an OUT or an IN_OUT argument

  Copy code snippet

  Copied to Clipboard

  Error: Could not Copy

  Copied to Clipboard

  Error: Could not Copy

   1  SELECT ua.object_name,
   2         ua.package_name,
   3         ua.argument_name,
   4         ua.in_out
   5    FROM (SELECT *
   6            FROM user_arguments
   7           WHERE position = 0) funcs,
   8         user_arguments ua
   9   WHERE     ua.in_out IN ('OUT', 'IN OUT')
  10         AND ua.position > 0
  11         AND ua.data_level = 0
  12         AND funcs.object_name = ua.object_name
  13         AND funcs.package_name = ua.package_name
  14         AND (   funcs.overload = ua.overload
  15              OR (funcs.overload IS NULL
  16                   AND ua.overload IS NULL))

   

  Lines	Description
  5–7	I use an inline view in the FROM clause to identify all those rows in USER_ARGUMENTS that are RETURN clauses (and therefore identify functions).
  9–11	I look for OUT or IN OUT arguments that are not in RETURN clauses and are not “nested” information, such as fields of a record argument.
  12–16	I use this rather lengthy join condition between the inline view (abbreviated as “funcs”) and USER_ARGUMENTS. The object names and package names must match, and the overload value must be the same or both must be NULL. The overload column is not NULL if the package has two or more subprograms with the same name.

  Table 2: Description of query behavior

A better USER_SOURCE

You can execute queries against USER_SOURCE to check for the presence or absence of certain strings and thus perform some fairly simplistic quality assurance checks of your code.

But Oracle offers a much more powerful means of analyzing your source code in Oracle Database 11g: with PL/Scope.

PL/Scope is a tool invoked by the PL/SQL compiler to collect information about all the identifiers (variables, procedures, functions, types, and so on) in your PL/SQL program unit and make it available through the USER_IDENTIFIERS view. This tool makes it relatively easy to get answers to questions that would otherwise require you to parse a PL/SQL program unit and then analyze the parse tree.

Here’s one example: My manager has asked me to remove from our programs any variables, constants, exceptions, and the like that are declared but never used. Finding all candidates for removal by simply searching code would be both time-consuming and error-prone.

With PL/Scope, it’s easy. USER_IDENTIFIERS contains a row for each declaration of an identifier. It may also contain other rows for usages of that identifier: a reference to it or a line of code that changes its value.

So a MINUS operation between these two sets of rows will leave us with all those identifiers that are declared but never referenced or used. Here’s the query for exceptions:

WITH subprograms_with_exception
        AS (SELECT DISTINCT owner
                          , object_name
                          , object_type
                          , name
              FROM all_identifiers has_exc
             WHERE     has_exc.owner = USER
                   AND has_exc.usage = 'DECLARATION'
                   AND has_exc.TYPE = 'EXCEPTION'),
     subprograms_with_raise_handle
        AS (SELECT DISTINCT owner
                          , object_name
                          , object_type
                          , name
              FROM all_identifiers with_rh
             WHERE     with_rh.owner = USER
                   AND with_rh.usage = 'REFERENCE'
                   AND with_rh.TYPE = 'EXCEPTION')
SELECT *
  FROM subprograms_with_exception
MINUS
SELECT *
FROM subprograms_with_raise_handle

PL/Scope is a powerful, flexible utility that can have a big impact on your ability to analyze code and identify ways to improve it. I wrote at more length about PL/Scope in “Zoom in on your code.”

It’s a gold mine in there

This article merely scratches the surface of the application information that can be mined from the data dictionary views in Oracle Database. PL/SQL editors such as Oracle SQL Developer provide user interfaces to many of these views, making it easier to browse their contents.

Dig deeper

• See the rest of the series.