Oracle Built−in Packages- P97 pdf

10.1 DBMS_UTILITY: Performing Miscellaneous Operations The DBMS_UTILITY package is the "miscellaneous package" for PL/SQL.. It contains programs that perform a wide variety of operations

Chapter 10

471

DBMS_UTILITY: Performing Miscellaneous Operations

DBMS_DESCRIBE: Describing PL/SQL Program Headers

DBMS_DDL: Compiling and Analyzing Objects

DBMS_RANDOM: Generating Random Numbers (Oracle8 Only)

You can't find a neat category for everything, can you? This chapter brings together a variety of useful

packages you are sure to dip into on a regular basis:

DBMS_UTILITY

The actual "miscellaneous" package It offers programs to free unused user memory, parse

comma−delimited lists, calculate the elapsed time of PL/SQL programs, and much more You never know what you'll find popping up next in DBMS_UTILITY!

DBMS_DESCRIBE

Contains a single procedure, DESCRIBE_PROCEDURE, which you can use to get information about the parameters of a stored program

DBMS_DDL

Contains programs to recompile stored code, analyze objects in your schema, and modify the

referenceability of object identifiers in Oracle8

DBMS_RANDOM

New to Oracle8, supplies PL/SQL developers with a random number generator

10.1 DBMS_UTILITY: Performing Miscellaneous Operations

The DBMS_UTILITY package is the "miscellaneous package" for PL/SQL It contains programs that perform

a wide variety of operations (listed in Table 10.1)

TIP: I recommend that whenever you install a new version of the Oracle database, you scan

the contents of the dbmsutil.sql file Check to see if Oracle has added any new programs or

changed the functionality of existing programs

10.1.1 Getting Started with DBMS_UTILITY

The DBMS_UTILITY package is created when the Oracle database is installed The dbmsutil.sql script (found

in the built−in packages source code directory, as described in Chapter 1, Introduction) 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_UTILITY for the package and grants EXECUTE privilege on the package to public All Oracle users can reference and make use of this package Table 10.1 summarizes the programs available with DBMS_UTILITY

Table 10.1: DBMS_UTILITY Programs

Analyzes all the tables, clusters, and indexes in a database

ANALYZE TABLE or ANALYZE INDEX command for each partition of the object, using parallel job queues (PL/SQL8 only)

No

and indexes in the specified schema

No

a PL/SQL table (PL/SQL Release 2.1 and later)

No

functions, and packages in the specified schema

No

DATA_BLOCK_ADDRESS_BLOCK Gets the block number part of a

data block address

Yes

DATA_BLOCK_ADDRESS_FILE Gets the file number part of a data

block address

Yes

compatibility information for the current instance (PL/SQL8 only)

No

statement (PL/SQL8 only)

No

stack in a formatted display

No

FORMAT_ERROR_STACK Returns the current error stack in a

formatted display

No

used to obtain unique (it is hoped) integer values for strings

No

parameter in the database parameter file, otherwise known as the INIT.ORA file (PL/SQL8 only)

Yes

arbitrary time in 100ths of seconds

No

instance was started in parallel server mode

No

MAKE_DATA_BLOCK_ADDRESS Creates a data block address given

a file number and a block number

Yes

into its component parts

No

[Appendix A] What's on the Companion Disk?

NAME_TOKENIZE Returns the individual components

or tokens in a string

No

platform and version of the current database

Yes

table into a comma−delimited list

No

10.1.1.1 DBMS_UTILITY nonprogram elements

In addition to the functions and procedures defined in the package, DBMS_UTILITY also declares five PL/SQL tables that are used either as input into or output from the package's built−in modules By the way,

these tables are also used by other built−in packages, such as DBMS_DEFER See Chapter 10 of Oracle PL/SQL Programming for more information about PL/SQL tables (also called index−by tables as of Oracle8) DBMS_UTILITY.UNCL_ARRAY

This PL/SQL table type is used to store lists of strings in the format:

"USER"."NAME."COLUMN"@LINK You can use the array to store any strings you want up to the length determined in the following TABLE type statement:

TYPE DBMS_UTILITY.UNCL_ARRAY IS TABLE OF VARCHAR2(227) INDEX BY BINARY_INTEGER;

DBMS_UTILITY.NAME_ARRAY

This PL/SQL table type is used to store names of identifiers and is defined as follows:

TYPE DBMS_UTILITY.NAME_ARRAY IS TABLE OF VARCHAR2(30) INDEX BY BINARY_INTEGER;

DBMS_UTILITY.DBLINK_ARRAY

This PL/SQL table type is used to store database links and is defined as follows:

TYPE DBMS_UTILITY.DBLINK_ARRAY IS TABLE OF VARCHAR2(128) INDEX BY BINARY_INTEGER;

DBMS_UTILITY.INDEX_TABLE_TYPE

This PL/SQL table type is declared within the package, but is not otherwise used It is made available for use by other packages and programs

TYPE DBMS_UTILITY.INDEX_TABLE_TYPE IS TABLE OF BINARY_INTEGER INDEX BY BINARY_INTEGER;

DBMS_UTILITY.NUMBER_ARRAY

This PL/SQL table type is declared within the package, but is not otherwise used It is made available for use by other packages and programs

TYPE DBMS_UTILITY.NUMBER_ARRAY IS TABLE OF NUMBER INDEX BY BINARY_INTEGER;

You can declare PL/SQL tables based on these TABLE type statements as shown below:

DECLARE

short_name_list DBMS_UTILITY.NAME_ARRAY;

long_name_list DBMS_UTILITY.INDEX_TABLE_TYPE;

BEGIN

Of course, if you do declare PL/SQL tables based on DBMS_UTILITY data structures, then those

declarations will change with any changes in the package

10.1.2 The DBMS_UTILITY Interface

This section describes each of the programs in the DBMS_UTILITY package; because of the miscellaneous nature of these programs, they are simply listed in alphabetical order

10.1.2.1 The DBMS_UTILITY.ANALYZE_DATABASE procedure

This procedure analyzes all the tables, clusters, and indexes in the entire database The header for the

procedure follows:

PROCEDURE DBMS_UTILITY.ANALYZE_DATABASE

(method IN VARCHAR2

,estimate_rows IN NUMBER DEFAULT NULL

,estimate_percent IN NUMBER DEFAULT NULL

,method_opt IN VARCHAR2 DEFAULT NULL);

Parameters are summarized in this table

Parameter Description

method Action to be taken by the program ESTIMATE, DELETE, and COMPUTE are accepted

values and are explained later

estimate_rows The number of rows to be used to perform the statistics estimate Cannot be less than 1

Used only if method is ESTIMATE

estimate_percent The percentage of rows to be used to perform the statistics estimate Ignored if

estimate_rows is non−NULL Must be between 1 and 99 Used only if method is ESTIMATE

method_opt The method option, indicating which elements of the object will be analyzed

Here are the valid entries for the method argument, and the resulting activity (when you pass one of these values, they must be enclosed in single quotes):

COMPUTE

Exact statistics are computed based on the entire contents of the objects These values are then placed

in the data dictionary

ESTIMATE

Statistics are estimated With this option, either estimate_rows or estimate_percent must be

non−NULL These values are then placed in the data dictionary

DELETE

The statistics for this object are deleted from the data dictionary

Here are the valid method_opt entries and the resulting impact (when you pass one of these values, they must

be enclosed in single quotes):

FOR TABLE

Collects statistics for the table

FOR ALL COLUMNS [SIZE N]

[Appendix A] What's on the Companion Disk?