A final note about the procedure name "xon": I wanted to use the procedure name "on," but ran afoul of the PL/SQL compiler since ON is a reserved word in SQL and PL/SQL. 11.1 DBMS_SESSION: Managing Session Information 12. Managing Server Resources Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 11.2.2 DBMS_SYSTEM Interface 546 Chapter 12 547 12. Managing Server Resources Contents: DBMS_SPACE: Obtaining Space Information DBMS_SHARED_POOL: Pinning Objects Through built−in packages, Oracle is now exposing more information about database internals −− information that is not directly visible in the catalog. This chapter describes two packages that expose useful information. DBMS_SPACE Gives DBAs an analysis of the amount of space both used and free within a table, index, or cluster segment. It also provides information about segment free list sizes −− information of special interest to Oracle Parallel Server administrators. DBMS_SHARED_POOL On the memory side, gives DBAs some measure of control over the Oracle System Global Area's (SGA's) shared pool. By pinning large packages into the shared pool, expensive runtime memory management (and even errors) can be avoided. 12.1 DBMS_SPACE: Obtaining Space Information The DBMS_SPACE package provides procedures for obtaining space utilization information about table, index, and cluster segments. This information is not directly available through the Oracle data dictionary views. It can be used to report on and track segment space consumption in an Oracle database more accurately than by monitoring extent allocation alone. By measuring segment growth rates over time, DBAs can better predict the need for additional space in the database. 12.1.1 Getting Started with DBMS_SPACE The DBMS_SPACE 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_SPACE for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. Table Table 12.1 lists the programs in the DBMS_SPACE package. Table 12.1: DBMS_SPACE Programs Name Description Use in SQL? FREE_BLOCKS Returns information on free blocks for a segment No UNUSED_SPACE Returns unused space information for a segment No The DBMS_SPACE package does not declare any exceptions or nonprogram elements. 12. Managing Server Resources 548 12.1.2 The DBMS_SPACE Interface This section describes the programs defined in DBMS_SPACE. 12.1.2.1 The DBMS_SPACE.FREE_BLOCKS procedure The FREE_BLOCKS procedure returns information about the number of blocks on Oracle's freelist groups for a table, index, or cluster segment. Specifications for Oracle7 and Oracle8 vary as follows. Here is the Oracle 7.x specification: PROCEDURE DBMS_SPACE.FREE_BLOCKS (segment_owner IN VARCHAR2 ,segment_name IN VARCHAR2 ,segment_type IN VARCHAR2 ,freelist_group_id IN NUMBER ,free_blks OUT NUMBER ,scan_limit IN NUMBER DEFAULT NULL); Here is the Oracle 8.0 specification: PROCEDURE DBMS_SPACE.FREE_BLOCKS (segment_owner IN VARCHAR2 ,segment_name IN VARCHAR2 ,segment_type IN VARCHAR2 ,freelist_group_id IN NUMBER ,free_blks OUT NUMBER ,scan_limit IN NUMBER DEFAULT NULL ,partition_name IN VARCHAR2 DEFAULT NULL); Parameters are summarized in the following table. Parameter Description segment_owner Schema of segment segment_name Name of segment segment_type Type of segment freelist_group_id Freelist group to compute free_blks Number of blocks on freelist scan_limit Maximum blocks to read partition_name Name of partition (8.0 only) 12.1.2.1.1 Exceptions The FREE_BLOCKS procedure does not raise any package exceptions. FREE_BLOCKS will raise the following Oracle exception if invalid segment data is passed in or if the executing user does not have privileges to use the procedure on the segment: ORA−00942 Table or view does not exist. 12.1.2.1.2 Restrictions Note the following restrictions on using FREE_BLOCKS: • [Appendix A] What's on the Companion Disk? 12.1.2 The DBMS_SPACE Interface 549 The user must have the ANALYZE ANY system privilege to use DBMS_SPACE.FREE_BLOCKS on segments from schemas other than the current session schema. • The program does not assert a purity level with the RESTRICT_REFERENCES pragma. 12.1.2.1.3 Example The following code block is a simple SQL*Plus report on the size of freelist number 0 for all tables in the current session schema: /* Filename on companion disk: spcex1.sql */* DECLARE free_blocks NUMBER; BEGIN DBMS_OUTPUT.PUT_LINE(RPAD('TABLE NAME',30)||' FREELIST BLOCKS'); FOR user_tables_rec IN (SELECT table_name FROM user_tables) LOOP DBMS_SPACE.FREE_BLOCKS (segment_owner => USER ,segment_name => user_tables_rec.table_name ,segment_type => 'TABLE' ,freelist_group_id => 0 ,free_blks => free_blocks ,scan_limit => NULL); DBMS_OUTPUT.PUT_LINE(RPAD(user_tables_rec.table_name,30)||' '|| TO_CHAR(free_blocks)); END LOOP; END; / This is a sample of the report output: TABLE NAME FREELIST BLOCKS Q$BGP_CONFIG 1 Q$BGP_DEBUG 1 Q$DICACHE_DETL 2 Q$INSTAT_DETL 1 Q$INSTAT_LOG 159 Q$IOWAITS_DETL 1 Q$LATCHSTAT_DETL 2 Q$LIBCACHE_DETL 1 Q$MTSDISP_DETL 1 Q$MTSSERV_DETL 1 Q$PLAN_TABLE 1 Q$SEG 3 Q$SEGFAIL_DETL 1 Q$SEGWATCH 1 Q$SESSIONWAIT_DETL 1 Blocks are added to free lists when the percentage of free space in the block is less that the PCTUSE setting for the segment. These blocks are below the segment highwater mark, and thus are not included in the unused blocks reported by DBMS_SPACE.UNUSED_SPACE. Freelist groups are used to reduce contention in Oracle Parallel Server installations by helping to partition data among the instances. Most DBAs will thus have less use for the FREE_BLOCKS procedure than for the UNUSED_SPACE procedure. [Appendix A] What's on the Companion Disk? 12.1.2 The DBMS_SPACE Interface 550 . about the number of blocks on Oracle& apos;s freelist groups for a table, index, or cluster segment. Specifications for Oracle7 and Oracle8 vary as follows. Here is the Oracle 7.x specification: PROCEDURE. information of special interest to Oracle Parallel Server administrators. DBMS_SHARED_POOL On the memory side, gives DBAs some measure of control over the Oracle System Global Area's (SGA's). information is not directly available through the Oracle data dictionary views. It can be used to report on and track segment space consumption in an Oracle database more accurately than by monitoring