Example 13-9 Enabling the Deprecation Warnings

ALTER SESSION SET PLSQL_WARNINGS='ENABLE:(6019,6020,6021,6022)';

Example 13-10 Deprecation of a PL/SQL Package

This example shows the deprecation of a PL/SQL package as a whole. Warnings will be issued for any reference to package pack1, and to the procedures foo and bar when used outside of the package and its body.

PACKAGE pack1 AS
PRAGMA DEPRECATE(pack1);
 PROCEDURE foo;
 PROCEDURE bar;
END pack1;

Example 13-11 Deprecation of a PL/SQL Package with a Custom Warning

This example shows the deprecation of a PL/SQL package. The compiler issues a custom warning message when a reference in another unit for the deprecated procedure foo is compiled.

PACKAGE pack5 AUTHID DEFINER AS
PRAGMA DEPRECATE(pack5 , ’Package pack5 has been deprecated, use new_pack5 instead.’);
 PROCEDURE foo;
 PROCEDURE bar;
END pack5;

A reference to procedure pack5.foo in another unit would draw a warning like this.

SP2-0810: Package Body created with compilation warnings

Errors for PACKAGE BODY PACK6:
4/10     PLW-06020: reference to a deprecated entity: PACK5 declared in unit PACK5[1,9].  
         Package pack5 has been deprecated, use new_pack5 instead

Example 13-12 Deprecation of a PL/SQL Procedure

This example shows the deprecation of a single PL/SQL procedure foo in package pack7.

PACKAGE pack7 AUTHID DEFINER AS
  PROCEDURE foo;
  PRAGMA DEPRECATE (foo, ’pack7.foo is deprecated, use pack7.bar instead.’);
  PROCEDURE bar;
END pack7;

Example 13-13 Deprecation of an Overloaded Procedure

This example shows the DEPRECATE pragma applies only to a specific overload of a procedure name. Only the second declaration of proc1 is deprecated.

PACKAGE pack2 AS
  PROCEDURE proc1(n1 NUMBER, n2 NUMBER, n3 NUMBER);
  -- Only the overloaded procedure with 2 arguments is deprecated
  PROCEDURE proc1(n1 NUMBER, n2 NUMBER);
      PRAGMA DEPRECATE(proc1);
 END pack2;

Example 13-14 Deprecation of a Constant and of an Exception

This example shows the deprecation of a constant and of an exception.

PACKAGE trans_data AUTHID DEFINER AS
   TYPE Transrec IS RECORD (
     accounttype VARCHAR2(30) ,
     ownername VARCHAR2(30) ,
     balance REAL
   );
   min_balance constant real := 10.0;
   PRAGMA DEPRECATE(min_balance , ’Minimum balance requirement has been removed.’);
   insufficient_funds EXCEPTION;
   PRAGMA DEPRECATE (insufficient_funds , ’Exception no longer raised.’);
END trans_data;

Example 13-15 Using Conditional Compilation to Deprecate Entities in Some Database Releases

This example shows the deprecation of procedure proc1 if the database release version is greater than 11.

CREATE PACKAGE pack11 AUTHID DEFINER AS
 $IF DBMS_DB_VERSION.VER_LE_11 
 $THEN
    PROCEDURE proc1;
 $ELSE
    PROCEDURE proc1;
    PRAGMA DEPRECATE(proc1);
 $END
 PROCEDURE proc2;
 PROCEDURE proc3;
END pack11;

Example 13-16 Deprecation of an Object Type

This example shows the deprecation of an entire object type.

TYPE type01 AS OBJECT(
   PRAGMA DEPRECATE (type01), 
   y NUMBER, 
   MEMBER PROCEDURE proc(x NUMBER), 
   MEMBER PROCEDURE proc2(x NUMBER) 
);

Example 13-17 Deprecation of a Member Function in an Object Type Specification

This example shows the deprecation of member function add2 in an object type specification.

TYPE objdata AS OBJECT(
  n1 NUMBER ,
  n2 NUMBER ,
  n3 NUMBER ,
  MEMBER FUNCTION add2 RETURN NUMBER ,
   PRAGMA DEPRECATE (add2),
  MEMBER FUNCTION add_all RETURN NUMBER
 );

Example 13-18 Deprecation of Inherited Object Types

This example shows that a reference to a deprecated entity x declared in unit type15_basetype type body will cause the compiler to issue a warning.

