END; I save the object name you specify in a package variable. I then call DESCRIBE_PROCEDURE, dumping all of the retrieved information into the predeclared PL/SQL tables. To display all of the argument information for a program, you would call psdesc.showargs. Here is a simplified presentation of this procedure: PROCEDURE showargs (obj IN VARCHAR2 := NULL) IS v_onearg arglist_rt; BEGIN IF obj IS NOT NULL THEN args (obj); END IF; IF g_position.COUNT > 0 THEN display_header; FOR argrow IN g_position.FIRST g_position.LAST LOOP v_onearg := arg (argrow); display_argument_info (v_onearg); END LOOP; END IF; END; In other words, if the object name is specified, call psdesc.args to fill up the pre−defined arrays. Then, if there is anything in those arrays (g_position.COUNT is greater than 0), proceed from the first to the last argument and (a) call psdesc.arg to retrieve all the information for the Nth argument, and (b) display that information −− all the details of which are left to the psdesc.spp file. That was easy enough! Here are some other aspects of psdesc you might find interesting: • Use of the package initialization section to fill g_datatype_names and g_mode_names, which are lists of "translations" for the numeric codes. • The use of a local function, strval, defined inside psdesc.showargs, which consolidates otherwise redundant logic used to format output for display. • The check for a non−NULL g_object_name in the psdesc.arg function to make sure that you have used psdesc.args or psdesc.showargs to fill up the predefined PL/SQL tables. This is a sure−fire validation step, since the g_object_name variable is defined in the package body. It is private data and is only modified by a call to psdesc.arg. 10.2.3.2 Using psdesc.args as a quality assurance tool Rather than spend any more space on the implementation of psdesc, I will show you how you might put it to use. Suppose that you want to perform quality assurance checks on your code (what a concept, eh?). One rule that you have established for all your developers is that no function should have OUT or IN OUT parameters. The only way that data is to be returned from a function is through the RETURN clause. This guideline improves [Appendix A] What's on the Companion Disk? 10.2.3 DBMS_DESCRIBE Example 501 the reusability and maintainability of the function. It also makes that function a candidate for execution within SQL. How can you make sure that everyone is following this rule? Sure, you could run some queries against ALL_SOURCE, which contains all the source code, but what would you look for? "IN OUT" and "OUT" are good candidates, but only when they are inside the parameter lists of functions. Hmmm. That actually involves some parsing. What's a software manager interested in code quality to do? Let's see if DESCRIBE_PROCEDURE and the psdesc package can help. The following hasout function satisfies the request by obtaining all arguments with a call to psdesc.args and then scanning the PL/SQL table filled from DBMS_DESCRIBE.DESCRIBE_PROCEDURE for the offending parameter mode. This function returns TRUE if the program named by the string that I pass to it contains an OUT or IN OUT argument. /* Filename on companion disk: hasout.sf */* CREATE OR REPLACE FUNCTION hasout (obj IN VARCHAR2) RETURN BOOLEAN IS v_onearg psdesc.arglist_rt; v_argrow PLS_INTEGER; retval BOOLEAN := NULL; BEGIN psdesc.args (obj); v_argrow := psdesc.numargs; IF v_argrow = 0 THEN retval := NULL; ELSE retval := FALSE; LOOP v_onearg := psdesc.arg (v_argrow); IF v_onearg.argument_name IS NOT NULL THEN retval := v_onearg.in_out IN (psdesc.c_out, psdesc.c_inout); END IF; EXIT WHEN retval OR v_argrow = 1; v_argrow := v_argrow − 1; END LOOP; END IF; RETURN retval; END; / This function works as advertised, even for overloaded programs. Suppose, for example, that I run this function against the desctst.upd function (overloaded earlier in two versions). These functions do not contain an OUT or IN OUT parameter. I run the following script: /* Filename on companion disk: hasout.tst */* BEGIN /* I need to call hasout with an IF statement if I am going to use DBMS_OUTPUT.PUT_LINE to show the results; that built−in is very sadly not overloaded for Booleans */ IF hasout ('&1') THEN DBMS_OUTPUT.PUT_LINE ('&1 contains OUT or IN OUT argument(s).'); ELSE DBMS_OUTPUT.PUT_LINE ('&1 contains only IN argument(s).'); END IF; END; / [Appendix A] What's on the Companion Disk? 10.2.3 DBMS_DESCRIBE Example 502 Calling this function, I get the following results: SQL> @hasout.tst desctest.upd desctest.upd contains only IN argument(s). If I now add an additional overloading of the desctest.upd function as follows, CREATE OR REPLACE PACKAGE desctest IS FUNCTION upd (account_in NUMBER, person person%ROWTYPE, amounts number_table, trans_no NUMBER, maxsal OUT NUMBER) RETURN account.balance%TYPE; END; / I then get this result from running the hasout function: SQL> @hasout.tst desctest.upd desctest.upd contains OUT or IN OUT argument(s). And I bet you thought you wouldn't ever find any reason to use DESCRIBE_PROCEDURE! This handy little utility points the way to many other kinds of analyses you can perform on your code. Once you have the psdesc package in place, it becomes easy to construct these higher−level programs. Now all you have to do is come up with a way to feed your full list of functions (both standalone and packaged) into the hasout function for its quality check. This sounds easier than it actually is. Why? Because Oracle does not offer any utilities that provide you with the list of programs defined inside of a package. You cannot, in other words, do a describe on a package and see the list of elements defined in that package's specification. I hope that this is a shortcoming Oracle will correct, both through the provision of an API (perhaps by adding another procedure to the DBMS_DESCRIBE package) and the extension of the DESCRIBE command in SQL*Plus. In the meantime, though, you have some options. You can get all of the stand−alone functions from ALL_OBJECTS, and that will be a start. Furthermore, if you are using PL/Vision from RevealNet (see the Preface, "About PL/Vision"), you can use the PLVcat utility to catalog your package specifications. This process will extract the names of all procedures and functions and deposit them in the plvctlg table. If that is not available, you will have to come up with a list by performing a code review on all your packages. Then put those function names (with their package names prefixed) into a database table or file. Once you have that, you can easily construct a script to read those names and pass them to hasout. 10.1 DBMS_UTILITY: Performing Miscellaneous Operations 10.3 DBMS_DDL: Compiling and Analyzing Objects Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 10.2.3 DBMS_DESCRIBE Example 503 Chapter 10 Miscellaneous Packages 10.3 DBMS_DDL: Compiling and Analyzing Objects The DBMS_DDL package provides access from within PL/SQL to two DDL (Data Definition Language) statements. It also offers special administrative services that are not available through DDL syntax (Oracle8 only). 10.3.1 Getting Started with DBMS_DDL This DBMS_DDL package is created when the Oracle database is installed. The dbmsdesc.sql script (found in the built−in packages source code directory, as described in Chapter 1) contains the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS.DDL for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. DBMS_DDL programs "run as user," which means that they execute with the privileges of the user who calls that program. NOTE: All programs in DBMS_DDL first commit the current transaction, then perform the specified operation. When the operation is completed, another commit is performed. 10.3.1.1 DBMS_DDL programs Table 10−3 shows the programs defined in DBMS_DDL. Table 10.3: DBMS_DDL Programs Name Description Use in SQL ALTER_COMPILE Compiles the specified PL/SQL object. No ANALYZE_OBJECT Computes statistics for the specified database object. No REFERENCEABLE Makes the specified table referenceable for object identifiers (OIDs) in existing data structures. Available in Oracle8 only. No ALTER_TABLE_NOT_REFERENCEABLE Undoes the action of the previous procedure, ALTER_TABLE_REFERENCEABLE. Available in Oracle8 only. No DBMS_DDL does not define any exceptions or nonprogram elements. 504 10.3.2 Compiling PL/SQL Objects You can recompile PL/SQL objects that are already stored in the database by calling the ALTER_COMPILE procedure. 10.3.2.1 The DBMS_DDL.ALTER_COMPILE procedure Here's the header for this procedure: PROCEDURE DBMS_DDL.ALTER_COMPILE (type IN VARCHAR2 ,schema IN VARCHAR2 ,name IN VARCHAR2); Here are the possible values you can provide for the type parameter (enclosed in single quotes when you pass them to the procedure) and the actions that result: Type Action PROCEDURE Recompiles the specified procedure FUNCTION Recompiles the specified function PACKAGE Recompiles the specified package specification and body PACKAGE BODY Recompiles the specified package body PACKAGE SPECIFICATION Recompiles the specified package specification The schema and name arguments are case−sensitive. In almost every instance, the names of your PL/SQL objects are stored in uppercase (you must enclose those names in double quotes when creating the objects if you want mixed case). You will therefore need to specify the names in uppercase when you call ALTER_COMPILE. Note the following about using this package: • If you pass NULL for the schema, then the current schema (the same value returned by a call to the built−in function USER) will be used. • If you try to recompile DBMS_DDL, STANDARD, or DBMS_STANDARD (assuming that you have the privileges to do so), this procedure will return without taking any action. • When you request recompilation of a program, Oracle will first recompile any objects upon which that program depends, and which are marked invalid. In order to compile a program, you must own that program (in other words, the schema you specify is the owner of the program for which you request compilation) or your schema must have been granted the ALTER ANY PROCEDURE privilege to compile another schema's programs. The following command from a DBA account in SQL*Plus enables the SCOTT account to compile the programs of other schemas: SQL> GRANT ALTER ANY PROCEDURE TO SCOTT; Here are a few examples of usage, assuming that SCOTT has been granted the ALTER ANY PROCEDURE privilege: 1. [Appendix A] What's on the Companion Disk? 10.3.2 Compiling PL/SQL Objects 505 . through DDL syntax (Oracle8 only). 10.3.1 Getting Started with DBMS_DDL This DBMS_DDL package is created when the Oracle database is installed. The dbmsdesc.sql script (found in the built−in packages. data structures. Available in Oracle8 only. No ALTER_TABLE_NOT_REFERENCEABLE Undoes the action of the previous procedure, ALTER_TABLE_REFERENCEABLE. Available in Oracle8 only. No DBMS_DDL does. list of elements defined in that package's specification. I hope that this is a shortcoming Oracle will correct, both through the provision of an API (perhaps by adding another procedure to