Oracle Built−in Packages- P103 docx

This is a sure−fire validation step, since the g_object_name variable is defined in the package body.. /* Filename on companion disk: hasout.sf */* CREATE OR REPLACE FUNCTION hasout obj

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?

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;

/

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.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

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:

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?