Collects column statistics for all columns and scalar attributes. The size is the maximum number of partitions in the histogram, with a default of 75 and a maximum of 254. FOR ALL INDEXED COLUMNS [SIZE N] Collects column statistics for all indexed columns in the table. The size is the maximum number of partitions in the histogram, with a default of 75 and a maximum of 254. FOR ALL INDEXES Collects statistics for all indexes associated with the table. 10.1.2.1.1 Example Here is an example of a request to this program to analyze all columns in my database: BEGIN DBMS_UTILITY.ANALYZE_DATABASE ( 'ESTIMATE', 100, 50, 'FOR ALL COLUMNS SIZE 200'); END; 10.1.2.2 The DBMS_UTILITY.ANALYZE_SCHEMA procedure This procedure analyzes all of the tables, clusters, and indexes in the specified schema. The header for the procedure follows: PROCEDURE DBMS_UTILITY.ANALYZE_SCHEMA (schema IN VARCHAR2 ,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. Parameters Description schema The name of the schema containing the object for which you wish to compute statistics. If NULL, then the current schema is used. This argument is case−sensitive. method Action to be taken by the program. ESTIMATE, DELETE, and COMPUTE are accepted values (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 [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 476 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] Collects column statistics for all columns and scalar attributes. The size is the maximum number of partitions in the histogram, with a default of 75 and a maximum of 254. FOR ALL INDEXED COLUMNS [SIZE N] Collects column statistics for all indexed columns in the table. The size is the maximum number of partitions in the histogram, with a default of 75 and a maximum of 254. FOR ALL INDEXES Collects statistics for all indexes associated with the table. 10.1.2.2.1 Example Here is an example of a request to this program to analyze all indexes in my current schema: BEGIN DBMS_UTILITY.ANALYZE_SCHEMA ( USER, 'ESTIMATE', 100, 50, 'FOR ALL INDEXES'); END; / 10.1.2.3 The DBMS_UTILITY.ANALYZE_PART_OBJECT procedure (Oracle8 Only) This procedure analyzes the specified, partitioned object. Here's the header for the procedure: PROCEDURE DBMS_UTILITY.ANALYZE_PART_OBJECT (schema IN VARCHAR2 DEFAULT NULL ,object_name IN VARCHAR2 DEFAULT NULL ,object_type IN CHAR DEFAULT 'T' ,command_type IN CHAR DEFAULT 'E' ,command_opt IN VARCHAR2 DEFAULT NULL ,sample_clause IN VARCHAR2 DEFAULT 'SAMPLE 5 PERCENT'); Parameters are summarized in the following table. Parameter Description schema The schema containing the specified object. object_name The name of the object to be analyzed. It must be partitioned. object_type The type of the object. Must be either T for TABLE or I for INDEX. command_type [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 477 A code indicating the type of analysis to perform. Valid values: C for COMPUTE STATISTICS, E for ESTIMATE STATISTICS, D for DELETE STATISTICS, and V for VALIDATE STRUCTURE. command_opt Options for the different command types. If command type is C or E, then command_opt can be any of the following: FOR TABLE, FOR ALL LOCAL INDEXES, FOR ALL COLUMNS, or a combination of some of the FOR options of the ANALYZE STATISTICS command. If command_type is V, then command_opt can be CASCADE if the object_type is T for TABLE. sample_clause Specifies the sample clause to use when command_type is E for ESTIMATE. Running this program is equivalent to executing this SQL command, ANALYZE TABLE|INDEX [<schema>.]<object_name> PARTITION <pname> [<command_type>] [<command_opt>] [<sample_clause>] for each partition of the specified object. DBMS_UTILITY will submit a job for each partition, so that the analysis can run in parallel using job queues. It is up to the user to control the number of concurrent jobs that will be started by setting correctly the initialization parameter JOB_QUEUE_PROCESSES. Any syntax errors encountered for the object specification will be reported in SNP trace files. 10.1.2.3.1 Example Here is an example of a request to this program to delete the statistics associated with the columns of the emp table: BEGIN DBMS_UTILITY.ANALYZE_PART_OBJECT ( USER, 'EMP', 'T', 'DELETE STATISTICS', 'FOR ALL COLUMNS'); END; / 10.1.2.4 The DBMS_UTILITY.COMMA_TO_TABLE procedure The COMMA_TO_TABLE procedure parses a comma−delimited list and places each name into a PL/SQL table. Here's the header for the procedure: PROCEDURE DBMS_UTILITY.COMMA_TO_TABLE (list IN VARCHAR2 ,tablen OUT BINARY_INTEGER ,tab OUT UNCL_ARRAY); Parameters are summarized in the following table. Parameter Description list Comma−delimited string tablen Number of names found in the list and placed in the PL/SQL table tab The PL/SQL table declared using one of the package's predeclared TABLE types This procedure uses the NAME_TOKENIZE procedure to determine which of the string's characters are names and which are commas. [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 478 10.1.2.4.1 Example COMMA_TO_TABLE is a handy utility if you happen to have a comma−delimited string; otherwise, it does you no good. Just think: with a tiny bit more effort, Oracle could have provided us with a much more general−purpose and useful string parsing engine. In any case, here is a sample use of DBMS_UTILITY.COMMA_TO_TABLE. It takes two different lists of correlated information, parses them into rows in two different tables, and then uses that data in a series of UPDATE statements. /* Filename on companion disk: upddelist.sp */* CREATE OR REPLACE PROCEDURE upd_from_list ( empno_list IN VARCHAR2, sal_list IN VARCHAR2) IS empnos DBMS_UTILITY.UNCL_ARRAY; sals DBMS_UTILITY.UNCL_ARRAY; numemps INTEGER; BEGIN DBMS_UTILITY.COMMA_TO_TABLE (empno_list, numemps, empnos); DBMS_UTILITY.COMMA_TO_TABLE (sal_list, numemps, sals); FOR rownum IN 1 numemps LOOP UPDATE emp SET sal = TO_NUMBER (sals(rownum)) WHERE empno = TO_NUMBER (empnos(rownum)); END LOOP; END; / NOTE: If you are running Oracle8, you could even rewrite this program to use array processing in DBMS_SQL and replace this loop with a single, dynamic UPDATE statement. See Chapter 2, Executing Dynamic SQL and PL/SQL, for more information. 10.1.2.5 The DBMS_UTILITY.COMPILE_SCHEMA procedure This procedure compiles all procedures, functions, and packages in the specified schema. The header for the procedure is, PROCEDURE DBMS_UTILITY.COMPILE_SCHEMA (schema VARCHAR2); where schema is the name of the schema. I have heard reports from developers that it sometimes seems as though they run this program and it does not do anything at all. As I write this, though, I have requested that DBMS_UTILITY recompile my PL/Vision schema, and the buzzing of the hard drive light, as well as the delay in the resurfacing of my SQL*Plus prompt, attests to the fact that it is indeed recompiling the scores of packages in this schema. 10.1.2.5.1 Example I execute the following command in SQL*Plus to recompile all programs in my current schema. Notice that before the recompilation, I had a single invalid package. Afterwards, all objects are valid. SQL> select object_name from user_objects where status='INVALID'; OBJECT_NAME −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− PLGTE SQL> exec DBMS_UTILITY.COMPILE_SCHEMA(user) PL/SQL procedure successfully completed. [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 479 SQL> select object_name from user_objects where status='INVALID'; no rows selected 10.1.2.6 The DBMS_UTILITY.DATA_BLOCK_ADDRESS_BLOCK function This function extracts and returns the block number of a data block address. The header for this function is, FUNCTION DBMS_UTILITY.DATA_BLOCK_ADDRESS_BLOCK (dba IN NUMBER) RETURN NUMBER; where dba is the data block address. 10.1.2.7 The DBMS_UTILITY.DATA_BLOCK_ADDRESS_FILE function This function extracts and returns the file number of a data block address. The header for this function is, FUNCTION DBMS_UTILITY.DATA_BLOCK_ADDRESS_FILE (dba IN NUMBER) RETURN NUMBER; where dba is the data block address. 10.1.2.8 The DBMS_UTILITY.DB_VERSION procedure This procedure (PL/SQL8 only) returns version information for the current database instance. Here's the header for this procedure: PROCEDURE DBMS_UTILITY.DB_VERSION (version OUT VARCHAR2 ,compatibility OUT VARCHAR2); Parameters are summarized in the following table. Parameter Description version A string that represents the internal software version of the database. The length of this string is variable and is determined by the database version. compatibility The compatibility setting of the database determined by the INIT.ORA parameter, COMPATIBLE. If the parameter is not specified in the INIT.ORA file, NULL is returned. 10.1.2.8.1 Example Before this function was available, you had to build a query against a V$ table in order to obtain this information. Now it is easy to obtain your database version from within PL/SQL. In fact, you can make it even easier to get this information by building a wrapper around DBMS_UTILITY.DB_VERSION, as shown here: /* Filename on companion disk: dbver.spp */* CREATE OR REPLACE PACKAGE db IS FUNCTION version RETURN VARCHAR2; FUNCTION compatibility RETURN VARCHAR2; END; / CREATE OR REPLACE PACKAGE BODY db IS v VARCHAR2(100); c VARCHAR2(100); PROCEDURE init_info IS [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 480 . 50, 'FOR ALL INDEXES'); END; / 10.1.2.3 The DBMS_UTILITY.ANALYZE_PART_OBJECT procedure (Oracle8 Only) This procedure analyzes the specified, partitioned object. Here's the header. comma−delimited string; otherwise, it does you no good. Just think: with a tiny bit more effort, Oracle could have provided us with a much more general−purpose and useful string parsing engine. In. (sals(rownum)) WHERE empno = TO_NUMBER (empnos(rownum)); END LOOP; END; / NOTE: If you are running Oracle8 , you could even rewrite this program to use array processing in DBMS_SQL and replace this