TYPE type15_basetype AS OBJECT 
( 
  x1 NUMBER, 
  x  NUMBER, 
  PRAGMA DEPRECATE (x), 
  MEMBER PROCEDURE f0 , 
  PRAGMA DEPRECATE (f0), 
  MEMBER PROCEDURE f1 ,
  PRAGMA DEPRECATE (f1),
  MEMBER PROCEDURE f2 ,
  PRAGMA DEPRECATE (f2),
  MEMBER PROCEDURE f3) NOT FINAL;

TYPE BODY type15_basetype AS 
   MEMBER PROCEDURE f0 
   IS 
   BEGIN 
     x := 1; 
   END; 
   MEMBER PROCEDURE f1 
   IS 
   BEGIN 
     x := 1; 
   END; 

   MEMBER PROCEDURE f2
   IS
   BEGIN
     x := 1;
   END;

   MEMBER PROCEDURE f3
   IS
   BEGIN
     x := 1;
   END;
END;

References to the deprecated entities x, f0, and f2 in type15_basetype type body will cause the compiler to issue a warning.

TYPE type15_subtype UNDER type15_basetype ( 
  y NUMBER , 
  MEMBER PROCEDURE f1(z NUMBER), 
  MEMBER PROCEDURE f1(z NUMBER , m1 NUMBER), 
  PRAGMA DEPRECATE(f1), 
  OVERRIDING MEMBER PROCEDURE f2 
);

TYPE BODY type15_subtype AS 
   MEMBER PROCEDURE f1(z NUMBER)
IS 
BEGIN 
  -- deprecation attribute inherited in derived type. 
  x := 1;
  x1:= 2; 
  SELF.f0; 
END; 

   MEMBER PROCEDURE f1(z  NUMBER , 
                    m1 NUMBER) 
   IS 
   BEGIN 
     NULL; 
   END; 
   OVERRIDING MEMBER PROCEDURE f2 
   IS 
   BEGIN 
     /* refer to deprecated f2 in supertype */ 
     (SELF AS type15_basetype).f2; 
     /* No warning for a reference to a not deprecated data member in the supertype */ 
     x1 := 1; 
   END; 
END;

References to deprecated entities x, f1, and f0 in unit type15_basetype will cause the compiler to issue a warning.

PROCEDURE test_types3 
AS 
  e type15_subtype ; 
  d type15_basetype ; 
BEGIN 
  e := type15_subtype (1 ,1 ,1); 
  d := type15_basetype (1, 1); 
  d.x := 2; -- warning issued 
  d.f1;     -- warning issued 
  e.f1 (4); -- overloaded in derived type. no warning. not deprecated in the derived type. 
  e.f1 (1); -- no warning  
  e.f0;     -- f0 is deprecated in base type. deprecation is inherited. warning issued 
            -- warning issued for deprecated x in d.x and e.x 

  DBMS_OUTPUT.PUT_LINE(to_char(e.x) || to_char(' ') || to_char(d.x)); 

END;

Example 13-19 Deprecation Only Applies to Top Level Subprogram

This examples shows that the DEPRECATE pragma may not be used to deprecate a nested procedure. The compiler issues a warning about the misuse of the pragma on the entity. The pragma has no effect.

PROCEDURE foo
IS
   PROCEDURE inner_foo
   IS
   PRAGMA DEPRECATE (inner_foo, 'procedure inner_foo is deprecated');
   BEGIN
     DBMS_OUTPUT.PUT_LINE('Executing inner_foo');
   END;
BEGIN
  DBMS_OUTPUT.PUT_LINE('Executing foo');
END; 

Example 13-20 Misplaced DEPRECATE Pragma

The DEPRECATE pragma must appear immediately after the declaration of the deprecated item. A warning about the misplaced pragma will be issued and the pragma will have no effect.

PROCEDURE bar
IS
BEGIN
   PRAGMA DEPRECATE(bar);
   DBMS_OUTPUT.PUT_LINE('Executing bar.');
END;

Example 13-21 Mismatch of the Element Name and the DEPRECATE Pragma Argument

This example shows that if the argument for the pragma does not match the name in the declaration, the pragma is ignored and the compiler does not issue a warning.

PACKAGE pkg13
AS
  PRAGMA DEPRECATE ('pkg13', 'Package pkg13 is deprecated, use pkg03');
  Y NUMBER;
END pkg13;

If an identifier is applied with a mismatched name, then the compiler issues a warning about the pragma being misplaced. The pragma has no effect.

CREATE PACKAGE pkg17
IS
  PRAGMA DEPRECATE ("pkg17");
END pkg17;