Chapter 10 471 10. Miscellaneous Packages Contents: 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 Name Description Use in SQL ANALYZE_DATABASE No 10. Miscellaneous Packages 472 Analyzes all the tables, clusters, and indexes in a database ANALYZE_PART_OBJECT Runs the equivalent of the SQL ANALYZE TABLE or ANALYZE INDEX command for each partition of the object, using parallel job queues (PL/SQL8 only) No ANALYZE_SCHEMA Analyzes all the tables, clusters, and indexes in the specified schema No COMMA_TO_TABLE Parses a comma−delimited list into a PL/SQL table (PL/SQL Release 2.1 and later) No COMPILE_SCHEMA Compiles all procedures, 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 DB_VERSION Returns the database version and compatibility information for the current instance (PL/SQL8 only) No EXEC_DDL_STATEMENT Executes the provided DDL statement (PL/SQL8 only) No FORMAT_CALL_STACK Returns the current module call stack in a formatted display No FORMAT_ERROR_STACK Returns the current error stack in a formatted display No GET_HASH_VALUE Returns a hash value for a string; used to obtain unique (it is hoped) integer values for strings No GET_PARAMETER_VALUE Retrieves information about a parameter in the database parameter file, otherwise known as the INIT.ORA file (PL/SQL8 only) Yes GET_TIME Returns the elapsed time since an arbitrary time in 100ths of seconds No IS_PARALLEL_SERVER Returns TRUE if the database 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 NAME_RESOLVE Resolves the name of an object into its component parts No [Appendix A] What's on the Companion Disk? 10. Miscellaneous Packages 473 NAME_TOKENIZE Returns the individual components or tokens in a string No PORT_STRING Returns a string describing the platform and version of the current database Yes TABLE_TO_COMMA Moves the names in a PL/SQL 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 [Appendix A] What's on the Companion Disk? 10.1.1 Getting Started with DBMS_UTILITY 474 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? 10.1.2 The DBMS_UTILITY Interface 475 . 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. 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. 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