12.2: Use DEPRECATE Pragma to Document Deprecated Units

View All Scripts Login to Run Script

Script Name 12.2: Use DEPRECATE Pragma to Document Deprecated Units
Description New to 12.2, you can now use the DEPRECATE pragma to document that a program unit (e.g., entire package) or subprogram (e.g., single procedure in a package) is deprecated and should not be used. You can then take advantage of compile-time warnings to help identify all places that deprecated code is used, and even render such code invalid for execution! Related blog post: http://stevenfeuersteinonplsql.blogspot.com/2016/10/122-helps-you-manage-persistent-code.html
Area PL/SQL General
Contributor Steven Feuerstein
Created Wednesday December 21, 2016

Statement 1
The key value-add for the DEPRECATE pragma is that new warnings have been added to help you analyze and find usages of deprecated code.
Turn on Compile-Time Warnings
```
ALTER SESSION SET plsql_warnings = 'enable:all'
```
```
Statement processed.
```

Statement 2

Specify the name of the package in the pragma. Notice the generation of the PLW-06019 warning.

Mark Entire Package as Deprecated

CREATE OR REPLACE PACKAGE pkg 
   AUTHID DEFINER 
AS 
   PRAGMA DEPRECATE(pkg); 
 
   PROCEDURE proc; 
   FUNCTION func RETURN NUMBER; 
END;

Warning: PACKAGE PKG
Line: 4 PLW-06019: entity PKG is deprecated

More Details: https://docs.oracle.com/error-help/db/ora-20001

Statement 3

Add Package Body

CREATE OR REPLACE PACKAGE BODY pkg
AS
   PROCEDURE proc
   IS
   BEGIN
      DBMS_OUTPUT.put_line ('old stuff');
   END;

   FUNCTION func
      RETURN NUMBER
   IS
   BEGIN
      RETURN 1;
   END;
END;

Package Body created.

Statement 4
Again, with warnings turned on, you are notified at time of compilation, via PLW-06020, that you are referencing an entity that is marked for deprecation.
Try Using Deprecated Unit
```
CREATE OR REPLACE PROCEDURE use_deprecated AUTHID DEFINER 
IS 
BEGIN 
   pkg.proc; 
END;
```
```
Warning: PROCEDURE USE_DEPRECATED
Line: 4 PLW-06020: reference to a deprecated entity: PKG declared in unit PKG[1,9]
```
More Details: https://docs.oracle.com/error-help/db/ora-20001
Statement 5
OK. You are SERIOUS. You do not want anyone using deprecated entities. So you specify that all deprecation-related warnings should be treated as "hard" compile errors. Take that!
Change Warnings into Errors
```
ALTER SESSION SET plsql_warnings='ERROR:(6019,6020,6021,6022)'
```
```
Statement processed.
```
Statement 6
But I went too far. The 6019 warning simply tells you that you *used* the pragma, not that you are used a deprecated entity. So that should stay as a warning.
Oh Wait Maybe Not 6019
```
CREATE OR REPLACE PACKAGE pkg 
   AUTHID DEFINER 
AS 
   PRAGMA DEPRECATE(pkg); 
 
   PROCEDURE proc; 
   FUNCTION func RETURN NUMBER; 
END;
```
```
Errors: PACKAGE PKG
Line: 4 PLS-06019: entity PKG is deprecated
```
More Details: https://docs.oracle.com/error-help/db/ora-24344

Statement 7

Deprecated Usages Set to Errors

ALTER SESSION SET plsql_warnings='ERROR:(6020,6021,6022)'

Statement processed.

Statement 8

Whew. That's good. Otherwise our existing code base is kaput.

Deprecated Package Still Compiles Without Error

CREATE OR REPLACE PACKAGE pkg 
   AUTHID DEFINER 
AS 
   PRAGMA DEPRECATE(pkg); 
 
   PROCEDURE proc; 
   FUNCTION func RETURN NUMBER; 
END;

Package created.

Statement 9
Sometimes you will not deprecate an entire package, but just a subset of subprograms within a package. Note that you can add a message to be displayed when warnings are enabled.
Deprecate Subprogram in Package
```
CREATE OR REPLACE PACKAGE pkg
   AUTHID DEFINER
AS
   PROCEDURE proc;

   PRAGMA DEPRECATE (proc, 'pkg.proc deprecated. Use pkg.new_proc instead.');

   PROCEDURE new_proc;
 END;
```
```
Package created.
```

Statement 10

Create Package Body

CREATE OR REPLACE PACKAGE BODY pkg
AS
   PROCEDURE proc
   IS
   BEGIN
      DBMS_OUTPUT.put_line ('old stuff');
   END;

   PROCEDURE new_proc
   IS
   BEGIN
      DBMS_OUTPUT.put_line ('new stuff');
   END;
END;

Package Body created.

Statement 11
Ouch! Not possible. With 6020 set as an error in my session, I now see "PLS-06020" - and "PLS" means compiler error, whereas "PLW" means warning. So my deprecated code is now strictly off limits.
Try to Use Deprecated Procedure
```
CREATE OR REPLACE PROCEDURE use_deprecated
IS
BEGIN
   pkg.proc;
END;
```
```
Errors: PROCEDURE USE_DEPRECATED
Line: 4 PLS-06020: reference to a deprecated entity: PROC declared in unit PKG[4,14].  pkg.proc deprecated. Use pkg.new_proc instead.
```
More Details: https://docs.oracle.com/error-help/db/ora-24344

Additional Information

Database on OTN SQL and PL/SQL Discussion forums
Oracle Database
Download Oracle Database