Oracle Built−in Packages- P116 doc

Any other character Cursor specified by address and hash value 12.2.2.2.1 Exceptions The UNKEEP procedure does not raise any package exceptions. It can raise the following Oracle exceptions if the name parameter does not resolve to a real object or an object of the proper type: ORA−06564 Object <object name> does not exist. ORA−06502 PL/SQL: numeric or value error. 12.2.2.2.2 Restrictions Note the following restrictions on calling UNKEEP: • Oracle warns that the UNKEEP procedure may not be supported in future releases. • The program does not assert a purity level with the RESTRICT_REFERENCES pragma. 12.2.2.2.3 Example This example releases the object pinned by the KEEP procedure (see the example for KEEP earlier): SQL> BEGIN 2 SYS.DBMS_SHARED_POOL.UNKEEP('SYS.STANDARD','P'); 3 END; 4 / PL/SQL procedure successfully completed. Usually an object is pinned into the shared pool for a reason, so it is not likely that you would need to call UNKEEP regularly. However, if large objects that have been pinned into the shared pool are definitely no longer needed, then memory can be made available to the shared pool by executing UNKEEP on these objects. 12.2.3 Monitoring and Modifying Shared Pool Behavior You can monitor the behavior of objects in the shared pool with the SIZES procedure. You can modify that behavior with the ABORTED_REQUEST_THRESHOLD procedure. 12.2.3.1 The DBMS_SHARED_POOL.SIZES procedure The SIZES procedure displays objects (including cursors and anonymous PL/SQL blocks) that are currently in the shared pool and that exceed the size (in kilobytes) specified by the minsize parameter. The program header follows: PROCEDURE DBMS_SHARED_POOL.SIZES (minsize IN NUMBER); The minsize parameter specifies the minimum size in kilobytes of shared pool objects that are displayed. The program does not raise any package exceptions, nor does it assert a purity level with the RESTRICT_REFERENCES pragma. [Appendix A] What's on the Companion Disk? 12.2.2 Pinning and Unpinning Objects 566 12.2.3.1.1 Example The following example demonstrates using the SIZES procedure in a SQL*Plus session to find all objects currently in the Oracle shared pool using more than 70 kilobytes of memory: SQL> set serveroutput on size 100000 SQL> execute SYS.DBMS_SHARED_POOL.SIZES(70); SIZE(K) KEPT NAME −−−−−− −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− −−−−−−−−−− 119 SYS.STANDARD (PACKAGE) 87 YES QDBA.Q$INSTAT (PACKAGE BODY) 80 YES QDBA.Q$BGPROC (PACKAGE BODY) 77 YES QDBA.Q$CVAR (PACKAGE) 72 begin :r:="LOADX"."RAND1";end; (0D953BE8,3990841093) (CURSOR) PL/SQL procedure successfully completed. Notice that a cursor object's name is composed of the address and hash value for the cursor. These are the values to use in calls to DBMS_SHARED_POOL.KEEP for pinning cursor objects. See the Section 12.2.4" section for an example of pinning a cursor. The SIZES procedure is normally used from the SQL*Plus, SQLDBA, or Sever Manager utilities. In order to display the results, issue the SET SERVEROUTPUT ON SIZE NNNNNN command prior to calling this program, as shown in the example. 12.2.3.2 The DBMS_SHARED_POOL.ABORTED_REQUEST_THRESHOLD procedure The ABORTED_REQUEST_THRESHOLD procedure allows the DBA to set a size threshold for restricting Oracle from dynamically flushing unpinned shared pool objects in order to make room for a large object greater than this size. When the threshold is set, any objects larger than the threshold for which sufficient free memory does not exist in the shared pool will fail to load with an ORA−4031 error (rather than flush other objects to make room). The program header follows: PROCEDURE DBMS_SHARED_POOL.ABORTED_REQUEST_THRESHOLD (threshold_size IN NUMBER); The threshold_size is a NUMBER, in bytes, that specifies the maximum size of objects that can be loaded if shared pool space is not available. 12.2.3.2.1 Exceptions The ABORTED_THRESHOLD_REQUEST procedure does not raise any package exceptions. It can raise the following Oracle exceptions if the threshold_size parameter is out of range: ORA−20000 threshold_size not in valid range: (5000 − 2147483647). 12.2.3.2.2 Restrictions Note the following restrictions on calling ABORTED_THRESHOLD_REQUEST: • The range of valid values for the threshold_size is 5000 to 2147483647, inclusive. • The program does not assert a purity level with the RESTRICT_REFERENCES pragma. [Appendix A] What's on the Companion Disk? 12.2.3 Monitoring and Modifying Shared Pool Behavior 567 12.2.3.2.3 Example The following shows how to keep objects larger than 50,000 bytes in size from flushing the shared pool when there is insufficient memory to load them: SQL> BEGIN 2 SYS.DBMS_SHARED_POOL.ABORTED_REQUEST_THRESHOLD(50000); 3 END; 4 / PL/SQL procedure successfully completed. ABORTED_REQUEST_THRESHOLD allows the DBA to control the negative impact of dynamically loading large objects into a fragmented or very active Oracle shared pool. Normally, these objects should be pinned into the shared pool using the KEEP procedure. By setting the aborted request threshold, the DBA can avoid performance degradation for all users in cases of extreme pressure on shared pool resources. However, this may result in some users receiving the ORA−4031 error. In these cases, the DBA should determine the source of the ORA−4031 errors and pin the appropriate objects into the shared pool using KEEP. 12.2.4 DBMS_SHARED_POOL Examples The DBMS_SHARED_POOL package is quite specialized and is intended for use by Oracle DBAs to help manage shared pool memory allocation problems. It would be unusual to see it used in applications, although a package−based application may try to pin itself into the shared pool using the KEEP procedure. One problem with the SIZES procedure is that it uses DBMS_OUTPUT to display its results. It is used primarily interactively from the SQL*Plus, SQLDBA, or Server Manager utilities. This is unfortunate, because the natural way to use these results programmatically would be as input to the KEEP procedure. Ambitious DBAs might explore using the UTL_FILE package to pass results from SIZES to KEEP. 12.2.4.1 Pinning packages automatically The best time to pin packages into the shared pool is immediately after the Oracle instance is first started and the database mounted. This is when shared pool memory is largely unallocated and has not become fragmented. It is a good DBA practice to call KEEP for any large packages as part of the database startup routine. Under UNIX, the Oracle−supplied script dbstart is often used to start databases. The DBA can customize this script to call KEEP and be sure the objects are pinned. One thing about database startup and shutdown scripts is that once they are working, you really do not want to modify them unless absolutely necessary. However, the need to pin new packages into the shared pool can come up at any time, and different databases may need to pin different sets of objects. In order to minimize maintenance of database startup scripts, I decided to write a simple procedure called object_keeper, which uses a table of object names and pins all objects in the table when called. Each database's startup script can call object_keeper once to pin all objects, eliminating script maintenance to add or delete objects from the list. The table also allows each database to maintain a separate list of objects to pin. The table that object_keeper uses is called keep_objects and is created as follows: //* Filename on companion disk: keeper.sql */* CREATE TABLE keep_objects ( obj_schema VARCHAR2(30) NOT NULL ,obj_name VARCHAR2(30) NOT NULL ,CONSTRAINT ko_PK PRIMARY KEY (obj_schema, obj_name) [Appendix A] What's on the Companion Disk? 12.2.3 Monitoring and Modifying Shared Pool Behavior 568 ) TABLESPACE USER_DATA STORAGE (INITIAL 2 NEXT 2 PCTINCREASE 0); The object_keeper procedure opens a cursor that joins keep_objects to DBA_OBJECTS and attempts to pin each of the objects in the cursor. Objects in keep_objects not found in DBA_OBJECTS will not be in the cursor, and thus will not attempt to be pinned. The call to DBMS_SHARED_POOL is contained in a BEGIN END sub−block to allow exception trapping and continuation to the next object in the cursor. //* Filename on companion disk: keeper.sql */* CREATE OR REPLACE PROCEDURE object_keeper /* || Procedure to pin objects into the shared pool || using DBMS_SHARED_POOL.KEEP procedure. All || objects found in the keep_objects table will || be KEEPed. || || For best results, procedure should be created || in the SYS schema. || || Author: John Beresniewicz, Savant Corp || Created: 09/18/97 || || Compilation Requirements: || || SELECT on SYS.DBA_OBJECTS || EXECUTE on SYS.DBMS_SHARED_POOL || || Execution Requirements: || || Some SYS objects may get ORA−1031 unless || the procedure is run by SYS || */ IS CURSOR keep_objects_cur IS SELECT DO.owner||'.'||DO.object_name object ,DECODE(DO.object_type ,'PACKAGE','P' ,'PROCEDURE','P' ,'FUNCTION','P' ,'TRIGGER','R' ,null ) type FROM keep_objects KO ,dba_objects DO WHERE UPPER(KO.obj_schema) = DO.owner AND UPPER(KO.obj_name) = DO.object_name AND DO.object_type IN ('PACKAGE','PROCEDURE','FUNCTION','TRIGGER'); BEGIN FOR ko_rec IN keep_objects_cur LOOP BEGIN SYS.DBMS_SHARED_POOL.KEEP (ko_rec.object, ko_rec.type); DBMS_OUTPUT.PUT_LINE ('KEPT: '||ko_rec.object); EXCEPTION WHEN OTHERS THEN DBMS_OUTPUT.PUT_LINE(SQLERRM); DBMS_OUTPUT.PUT_LINE [Appendix A] What's on the Companion Disk? 12.2.3 Monitoring and Modifying Shared Pool Behavior 569 ('KEEP FAIL: '||ko_rec.object||' '||ko_rec.type); END; END LOOP; END object_keeper; The object_keeper procedure uses DBMS_OUTPUT to display the results of the calls to KEEP. This is primarily for testing to make sure that all objects actually do get pinned. Use the SET SERVEROUTPUT ON SIZE nnnnnn command to enable the output display. The following shows the results in SQL*Plus of inserting several rows into keep_objects and executing the object_keeper procedure. This script is available on the disk in the keeptst.sql file. SQL> INSERT INTO keep_objects 2 VALUES ('SYS','STANDARD'); 1 row created. SQL> INSERT INTO keep_objects 2 VALUES ('SYS','DBMS_STANDARD'); 1 row created. SQL> INSERT INTO keep_objects 2 VALUES ('BOGUS','PACKAGE'); 1 row created. SQL> INSERT INTO keep_objects 2 VALUES ('SYS','DIUTIL'); 1 row created. SQL> INSERT INTO keep_objects 2 VALUES ('SYS','DBMS_SQL'); 1 row created. SQL> set serveroutput on size 100000 SQL> execute object_keeper; KEEPED: SYS.DBMS_SQL KEEPED: SYS.DBMS_STANDARD KEEPED: SYS.DIUTIL KEEPED: SYS.STANDARD PL/SQL procedure successfully completed. 12.2.4.2 Pinning cursors into the shared pool The DBMS_SHARED_POOL.KEEP procedure can be used to pin large cursors into the shared pool, as well as packages, procedures, and functions. In practice, it would be very unusual to need to do this. One reason might be in the case of a very large and complex view definition. Pinning the cursor associated with the view's SELECT statement into the shared pool may avoid memory management issues when users access the view. In order to pin a cursor, the DBMS_SHARED_POOL.SIZES procedure is used to identify the cursor's address and hash value. These values are then passed as the name parameter in the call to DBMS_SHARED_POOL.KEEP. Note that because the cursor address is not identifiable until after the cursor is already in the shared pool, it is impossible to pre−pin a cursor object prior to its first reference by a user. The following is output from a SQL*Plus session in which a cursor is identified using the SIZES procedure and is then pinned into the shared pool using KEEP: SQL> execute dbms_shared_pool.sizes(50); [Appendix A] What's on the Companion Disk? 12.2.4 DBMS_SHARED_POOL Examples 570 . Exceptions The UNKEEP procedure does not raise any package exceptions. It can raise the following Oracle exceptions if the name parameter does not resolve to a real object or an object of the proper. numeric or value error. 12.2.2.2.2 Restrictions Note the following restrictions on calling UNKEEP: • Oracle warns that the UNKEEP procedure may not be supported in future releases. • The program does. demonstrates using the SIZES procedure in a SQL*Plus session to find all objects currently in the Oracle shared pool using more than 70 kilobytes of memory: SQL> set serveroutput on size 100000 SQL>