Oracle Built−in Packages- P102 pdf

Index−by (PL/SQL) table type 251 BOOLEAN 252 10.2.1.4 Exceptions DBMS_DESCRIBE.DESCRIBE_PROCEDURE may raise any of the exceptions listed in the following table. Error Code Description ORA−20000 A package was specified. DESCRIBE_PROCEDURE currently allows you to request only describes for top−level ("standalone") programs (procedure and functions) or programs within a package. ORA−20001 You requested a describe of a procedure or function that does not exist within the package. ORA−20002 You requested a describe of a procedure or function that is remote (either by including a database link or by passing a program name that is actually a synonym for a program defined using a database link). DESCRIBE_PROCEDURE is currently unable to describe remote objects. ORA−20003 You requested describe of an object that is marked invalid. You can describe only valid objects. Recompile the object and then describe it. ORA−20004 There was a syntax error in the specification of the object's name. Notice that these exceptions are not defined in the specification of the package. Instead, DESCRIBE_PROCEDURE simply calls RAISE_APPLICATION_ERROR with the error numbers listed earlier. These error numbers may therefore conflict with your own −20NNN error number usages (this is a very bad design decision on Oracle's part). If you embed calls to DESCRIBE_PROCEDURE inside your application or utility, watch out for the confusion such conflicts can cause. 10.2.1.5 Restrictions There are several limitations on using DESCRIBE_PROCEDURE: • You cannot describe remote objects (i.e., PL/SQL program elements that are defined in another database instance). • You cannot get a describe or a listing of all elements defined in a package specification. You need to know the name of the procedure or function within the package in other to get a describe of it. • DBMS_DESCRIBE.DESCRIBE_PROCEDURE will not show you the internal structure (attributes) of Oracle8 elements such as object types, variable arrays, and nested tables. 10.2.2 Explaining DBMS_DESCRIBE Results In the following sections and in subsequent examples I will demonstrate different ways of using DBMS_DESCRIBE.DESCRIBE_PROCEDURE. I will be working with the following objects: CREATE TABLE account (account_no number, person_id number, balance number(7,2)); CREATE TABLE person (person_id number(4), [Appendix A] What's on the Companion Disk? 10.2.1 Getting Started with DBMS_DESCRIBE 496 person_nm varchar2(10)); I will also describe objects in a package called desctest, which is defined in the psdesc.tst file on the companion disk. The output I display from the DESCRIBE_PROCEDURE is generated by the psdesc (PL/SQL DESCribe) package, which is explained in the "Section 10.2.3, "DBMS_DESCRIBE Example"" section and is defined in the psdesc.spp file. 10.2.2.1 Specifying a program name The valid syntax for a PL/SQL object to be described follows: [[part1.]part2.]part3 Here are various valid object specifications for DBMS_DESCRIBE.DESCRIBE_PROCEDURE: Object Specification Description showemps Standalone procedure or synonym to same emppkg.employee_name Function inside a package scott.delete_dept Standalone procedure in the SCOTT schema scott.emppkg.update_salary Procedure inside a package in the SCOTT schema You can also describe procedures and functions in the STANDARD and DBMS_STANDARD packages (the default packages of PL/SQL, containing the core elements of the language). To do this, you must prefix the name of the built−in with its package name, as in: 'STANDARD.TO_CHAR' 10.2.2.2 The DESCRIBE level The level array discloses the hierarchy of the elements in a program's arguments. The level applies only to the following subset of composite datatypes: records and PL/SQL tables. The default level of 0 means that it is the top level. For scalars, that is the only level. For composites, 0 indicates that you are pointing to the actual composite argument. Each successive value of level (positive integers: 1, 2, etc.) indicates that the argument attribute or field is a child of the previous level. The following example demonstrates how DESCRIBE_PROCEDURE generates its levels. Suppose that I have the following elements defined inside a package: /* Filename on companion disk: psdesc.tst */* CREATE OR REPLACE PACKAGE desctest IS TYPE number_table IS TABLE OF NUMBER INDEX BY BINARY_INTEGER; TYPE myrec1 IS RECORD (empno NUMBER, indsal NUMBER); TYPE myrec2 IS RECORD (ename VARCHAR2(20), hiredate DATE, empno_info myrec1); TYPE myrec3 IS RECORD (deptno NUMBER, totsal NUMBER, all_emp_info myrec2); TYPE myrec_table IS TABLE OF myrec1 INDEX BY BINARY_INTEGER; PROCEDURE composites (account_in NUMBER, person person%ROWTYPE, multirec myrec3, num_table number_table, recs_table myrec_table); END; / [Appendix A] What's on the Companion Disk? 10.2.2 Explaining DBMS_DESCRIBE Results 497 I have double−nested a record (myrec1 inside myrec2 inside myrec3), a table based on a record (myrec_table), and a "simple" table−based record (person%ROWTYPE). Here are the results from DBMS_DESCRIBE.DESCRIBE_PROCEDURE: SQL> exec psdesc.showargs ('desctest.composites') OvLd Pos Lev Type Name −−−− −−− −−− −−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−−−−−− 0 1 0 NUMBER ACCOUNT_IN 0 2 0 RECORD PERSON 0 1 1 NUMBER PERSON_ID 0 2 1 VARCHAR2 PERSON_NM 0 3 0 RECORD MULTIREC 0 1 1 NUMBER DEPTNO 0 2 1 NUMBER TOTSAL 0 3 1 RECORD ALL_EMP_INFO 0 1 2 VARCHAR2 ENAME 0 2 2 DATE HIREDATE 0 3 2 RECORD EMPNO_INFO 0 1 3 NUMBER EMPNO 0 2 3 NUMBER INDSAL 0 4 0 INDEX−BY TABLE NUM_TABLE 0 1 1 NUMBER RETURN Value 0 5 0 INDEX−BY TABLE RECS_TABLE 0 1 1 RECORD RETURN Value 0 1 2 NUMBER EMPNO 0 2 2 NUMBER INDSAL 10.2.2.3 How overloading is handled When you overload, you define more than one program with the same name. You will usually do this in packages. DESCRIBE_PROCEDURE creates a set of rows in the arrays for each overloading of a program. It then generates a unique, sequential number in the overload array to indicate that (a) the program is overloaded (a value of 0 indicates no overloading), and (b) to which overloading the arguments belong. Suppose that the desctest package has two overloaded versions of the upd function (the only difference is in the datatype of the last parameter, NUMBER vs. DATE). CREATE OR REPLACE PACKAGE desctest IS FUNCTION upd (account_in NUMBER, person person%ROWTYPE, amounts number_table, trans_date DATE) RETURN account.balance%TYPE; FUNCTION upd (account_in NUMBER, person person%ROWTYPE, amounts number_table, trans_no NUMBER) RETURN account.balance%TYPE; END; / Then the output from DBMS_DESCRIBE.DESCRIBE_PROCEDURE would be as follows: SQL> exec psdesc.showargs ('desctest.upd') OvLd Pos Lev Type Name −−−− −−− −−− −−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−− 1 0 0 NUMBER RETURN Value 1 1 0 NUMBER ACCOUNT_IN 1 2 0 RECORD PERSON 1 1 1 NUMBER PERSON_ID 1 2 1 VARCHAR2 PERSON_NM [Appendix A] What's on the Companion Disk? 10.2.2 Explaining DBMS_DESCRIBE Results 498 1 3 0 INDEX−BY TABLE AMOUNTS 1 1 1 NUMBER RETURN Value 1 4 0 DATE TRANS_DATE −−−− −−− −−− −−−−−−−−−−−−−−− −−−−−−−−−−−−−−−−−−− 2 0 0 NUMBER RETURN Value 2 1 0 NUMBER ACCOUNT_IN 2 2 0 RECORD PERSON 2 1 1 NUMBER PERSON_ID 2 2 1 VARCHAR2 PERSON_NM 2 3 0 INDEX−BY TABLE AMOUNTS 2 1 1 NUMBER RETURN Value 2 4 0 NUMBER TRANS_NO 10.2.3 DBMS_DESCRIBE Example The most important example I can think of for DBMS_DESCRIBE.DESCRIBE_PROCEDURE is the construction of a utility that makes it easier to use this procedure. Without such a utility, you must declare a set of PL/SQL tables every time you want to call the DESCRIBE_PROCEDURE. You must then also interpret the results. By encapsulating all of this information and these data structures inside the package, you can take advantage of DBMS_DESCRIBE.DESCRIBE_PROCEDURE much more easily, and also interpret the results with greater accuracy and understanding. 10.2.3.1 Features of the psdesc package The psdesc package offers those features (PL/SQL Release 2.3 or later is needed to compile and use this package). Found in the psdesc.spp file, it contains the following elements: • A set of constants that give names to each of the different datatype values. These constants allow you to write code without having to remember specific hard−coded values. Here are a few lines from that code: c_varchar2 CONSTANT PLS_INTEGER := 1; c_number CONSTANT PLS_INTEGER := 2; c_object_type CONSTANT PLS_INTEGER := 121; • A PL/SQL table containing names to go along with those datatype constants (numbers). The psdesc.showargs program uses this table to display more descriptive information about the argument (for example, more than simply saying that it is type 121). • A set of constants that give names to the values for the different parameter modes. These are defined as follows: c_in CONSTANT PLS_INTEGER := 0; c_out CONSTANT PLS_INTEGER := 1; c_inout CONSTANT PLS_INTEGER := 2; • A user−defined record type that parallels the set of PL/SQL tables populated by the DESCRIBE_PROCEDURE procedure. This record type is defined as follows: TYPE arglist_rt IS RECORD ( overload NUMBER, position NUMBER ,level NUMBER ,argument_name VARCHAR2 (30) ,datatype NUMBER [Appendix A] What's on the Companion Disk? 10.2.3 DBMS_DESCRIBE Example 499 ,default_value NUMBER ,in_out NUMBER ,length NUMBER ,precision NUMBER ,scale NUMBER ,radix NUMBER); This record type is the RETURN value for the psdesc.arg function. • A procedure that acts as a wrapper around the DESCRIBE_PROCEDURE procedure. The psdesc.args procedure has a much simpler interface. PROCEDURE psdesc.args (obj IN VARCHAR2); When you call it, you don't need to provide a set of predeclared PL/SQL tables. Those arrays are already defined in the psdesc package specification. • A procedure that displays all of the argument information in a very readable format. You have seen the output (or part of it) in a number of earlier sections in this chapter. PROCEDURE psdesc.showargs (obj IN VARCHAR2 := NULL); Notice that this procedure has an optional object name; if you don't provide one, it will show you the arguments for whatever program was last processed in a call to psdesc.args. In other words, it will examine whatever is sitting in the individual arrays. • A procedure that returns information about a specified argument (by position in the arrays). FUNCTION psdesc.arg (pos IN INTEGER) RETURN arglist_rt; For reasons of space, I will not show the entire package specification and body. You can examine both of those in the psdesc.spp file. You will notice that I have placed all of the predefined PL/SQL tables in the package specification, even though the programs of psdesc offer a programmatic interface to those tables. I did that to make it easier to examine and manipulate the contents of the argument information. Just to give you a sense of how psdesc does its job, here is the implementation of psdesc.args (my "substitute" for the original DESCRIBE_PROCEDURE): /* Filename on companion disk: psdesc.spp */* PROCEDURE args (obj IN VARCHAR2) IS BEGIN g_object_name := obj; DBMS_DESCRIBE.DESCRIBE_PROCEDURE (obj, NULL, NULL, g_overload, g_position, g_level, g_argument_name, g_datatype, g_default_value, g_in_out, g_length, g_precision, g_scale, g_radix, g_spare); [Appendix A] What's on the Companion Disk? 10.2.3 DBMS_DESCRIBE Example 500 . therefore conflict with your own −20NNN error number usages (this is a very bad design decision on Oracle& apos;s part). If you embed calls to DESCRIBE_PROCEDURE inside your application or utility,. it. • DBMS_DESCRIBE.DESCRIBE_PROCEDURE will not show you the internal structure (attributes) of Oracle8 elements such as object types, variable arrays, and nested tables. 10.2.2 Explaining DBMS_DESCRIBE. PL/SQL, containing the core elements of the language). To do this, you must prefix the name of the built−in with its package name, as in: 'STANDARD.TO_CHAR' 10.2.2.2 The DESCRIBE level The