Oracle® Database PL/SQL Packages and Types Reference 11g Release 1 (11.1) Part Number B28419-01 |
|
|
View PDF |
The DBMS_RESOURCE_MANAGER
package maintains plans, consumer groups, and plan directives. It also provides semantics so that you may group together changes to the plan schema.
See Also:
For more information on using the Database Resource Manager, see Oracle Database Administrator's Guide.This chapter contains the following topics:
Deprecated Subprograms
Security Model
Constants
Note:
Oracle recommends that you do not use deprecated procedures in new applications. Support for deprecated features is for backward compatibility only.The following subprograms are deprecated with Oracle Database 11g:
The invoker must have the ADMINISTER_RESOURCE_MANAGER
system privilege to execute these procedures. The procedures to grant and revoke this privilege are in the package Chapter 106, "DBMS_RESOURCE_MANAGER_PRIVS".
Table 105-1 DBMS_RESOURCE_MANAGER Constants
Constant | Definition |
---|---|
CLIENT_MACHINE |
CONSTANT VARCHAR2(30):= 'CLIENT_MACHINE'; |
CLIENT_OS_USER |
CONSTANT VARCHAR2(30):= 'CLIENT_OS_USER'; |
CLIENT_PROGRAM |
CONSTANT VARCHAR2(30):= 'CLIENT_PROGRAM'; |
MODULE_NAME |
CONSTANT VARCHAR2(30):= 'MODULE_NAME'; |
MODULE_NAME_ACTION |
CONSTANT VARCHAR2(30):= 'MODULE_NAME_ACTION'; |
ORACLE_USER |
CONSTANT VARCHAR2(30):= 'ORACLE_USER' |
SERVICE_MODULE |
CONSTANT VARCHAR2(30):= 'SERVICE_MODULE'; |
SERVICE_MODULE_ACTION |
CONSTANT VARCHAR2(30):= 'SERVICE_MODULE_ACTION'; |
SERVICE_NAME |
CONSTANT VARCHAR2(30):= 'SERVICE_NAME'; |
PERFORMANCE_CLASS |
CONSTANT VARCHAR2(30):= 'PERFORMANCE_CLASS'; |
Table 105-2 DBMS_RESOURCE_MANAGER Package Subprograms
Subprogram | Description |
---|---|
CALIBRATE_IO Procedure |
Calibrates the I/O capabilities of storage |
CLEAR_PENDING_AREA Procedure |
Clears the work area for the resource manager |
CREATE_CONSUMER_GROUP Procedure |
Creates entries which define resource consumer groups |
CREATE_PENDING_AREA Procedure |
Creates a work area for changes to resource manager objects |
CREATE_PLAN Procedure |
Creates entries which define resource plans |
CREATE_PLAN_DIRECTIVE Procedure |
Creates resource plan directives |
CREATE_SIMPLE_PLAN Procedure |
Creates a single-level resource plan containing up to eight consumer groups in one step |
DELETE_CONSUMER_GROUP Procedure |
Deletes entries which define resource consumer groups |
DELETE_PLAN Procedure |
Deletes the specified plan as well as all the plan directives it refers to |
DELETE_PLAN_CASCADE Procedure |
Deletes the specified plan as well as all its descendants (plan directives, subplans, consumer groups) |
DELETE_PLAN_DIRECTIVE Procedure |
Deletes resource plan directives |
SET_CONSUMER_GROUP_MAPPING Procedure |
Adds, deletes, or modifies pairs for the login and run-time attribute mappings |
SET_CONSUMER_GROUP_MAPPING_PRI Procedure |
Creates the session attribute mapping priority list |
SET_INITIAL_CONSUMER_GROUP Procedure |
Assigns the initial resource consumer group for a user (Caution: Deprecated Subprogram) |
SUBMIT_PENDING_AREA Procedure |
Submits pending changes for the resource manager |
SWITCH_CONSUMER_GROUP_FOR_SESS Procedure |
Changes the resource consumer group of a specific session |
SWITCH_CONSUMER_GROUP_FOR_USER Procedure |
Changes the resource consumer group for all sessions with a given user name |
SWITCH_PLAN Procedure |
Sets the current resource manager plan |
UPDATE_CONSUMER_GROUP Procedure |
Updates entries which define resource consumer groups |
UPDATE_PLAN Procedure |
Updates entries which define resource plans |
UPDATE_PLAN_DIRECTIVE Procedure |
Updates resource plan directives |
VALIDATE_PENDING_AREA Procedure |
Validates pending changes for the resource manage |
This procedure calibrates the I/O capabilities of storage. Calibration status is available from the V$IO_CALIBRATION_STATUS
view and results for a successful calibration run are located in DBA_RSRC_IO_CALIBRATE
table.
Syntax
DBMS_RESOURCE_MANAGER.CALIBRATE_IO ( num_physical_disks IN PLS_INTEGER DEFAULT 1, max_latency IN PLS_INTEGER DEFAULT 20, max_iops OUT PLS_INTEGER, max_mbps OUT PLS_INTEGER, actual_latency OUT PLS_INTEGER);
Parameters
Table 105-3 CALIBRATE_IO Procedure Parameters
Parameter | Description |
---|---|
num_physical_disks |
Approximate number of physical disks in the database storage |
max_latency |
Maximum tolerable latency in milliseconds for database-block-sized IO requests |
max_iops |
Maximum number of I/O requests per second that can be sustained. The I/O requests are randomly-distributed, database-block-sized reads. |
max_mbps |
Maximum throughput of I/O that can be sustained, expressed in megabytes per second. The I/O requests are randomly-distributed, 1 megabyte reads. |
actual_latency |
Average latency of database-block-sized I/O requests at max_iops rate, expressed in milliseconds |
Usage Notes
Only users with the SYSDBA privilege can run this procedure. Qualified users must also turn on timed_statistics
, and ensure asynch_io
is enabled for datafiles. This can be achieved by setting filesystemio_options
to either ASYNCH
or SETALL
. One can also query the asynch_io
status by means of the following SQL statement:
col name format a50 SELECT name, asynch_io FROM v$datafile f,v$iostat_file i WHERE f.file# = i.file_no AND filetype_name = 'Data File' /
Only one calibration can be run at a time. If another calibration is initiated at the same time, it will fail.
For an Oracle Real Application Clusters (RAC) database, the workload is simultaneously generated from all instances.
See Also:
Oracle Database Performance Tuning Guide for more information about calibrationExamples
Example of using I/O Calibration procedure
SET SERVEROUTPUT ON DECLARE lat INTEGER; iops INTEGER; mbps INTEGER; BEGIN -- DBMS_RESOURCE_MANAGER.CALIBRATE_IO (<DISKS>, <MAX_LATENCY>, iops, mbps, lat); DBMS_RESOURCE_MANAGER.CALIBRATE_IO (2, 10, iops, mbps, lat); DBMS_OUTPUT.PUT_LINE ('max_iops = ' || iops); DBMS_OUTPUT.PUT_LINE ('latency = ' || lat); dbms_output.put_line('max_mbps = ' || mbps); end; /
View for I/O calibration results
SQL> desc V$IO_CALIBRATION_STATUS Name Null? Type ----------------------------------------- -------- ---------------------------- STATUS VARCHAR2(13) CALIBRATION_TIME TIMESTAMP(3) SQL> desc gv$io_calibration_status Name Null? Type ----------------------------------------- -------- ---------------------------- INST_ID NUMBER STATUS VARCHAR2(13) CALIBRATION_TIME TIMESTAMP(3) Column explanation: ------------------- STATUS: IN PROGRESS : Calibration in Progress (Results from previous calibration run displayed, if available) READY : Results ready and available from earlier run NOT AVAILABLE : Calibration results not available. CALIBRATION_TIME: End time of the last calibration run
DBA table that stores I/O Calibration results
SQL> desc DBA_RSRC_IO_CALIBRATE Name Null? Type ----------------------------------------- -------- ---------------------------- START_TIME TIMESTAMP(6) END_TIME TIMESTAMP(6) MAX_IOPS NUMBER MAX_MBPS NUMBER MAX_PMBPS NUMBER LATENCY NUMBER NUM_PHYSICAL_DISKS NUMBER comment on table DBA_RSRC_IO_CALIBRATE is 'Results of the most recent I/O calibration' / comment on column DBA_RSRC_IO_CALIBRATE.START_TIME is 'start time of the most recent I/O calibration' / comment on column DBA_RSRC_IO_CALIBRATE.END_TIME is 'end time of the most recent I/O calibration' / comment on column DBA_RSRC_IO_CALIBRATE.MAX_IOPS is 'maximum number of data-block read requests that can be sustained per second' / comment on column DBA_RSRC_IO_CALIBRATE.MAX_MBPS is 'maximum megabytes per second of maximum-sized read requests that can be sustained' / comment on column DBA_RSRC_IO_CALIBRATE.MAX_PMBPS is 'maximum megabytes per second of large I/O requests that can be sustained by a single process' / comment on column DBA_RSRC_IO_CALIBRATE.LATENCY is 'latency for data-block read requests' / comment on column DBA_RSRC_IO_CALIBRATE.NUM_PHYSICAL_DISKS is 'number of physical disks in the storage subsystem (as specified by user)' /
This procedure clears pending changes for the resource manager.
Syntax
DBMS_RESOURCE_MANAGER.CLEAR_PENDING_AREA;
This procedure creates entries which define resource consumer groups.
Syntax
DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( consumer_group IN VARCHAR2, comment IN VARCHAR2, cpu_mth IN VARCHAR2 DEFAULT NULL, mgmt_mth IN VARCHAR2 DEFAULT 'ROUND-ROBIN');
Parameters
Table 105-4 CREATE_CONSUMER_GROUP Procedure Parameters
Parameter | Description |
---|---|
consumer_group |
The name of the consumer group. |
comment |
The user's comment. |
cpu_mth |
Name of CPU resource allocation method (deprecated) |
mgmt_mth |
Name of CPU resource allocation method |
This procedure makes changes to resource manager objects.
All changes to the plan schema must be done within a pending area. The pending area can be thought of as a "scratch" area for plan schema changes. The administrator creates this pending area, makes changes as necessary, possibly validates these changes, and only when the submit is completed do these changes become active.
Syntax
DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA;
Usage Notes
You may, at any time while the pending area is active, view the current plan schema with your changes by selecting from the appropriate user views.
At any time, you may clear the pending area if you want to stop the current changes. You may also call the VALIDATE
procedure to confirm whether the changes you has made are valid. You do not have to do your changes in a given order to maintain a consistent group of entries. These checks are also implicitly done when the pending area is submitted.
Note:
Oracle allows "orphan" consumer groups (in other words, consumer groups that have no plan directives that refer to them). This is in anticipation that an administrator may want to create a consumer group that is not currently being used, but will be used in the future.The following rules must be adhered to, and they are checked whenever the validate or submit procedures are executed:
No plan schema may contain any loops.
All plans and consumer groups referred to by plan directives must exist.
All plans must have plan directives that refer to either plans or consumer groups.
All percentages in any given level must not add up to greater than 100 for the emphasis resource allocation method.
No plan may be deleted that is currently being used as a top plan by an active instance.
For Oracle8i, the plan directive parameter, parallel_degree_limit_p1
, may only appear in plan directives that refer to consumer groups (that is, not at subplans).
There cannot be more than 32 plan directives coming from any given plan (that is, no plan can have more than 32 children).
There cannot be more than 32 consumer groups in any active plan schema.
Plans and consumer groups use the same namespace; therefore, no plan can have the same name as any consumer group.
There must be a plan directive for OTHER_GROUPS
somewhere in any active plan schema.This ensures that a session not covered by the currently active plan is allocated resources as specified by the OTHER_GROUPS
directive.
If any of the preceding rules are broken when checked by the VALIDATE
or SUBMIT
procedures, then an informative error message is returned. You may then make changes to fix the problem(s) and reissue the validate or submit procedures.
This procedure creates entries which define resource plans.
Syntax
DBMS_RESOURCE_MANAGER.CREATE_PLAN ( plan IN VARCHAR2, comment IN VARCHAR2, cpu_mth IN VARCHAR2 DEFAULT NULL, -- deprecated active_sess_pool_mth IN VARCHAR2 DEFAULT 'ACTIVE_SESS_POOL_ABSOLUTE', parallel_degree_limit_mth IN VARCHAR2 DEFAULT 'PARALLEL_DEGREE_LIMIT_ABSOLUTE', queueing_mth IN VARCHAR2 DEFAULT 'FIFO_TIMEOUT', mgmt_mth IN VARCHAR2 DEFAULT 'EMPHASIS');
Parameters
Table 105-5 CREATE_PLAN Procedure Parameters
Parameter | Description |
---|---|
plan |
The name of the resource plan. |
comment |
User's comment. |
cpu_mth |
Allocation method for CPU resources (deprecated) |
active_sess_pool_mth |
The Active session pool resource allocation method. Limits the number of active sessions. All other sessions are inactive and wait in a queue to be activated. ACTIVE_SESS_POOL_ABSOLUTE is the default and only method available. |
parallel_degree_limit_mth |
The resource allocation method for specifying a limit on the degree of parallelism of any operation. PARALLEL_DEGREE_LIMIT_ABSOLUTE is the default and only method available. |
queueing_mth |
The Queuing resource allocation method. Controls order in which queued inactive sessions will execute. FIFO_TIMEOUT is the default and only method available |
mgmt_mth |
The resource allocation method for specifying how much resources (e.g. CPU or I/O) each consumer group or sub-plan gets
|
Usage Notes
If you want to use any default resource allocation method, then you do not need not specify it when creating or updating a plan.
This procedure creates resource plan directives.
Syntax
DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( plan IN VARCHAR2, group_or_subplan IN VARCHAR2, comment IN VARCHAR2, cpu_p1 IN NUMBER DEFAULT NULL, -- deprecated cpu_p2 IN NUMBER DEFAULT NULL, -- deprecated cpu_p3 IN NUMBER DEFAULT NULL, -- deprecated cpu_p4 IN NUMBER DEFAULT NULL, -- deprecated cpu_p5 IN NUMBER DEFAULT NULL, -- deprecated cpu_p6 IN NUMBER DEFAULT NULL, -- deprecated cpu_p7 IN NUMBER DEFAULT NULL, -- deprecated cpu_p8 IN NUMBER DEFAULT NULL, -- deprecated active_sess_pool_p1 IN NUMBER DEFAULT NULL, queueing_p1 IN NUMBER DEFAULT NULL, parallel_degree_limit_p1 IN NUMBER DEFAULT NULL, switch_group IN VARCHAR2 DEFAULT NULL, switch_time IN NUMBER DEFAULT NULL, switch_estimate IN BOOLEAN DEFAULT FALSE, max_est_exec_time IN NUMBER DEFAULT NULL, undo_pool IN NUMBER DEFAULT NULL, max_idle_time IN NUMBER DEFAULT NULL, max_idle_blocker_time IN NUMBER DEFAULT NULL, switch_time_in_call IN NUMBER DEFAULT NULL, -- deprecated mgmt_p1 IN NUMBER DEFAULT NULL, mgmt_p2 IN NUMBER DEFAULT NULL, mgmt_p3 IN NUMBER DEFAULT NULL, mgmt_p4 IN NUMBER DEFAULT NULL, mgmt_p5 IN NUMBER DEFAULT NULL, mgmt_p6 IN NUMBER DEFAULT NULL, mgmt_p7 IN NUMBER DEFAULT NULL, mgmt_p8 IN NUMBER DEFAULT NULL, switch_io_megabytes IN NUMBER DEFAULT NULL, switch_io_reqs IN NUMBER DEFAULT NULL, switch_for_call IN BOOLEAN DEFAULT NULL);
Parameters
Table 105-6 CREATE_PLAN_DIRECTIVE Procedure Parameters
Parameter | Description |
---|---|
plan |
The name of the resource plan. |
group_or_subplan |
The name of the consumer group or subplan. |
comment |
Comment for the plan directive. |
cpu_p1 |
First parameter for the CPU resources allocation method (deprecated use mgmt_p1 instead) |
cpu_p2 |
Second parameter for the CPU resources allocation method (deprecated use mgmt_p2 instead) |
cpu_p3 |
Third parameter for the CPU resources allocation method (deprecated use mgmt_p3 instead) |
cpu_p4 |
Fourth parameter for the CPU resources allocation method (deprecated use mgmt_p4 instead) |
cpu_p5 |
Fifth parameter for the CPU resources allocation method (deprecated use mgmt_p5 instead) |
cpu_p6 |
Sixth parameter for the CPU resources allocation method (deprecated use mgmt_p6 instead) |
cpu_p7 |
Seventh parameter for the CPU resources allocation method (deprecated use mgmt_p7 instead) |
cpu_p8 |
Eighth parameter for the CPU resources allocation method (deprecated use mgmt_p8 instead) |
active_sess_pool_p1 |
Specifies maximum number of concurrently active sessions for a consumer group. Default is NULL , which means unlimited. |
queueing_p1 |
Specified time (in seconds) after which a job in the inactive session queue (waiting for execution) will time out. Default is NULL , which means unlimited. |
parallel_degree_limit_p1 |
Specifies a limit on the degree of parallelism for any operation. Default is NULL , which means unlimited. |
switch_group |
Specifies consumer group to switch to, once a switch condition is met. If the group name is 'CANCEL_SQL ', then the current call is canceled when the switch condition is met. If the group name is 'KILL_SESSION ', then the session is killed when the switch condition is met. Default is NULL . |
switch_time |
Specifies time (in seconds) that a session can execute before an action is taken. Default is NULL , which means unlimited. |
switch_estimate |
If TRUE , tells Oracle to use its execution time estimate to automatically switch the consumer group of an operation before beginning its execution. Default is FALSE . |
max_est_exec_time |
Specifies the maximum execution time (in seconds) allowed for a session. If the optimizer estimates that an operation will take longer than MAX_EST_EXEC_TIME , the operation is not started and ORA-07455 is issued. If the optimizer does not provide an estimate, this directive has no effect. Default is NULL , which means unlimited. |
undo_pool |
Sets a maximum in kilobytes (K ) on the total amount of undo generated by a consumer group. Default is NULL , which means unlimited. |
max_idle_time |
Indicates the maximum session idle time. Default is NULL , which means unlimited. |
max_idle_blocker_time |
The maximum amount of time in seconds that a session can be idle while blocking another session's acquisition of a resource. |
switch_time_in_call |
Deprecated. If this parameter is specified, switch_time will be effectively set to switch_time_in_call and switch_for_call will be effectively set to TRUE . |
mgmt_p1 |
Resource allocation value for level 1 (replaces cpu_p1 ):
|
mgmt_p2 |
Resource allocation value for level 2 (replaces cpu_p2 )
|
mgmt_p3 |
Resource allocation value for level 3 (replaces cpu_p3 )
|
mgmt_p4 |
Resource allocation value for level 4 (replaces cpu_p4 )
|
mgmt_p5 |
Resource allocation value for level 5 (replaces cpu_p5 )
|
mgmt_p6 |
Resource allocation value for level 6 (replaces cpu_p6 )
|
mgmt_p7 |
Resource allocation value for level 7 (replaces cpu_p7 )
|
mgmt_p8 |
Resource allocation value for level 8 (replaces cpu_p8 )
|
switch_io_megabytes |
Specifies the amount of I/O (in MB) that a session can issue before an action is taken. Default is NULL , which means unlimited. |
switch_io_reqs |
Specifies the number of I/O requests that a session can issue before an action is taken. Default is NULL , which means unlimited. |
switch_for_call |
Specifies that if an action is taken because of the switch_time , switch_io_megabytes , or switch_io_reqs parameters, the consumer group is restored to its original consumer group at the end of the top call. Default is FALSE , which means that the original consumer group is not restored at the end of the top call. |
Usage Notes
All parameters default to NULL
. However, for the EMPHASIS
CPU
resource allocation method, this case would starve all the users.
For max_idle_time
and max_idle_blocker_time
, PMON
will check these limits once a minute. If it finds a session that has exceeded one of the limits, it will forcibly kill the session and clean up all its state.
The parameter switch_time_in_call
is mostly useful for three-tier applications where the mid-tier server is implementing session pooling. By using switch_time_in_call
, the resource usage of one client will not affect a future client that happens to be executed on the same session.
This procedure creates a single-level resource plan containing up to eight consumer groups in one step. You do not need to create a pending area manually before creating a resource plan, or use the CREATE_CONSUMER_GROUP
and CREATE_RESOURCE_PLAN_DIRECTIVES
procedures separately.
Syntax
DBMS_RESOURCE_MANAGER.CREATE_SIMPLE_PLAN ( simple_plan IN VARCHAR2 DEFAULT NULL, consumer_group1 IN VARCHAR2 DEFAULT NULL, group1_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group2 IN VARCHAR2 DEFAULT NULL, group2_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group3 IN VARCHAR2 DEFAULT NULL, group3_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group4 IN VARCHAR2 DEFAULT NULL, group4_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group5 IN VARCHAR2 DEFAULT NULL, group5_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group6 IN VARCHAR2 DEFAULT NULL, group6_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group7 IN VARCHAR2 DEFAULT NULL, group7_cpu IN NUMBER DEFAULT NULL, -- deprecated consumer_group8 IN VARCHAR2 DEFAULT NULL, group8_cpu IN NUMBER DEFAULT NULL, -- deprecated group1_percent IN NUMBER DEFAULT NULL, group2_percent IN NUMBER DEFAULT NULL, group3_percent IN NUMBER DEFAULT NULL, group4_percent IN NUMBER DEFAULT NULL, group5_percent IN NUMBER DEFAULT NULL, group6_percent IN NUMBER DEFAULT NULL, group7_percent IN NUMBER DEFAULT NULL, group8_percent IN NUMBER DEFAULT NULL);
Parameters
Table 105-7 CREATE_SIMPLE_PLAN Procedure Parameters
Parameter | Description |
---|---|
simple_plan |
The name of the resource plan. |
consumer_group1 |
Name of the consumer group |
group1_cpu |
Percentage for group (deprecated) |
consumer_group2 |
Name of the consumer group |
group2_cpu |
Percentage for group (deprecated) |
consumer_group3 |
Name of the consumer group |
group3_cpu |
Percentage for group (deprecated) |
consumer_group4 |
Name of the consumer group |
group4_cpu |
Percentage for group (deprecated) |
consumer_group5 |
Name of the consumer group |
group5_cpu |
Percentage for group (deprecated) |
consumer_group6 |
Name of the consumer group |
group6_cpu |
Percentage for group (deprecated) |
consumer_group7 |
Name of the consumer group |
group7_cpu |
Percentage for group (deprecated) |
consumer_group8 |
Name of the consumer group |
group8_cpu |
Percentage for group (deprecated) |
group1_percent |
Percentage of resources allocated for this consumer group |
group2_percent |
Percentage of resources allocated for this consumer group |
group3_percent |
Percentage of resources allocated for this consumer group |
group4_percent |
Percentage of resources allocated for this consumer group |
group5_percent |
Percentage of resources allocated for this consumer group |
group6_percent |
Percentage of resources allocated for this consumer group |
group7_percent |
Percentage of resources allocated for this consumer group |
group8_percent |
Percentage of resources allocated for this consumer group |
This procedure delete entries which define resource consumer groups.
Syntax
DBMS_RESOURCE_MANAGER.DELETE_CONSUMER_GROUP ( consumer_group IN VARCHAR2);
Parameters
Table 105-8 DELETE_CONSUMER_GROUP Procedure Parameters
Parameters | Description |
---|---|
consumer_group |
The name of the consumer group to be deleted. |
This procedure deletes the specified plan as well as all the plan directives to which it refers.
Syntax
DBMS_RESOURCE_MANAGER.DELETE_PLAN ( plan IN VARCHAR2);
Parameters
Table 105-9 DELETE_PLAN Procedure Parameters
Parameter | Description |
---|---|
plan |
The name of the resource plan to delete. |
This procedure deletes the specified plan and all of its descendants (plan directives, subplans, consumer groups). Mandatory objects and directives are not deleted.
Syntax
DBMS_RESOURCE_MANAGER.DELETE_PLAN_CASCADE ( plan IN VARCHAR2);
Parameters
Table 105-10 DELETE_PLAN_CASCADE Procedure Parameters
Parameters | Description |
---|---|
plan |
The name of the plan. |
Usage Notes
If DELETE_PLAN_CASCADE
encounters any error, then it rolls back, and nothing is deleted.
This procedure deletes resource plan directives.
Syntax
DBMS_RESOURCE_MANAGER.DELETE_PLAN_DIRECTIVE ( plan IN VARCHAR2, group_or_subplan IN VARCHAR2);
Parameters
Table 105-11 DELETE_PLAN_DIRECTIVE Procedure Parameters
Parameter | Description |
---|---|
plan |
The name of the resource plan. |
group_or_subplan |
The name of the group or subplan. |
This procedure adds, deletes, or modifies entries that map sessions to consumer groups, based on the session's login and runtime attributes.
Syntax
DBMS_RESOURCE_MANAGER.SET_CONSUMER_GROUP_MAPPING( attribute IN VARCHAR2, value IN VARCHAR2, consumer_group IN VARCHAR2 DEFAULT NULL);
Parameters
Table 105-12 SET_CONSUMER_GROUP_MAPPING Procedure Parameters
Parameters | Description |
---|---|
attribute |
The mapping attribute to add/modify. It can be one of the Constants listed. |
value |
The attribute value to match. |
consumer_group |
The name of the mapped consumer group, or NULL to delete a mapping. |
Usage Notes
If no mapping exists for the given attribute and value, a mapping to the given consumer group will be created. If a mapping already exists for the given attribute and value, the mapped consumer group will be updated to the one given. If the consumer_group
argument is NULL
, then any mapping from the given attribute and value will be deleted.
Multiple attributes of a session can be used to map the session to a consumer group. This procedure prioritizes the attribute mappings.
Syntax
DBMS_RESOURCE_MANAGER.SET_CONSUMER_GROUP_MAPPING_PRI( explicit IN NUMBER, oracle_user IN NUMBER, service_name IN NUMBER, client_os_user IN NUMBER, client_program IN NUMBER, client_machine IN NUMBER, module_name IN NUMBER, module_name_action IN NUMBER, service_module IN NUMBER, service_module_action IN NUMBER);
Parameters
Table 105-13 SET_CONSUMER_GROUP_MAPPING_PRI Procedure Parameters
Parameters | Description |
---|---|
explicit |
The priority of the explicit mapping. |
oracle_user |
The priority of the Oracle user name mapping. |
service_name |
The priority of the client service name mapping. |
client_os_user |
The priority of the client operating system user name mapping. |
client_program |
The priority of the client program mapping. |
client_machine |
The priority of the client machine mapping. |
module_name |
The priority of the application module name mapping. |
module_name_action |
The priority of the application module name and action mapping. |
service_module |
The priority of the service name and application module name mapping. |
module_name_action |
The priority of the service name, application module name, and application action mapping. |
Usage Notes
This procedure requires that you include the pseudo-attribute explicit
as an argument. It must be set to 1. It indicates that explicit consumer group switches have the highest priority. You explicitly switch consumer groups with these package procedures:
DBMS_SESSION
.SWITCH_CURRENT_CONSUMER_GROUP
DBMS_RESOURCE_MANAGER
.SWITCH_CONSUMER_GROUP_FOR_SESS
DBMS_RESOURCE_MANAGER
.SWITCH_CONSUMER_GROUP_FOR_USER
Each priority value must be a unique integer from 1 to 10. Together, they establish an ordering where 1 is the highest priority and 10 is the lowest.
Note:
This procedure is deprecated in Release 11gR1. While the procedure remains available in the package, Initial Consumer Group is set by the session-to-consumer group mapping rules.The initial consumer group of a user is the consumer group to which any session created by that user initially belongs. This procedure sets the initial resource consumer group for a user.
Syntax
DBMS_RESOURCE_MANAGER.SET_INITIAL_CONSUMER_GROUP ( user IN VARCHAR2, consumer_group IN VARCHAR2);
Parameters
Table 105-14 SET_INITIAL_CONSUMER_GROUP Procedure Parameters
Parameters | Description |
---|---|
user |
The name of the user. |
consumer_group |
The user's initial consumer group. |
Usage Notes
The ADMINISTER_RESOURCE_MANAGER
or the ALTER
USER
system privilege are required to be able to execute this procedure. The user, or PUBLIC
, must be directly granted switch privilege to a consumer group before it can be set to be the user's initial consumer group. Switch privilege for the initial consumer group cannot come from a role granted to that user.
Note:
These semantics are similar to those forALTER
USER
DEFAULT
ROLE
.If the initial consumer group for a user has never been set, then the user's initial consumer group is automatically the consumer group: DEFAULT_CONSUMER_GROUP
.
DEFAULT_CONSUMER_GROUP
has switch privileges granted to PUBLIC
; therefore, all users are automatically granted switch privilege for this consumer group. Upon deletion of a consumer group, all users having the deleted group as their initial consumer group now have DEFAULT_CONSUMER_GROUP
as their initial consumer group. All currently active sessions belonging to a deleted consumer group are switched to DEFAULT_CONSUMER_GROUP
.
This procedure submits pending changes for the resource manager. It clears the pending area after validating and committing the changes (if valid).
Note:
A call toSUBMIT_PENDING_AREA
may fail even if VALIDATE_PENDING_AREA
succeeds. This may happen if a plan being deleted is loaded by an instance after a call to VALIDATE_PENDING_AREA
, but before a call to SUBMIT_PENDING_AREA
.Syntax
DBMS_RESOURCE_MANAGER.SUBMIT_PENDING_AREA;
This procedure changes the resource consumer group of a specific session. It also changes the consumer group of any (PQ) slave sessions that are related to the top user session.
Syntax
DBMS_RESOURCE_MANAGER.SWITCH_CONSUMER_GROUP_FOR_SESS ( session_id IN NUMBER, session_serial IN NUMBER, consumer_group IN VARCHAR2);
Parameters
Table 105-15 SWITCH_CONSUMER_GROUP_FOR_SESS Procedure Parameters
Parameter | Description |
---|---|
session_id |
SID column from the view V$SESSION . |
session_serial |
SERIAL# column from view V$SESSION . |
consumer_group |
The name of the consumer group to switch to. |
This procedure changes the resource consumer group for all sessions with a given user ID. It also change the consumer group of any (PQ) slave sessions that are related to the top user session.
Syntax
DBMS_RESOURCE_MANAGER.SWITCH_CONSUMER_GROUP_FOR_USER ( user IN VARCHAR2, consumer_group IN VARCHAR2);
Parameters
Table 105-16 SWITCH_CONSUMER_GROUP_FOR_USER Procedure Parameters
Parameter | Description |
---|---|
user |
The name of the user. |
consumer_group |
The name of the consumer group to switch to. |
Usage Notes
The SWITCH_CONSUMER_GROUP_FOR_SESS Procedure and SWITCH_CONSUMER_GROUP_FOR_USER
procedures let you to raise or lower the allocation of CPU resources of certain sessions or users. This provides a functionality similar to the nice
command on UNIX.
These procedures cause the session to be moved into the newly specified consumer group immediately.
This procedure sets the current resource manager plan.
Syntax
DBMS_RESOURCE_MANAGER.SWITCH_PLAN( plan_name IN VARCHAR2, sid IN VARCHAR2 DEFAULT '*', allow_scheduler_plan_switches IN BOOLEAN DEFAULT TRUE);
Parameters
Table 105-17 SWITCH_PLAN Procedure Parameters
Parameter | Description |
---|---|
plan_name |
The name of the plan to which to switch. Passing in an empty string ('') for the plan_name , disables the resource manager |
sid |
The sid parameter is relevant only in a Oracle Real Application Clusters environment. This parameter lets you change the plan for a particular instance. Specify the sid of the instance where you want to change the plan. Or specify '*' if you want Oracle to change the plan for all instances. |
allow_scheduler_plan_switches |
FALSE - disables automated plan switches by the job scheduler at window boundaries. To re-enable automated plan switches, switch_plan must be called again by the administrator with allow_scheduler_plan_switches set to TRUE . By default automated plan switches by the job scheduler are enabled. |
This procedure updates entries which define resource consumer groups.
Syntax
DBMS_RESOURCE_MANAGER.UPDATE_CONSUMER_GROUP ( consumer_group IN VARCHAR2, new_comment IN VARCHAR2 DEFAULT NULL, new_cpu_mth IN VARCHAR2 DEFAULT NULL, new_mgmt_mth IN VARCHAR2 DEFAULT NULL);
Parameters
Table 105-18 UPDATE_CONSUMER_GROUP Procedure Parameter
Parameter | Description |
---|---|
consumer_group |
The name of consumer group |
new_comment |
New user's comment |
new_cpu_mth |
Name of new method for CPU resource allocation (deprecated) |
new_mgmt_mth |
Name of new method for CPU resource allocation |
Usage Notes
If the parameters to the UPDATE_CONSUMER_GROUP
procedure are not specified, then they remain unchanged in the data dictionary.
This procedure updates entries which define resource plans.
Syntax
DBMS_RESOURCE_MANAGER.UPDATE_PLAN ( plan IN VARCHAR2, new_comment IN VARCHAR2 DEFAULT NULL, new_cpu_mth IN VARCHAR2 DEFAULT NULL, -- deprecated new_active_sess_pool_mth IN VARCHAR2 DEFAULT NULL, new_parallel_degree_limit_mth IN VARCHAR2 DEFAULT NULL, new_queueing_mth IN VARCHAR2 DEFAULT NULL, new_queueing_mth IN VARCHAR2 DEFAULT NULL, new_mgmt_mth IN VARCHAR2 DEFAULT NULL);
Parameters
Table 105-19 UPDATE_PLAN Procedure Parameters
Parameter | Description |
---|---|
plan |
The name of resource plan. |
new_comment |
New user's comment. |
new_cpu_mth |
The name of new allocation method for CPU resources (deprecated). |
new_active_sess_pool_mth |
The name of new method for maximum active sessions. |
new_parallel_degree_limit_mth |
The name of new method for degree of parallelism. |
new_queueing_mth |
Specifies type of queuing policy to use with active session pool feature. |
new_mgmt_mth |
The resource allocation method for specifying how much resources (e.g. CPU or I/O) each consumer group or sub-plan gets
|
Usage Notes
If the parameters to UPDATE_PLAN Procedure are not specified, then they remain unchanged in the data dictionary.
If you want to use any default resource allocation method, then you do not need not specify it when creating or updating a plan.
This procedure updates resource plan directives.
Syntax
DBMS_RESOURCE_MANAGER.UPDATE_PLAN_DIRECTIVE ( plan IN VARCHAR2, group_or_subplan IN VARCHAR2, new_comment IN VARCHAR2 DEFAULT NULL, new_cpu_p1 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p2 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p3 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p4 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p5 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p6 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p7 IN NUMBER DEFAULT NULL, -- deprecated new_cpu_p8 IN NUMBER DEFAULT NULL, -- deprecated new_active_sess_pool_p1 IN NUMBER DEFAULT NULL, new_queueing_p1 IN NUMBER DEFAULT NULL, new_parallel_degree_limit_p1 IN NUMBER DEFAULT NULL, new_switch_group IN VARCHAR2 DEFAULT NULL, new_switch_time IN NUMBER DEFAULT NULL, new_switch_estimate IN BOOLEAN DEFAULT FALSE, new_max_est_exec_time IN NUMBER DEFAULT NULL, new_undo_pool IN NUMBER DEFAULT NULL, new_max_idle_time IN NUMBER DEFAULT NULL, new_max_idle_blocker_time IN NUMBER DEFAULT NULL, switch_time_in_call IN NUMBER DEFAULT NULL, -- deprecated mgmt_p1 IN NUMBER DEFAULT NULL, mgmt_p2 IN NUMBER DEFAULT NULL, mgmt_p3 IN NUMBER DEFAULT NULL, mgmt_p4 IN NUMBER DEFAULT NULL, mgmt_p5 IN NUMBER DEFAULT NULL, mgmt_p6 IN NUMBER DEFAULT NULL, mgmt_p7 IN NUMBER DEFAULT NULL, mgmt_p8 IN NUMBER DEFAULT NULL, switch_io_megabytes IN NUMBER DEFAULT NULL, switch_io_reqs IN NUMBER DEFAULT NULL, switch_for_call IN BOOLEAN DEFAULT NULL);
Parameters
Table 105-20 UPDATE_PLAN_DIRECTIVE Procedure Parameters
Parameter | Description |
---|---|
plan |
The name of the resource plan. |
group_or_subplan |
The name of the consumer group or subplan. |
new_comment |
Comment for the plan directive. |
new_cpu_p1 |
First parameter for the CPU resources allocation method ((deprecated - use new_mgmt_p1 instead) |
new_cpu_p2 |
Parameter for the CPU resources allocation method ((deprecated - use new_mgmt_p2 instead) |
new_cpu_p3 |
Parameter for the CPU resources allocation method (deprecated - use new_mgmt_p3 instead) |
new_cpu_p4 |
Parameter for the CPU resources allocation method (deprecated- use new_mgmt_p4 instead) |
new_cpu_p5 |
Parameter for the CPU resources allocation method (deprecated - use new_mgmt_p5 instead) |
new_cpu_p6 |
Parameter for the CPU resources allocation method (deprecated- use new_mgmt_p6 instead) |
new_cpu_p7 |
Parameter for the CPU resources allocation method (deprecated- use new_mgmt_p7 instead) |
new_cpu_p8 |
Parameter for the CPU resources allocation method (deprecated- use new_mgmt_p8 instead) |
new_active_sess_pool_p1 |
Specifies maximum number of concurrently active sessions for a consumer group. Default is NULL , which means unlimited. |
new_queueing_p1 |
Specified time (in seconds) after which a job in the inactive session queue (waiting for execution) will time out. Default is NULL , which means unlimited. |
new_switch_group |
Specifies a limit on the degree of parallelism for any operation. Default is NULL , which means unlimited. Switches to another group once a switch condition is met. |
new_switch_time |
Specifies consumer group to which this session is switched if other switch criteria is met. Default is NULL . If the group name is 'CANCEL_SQL ', the current call will be canceled when other switch criteria are met. If the group name is 'KILL_SESSION ', the session will be killed when other switch criteria are met. |
new_switch_estimate |
Specifies time (in seconds) that a session can execute before an action is taken. Default is NULL , which means unlimited. |
new_max_est_exec_time |
If TRUE , tells Oracle to use its execution time estimate to automatically switch the consumer group of an operation before beginning its execution. Default is FALSE . |
new_undo_pool |
Specifies the maximum execution time (in seconds) allowed for a session. If the optimizer estimates that an operation will take longer than MAX_EST_EXEC_TIME , the operation is not started and ORA-07455 is issued. If the optimizer does not provide an estimate, this directive has no effect. Default is NULL , which means unlimited. |
new_parallel_degree_limit_p1 |
Sets a maximum in kilobytes (K ) on the total amount of undo generated by a consumer group. Default is NULL , which means unlimited. |
new_max_idle_time |
Indicates the maximum session idle time. Default is NULL , which means unlimited. |
new_max_idle_blocker_time |
The maximum amount of time in seconds that a session can be idle while blocking another session's acquisition of a resource. |
new_switch_time_in_call |
Deprecated. If this parameter is specified, new_switch_time will be effectively set to new_switch_time_in_call and new_switch_for_call will be effectively set to TRUE . |
new_mgmt_p1 |
Resource allocation value for level 1 (replaces new_cpu_p1 ):
|
new_mgmt_p2 |
Resource allocation value for level 2 (replaces new_cpu_p2 )
|
new_mgmt_p3 |
Resource allocation value for level 3 (replaces new_cpu_p3 )
|
new_mgmt_p4 |
Resource allocation value for level 4 (replaces new_cpu_p4 )
|
new_mgmt_p5 |
Resource allocation value for level 5 (replaces new_cpu_p5 )
|
new_mgmt_p6 |
Resource allocation value for level 6 (replaces new_cpu_p6 )
|
new_mgmt_p7 |
Resource allocation value for level 7 (replaces new_cpu_p7 )
|
new_mgmt_p8 |
Resource allocation value for level 8 (replaces new_cpu_p8 )
|
new_switch_io_megabytes |
Specifies the amount of I/O (in MB) that a session can issue before an action is taken. Default is NULL , which means unlimited. |
new_switch_io_reqs |
Specifies the number of I/O requests that a session can issue before an action is taken. Default is NULL , which means unlimited. |
new_switch_for_call |
Specifies that if an action is taken because of the new_switch_time , new_switch_io_megabytes , or new_switch_io_reqs parameters, the consumer group is restored to its original consumer group at the end of the top call. Default is FALSE , which means that the original consumer group is not restored at the end of the top call. |
Usage Notes
If the parameters for UPDATE_PLAN_DIRECTIVE
are left unspecified, then they remain unchanged in the data dictionary.
For new_max_idle_time
and new_max_idle_blocker_time
, PMON
will check these limits once a minute. If it finds a session that has exceeded one of the limits, it will forcibly kill the session and clean up all its state.
The parameter new_switch_time_in_call
is mostly useful for three-tier applications where the mid-tier server is implementing session pooling. By turning on new_switch_time_in_call
, the resource usage of one client will not affect the consumer group of a future client that happens to be executed on the same session.
This procedure validates pending changes for the resource manager.
Syntax
DBMS_RESOURCE_MANAGER.VALIDATE_PENDING_AREA;