
The code gets reprogrammed and some of the code is no longer needed with the passage of time and then you need to ensure any new development avoids referencing old APIs. Removing old code can be a problem as far as backwards compatibility is concerned. Oracle database 12.2 introduces the "DEPRECATE PRAGMA" to mark code as deprecated and display compiler warnings if deprecated code is referenced by any newly compiled code.
How To Use DEPRECATE PRAGMA
Compiler warnings must be enabled for us to see the results of the
DEPRECATE
pragma.-- Enable just deprecated code warnings. ALTER SESSION SET PLSQL_WARNINGS='ENABLE:(6019,6020,6021,6022)'; -- Enable all warnings. ALTER SESSION SET PLSQL_WARNINGS='ENABLE:ALL';
The
DEPRECATE
pragma has two variations. Without an additional literal the standard messages are displayed. Not surprisingly, when we compile the deprecated code we see a message.CREATE OR REPLACE PROCEDURE my_proc AUTHID DEFINER ASPRAGMA DEPRECATE(my_proc);BEGINNULL;END; /SP2-0804: Procedure created with compilation warningsSQL> SHOW ERRORS Errors for PROCEDURE MY_PROC:-------- -----------------------------------------------------------------LINE/COL ERROR 2/3 PLW-06019: entity MY_PROC is deprecatedSQL>
More importantly, if we write some code that references the deprecated procedure we will see a warning.
CREATE OR REPLACE PROCEDURE my_calling_proc AUTHID DEFINER ASBEGIN my_proc; END; /SQL> SHOW ERRORSSP2-0804: Procedure created with compilation warnings-------- -----------------------------------------------------------------Errors for PROCEDURE MY_CALLING_PROC: LINE/COL ERRORSQL>3/3 PLW-06020: reference to a deprecated entity: MY_PROC declared in unit MY_PROC[1,11]
We can use a literal string to alter the compiler warning message, which can be used to indicate the API we should have called rather than the deprecated API.
CREATE OR REPLACE PROCEDURE my_proc AUTHID DEFINER ASPRAGMA DEPRECATE(my_proc, 'Use MY_PROC2 instead of MY_PROC.');BEGINNULL;END; /SP2-0804: Procedure created with compilation warningsSQL> SHOW ERRORS Errors for PROCEDURE MY_PROC:-------- -----------------------------------------------------------------LINE/COL ERROR 2/3 PLW-06019: entity MY_PROC is deprecatedCREATE OR REPLACE PROCEDURE my_calling_proc AUTHID DEFINER ASSQL> BEGIN my_proc; END; /-------- -----------------------------------------------------------------Errors for PROCEDURE MY_CALLING_PROC: LINE/COL ERROR3/3 PLW-06020: reference to a deprecated entity: MY_PROC declared inunit MY_PROC[1,11]. Use MY_PROC2 instead of MY_PROC.SQL>
How To Deprecate Packages
A whole package can be deprecated as follows.
CREATE OR REPLACE PACKAGE my_package AUTHID DEFINER ASPRAGMA DEPRECATE(my_package);PROCEDURE my_procedure;PROCEDURE my_procedure(p_in IN NUMBER);FUNCTION my_function RETURN NUMBER;SP2-0808: Package created with compilation warningsEND my_package; / SQL> SHOW ERRORS-------- -----------------------------------------------------------------Errors for PACKAGE MY_PACKAGE: LINE/COL ERRORSQL>2/3 PLW-06019: entity MY_PACKAGE is deprecated
We can mark individual items in the package as deprecated, rather than the whole package.
CREATE OR REPLACE PACKAGE my_package AUTHID DEFINER ASPROCEDURE my_procedure;PRAGMA DEPRECATE(my_procedure);PROCEDURE my_procedure(p_in IN NUMBER);FUNCTION my_function RETURN NUMBER;SP2-0808: Package created with compilation warningsEND my_package; / SQL> SHOW ERRORS-------- -----------------------------------------------------------------Errors for PACKAGE MY_PACKAGE: LINE/COL ERRORSQL>3/3 PLW-06019: entity MY_PROCEDURE is deprecated
We can also mark package cursors, types, variables and exceptions as deprecated.
CREATE OR REPLACE PACKAGE my_package AUTHID DEFINER ASCURSOR c_cursor IS SELECT dummy FROM dual;PRAGMA DEPRECATE(c_cursor);TYPE t_rec IS RECORD (id NUMBER,description VARCHAR2(50));PRAGMA DEPRECATE(t_rec);g_var NUMBER := 1;PRAGMA DEPRECATE(g_var);ex_my_exception EXCEPTION;PRAGMA DEPRECATE (ex_my_exception);END my_package;/SP2-0808: Package created with compilation warningsSQL> SHOW ERRORS Errors for PACKAGE MY_PACKAGE:-------- -----------------------------------------------------------------LINE/COL ERROREXCEPTION_INIT0/0 PLW-05021: exception EX_MY_EXCEPTION does not have a pragma10/3 PLW-06019: entity T_REC is deprecated4/3 PLW-06019: entity C_CURSOR is deprecated 12/9 PLW-06026: package specification exposes global variableSQL>13/3 PLW-06019: entity G_VAR is deprecated16/3 PLW-06019: entity EX_MY_EXCEPTION is deprecated
How To Deprecate Object Types
We can deprecate object types and their member functions in a similar way to packages. The following example deprecates the whole object type.
CREATE OR REPLACE TYPE t_my_type AUTHID DEFINER AS OBJECT (PRAGMA DEPRECATE(t_my_type),id NUMBER,description VARCHAR2(50),MEMBER PROCEDURE my_procedure,MEMBER FUNCTION my_function RETURN NUMBER); /SP2-0816: Type created with compilation warningsSQL> SHOW ERRORS Errors for TYPE T_MY_TYPE:-------- -----------------------------------------------------------------LINE/COL ERROR5/10 PLW-07203: parameter 'SELF' may benefit from use of the NOCOPY2/3 PLW-06019: entity T_MY_TYPE is deprecatedSQL>compiler hint
The following example deprecates individual properties and member functions.
CREATE OR REPLACE TYPE t_my_type AUTHID DEFINER AS OBJECT (id NUMBER, description VARCHAR2(50),PRAGMA DEPRECATE(description),MEMBER PROCEDURE my_procedure,PRAGMA DEPRECATE(my_procedure),MEMBER FUNCTION my_function RETURN NUMBER); /SP2-0816: Type created with compilation warningsSQL> SHOW ERRORS Errors for TYPE T_MY_TYPE:-------- -----------------------------------------------------------------LINE/COL ERROR5/10 PLW-07203: parameter 'SELF' may benefit from use of the NOCOPY4/3 PLW-06019: entity DESCRIPTION is deprecated6/3 PLW-06019: entity MY_PROCEDURE is deprecatedcompiler hintSQL>
This is how Deprecate Pragma works.
No comments: