Implementing Resource Management

30
C H A P T E R

In This Chapter
How resource management works How to create a resource plan The DBMS_RESOURCE_ MANAGER reference The DBMS_RESOURCE_ MANAGER_PRIVS reference Resource management and the data dictionary

esource management is a new feature in Oracle8i that allows you to apportion CPU resources amongst various users and groups of users. The potential for one user or group of users to consume an inordinate amount of resources has always existed. In prior releases of Oracle, you could attempt to address such problems through user profiles, but user profiles are limited. They can cut off a user after that user consumes a certain amount of CPU or I/O, but they cant do the same for a group of users. Also, user profiles cannot meter resources such that a user can spread the effort of executing a large query out over a larger period of time. Oracle8is resource management feature brings flexibility to the table. You can apportion CPU time to different user groups on a percentage basis, and you can identify some groups as having a higher priority than others. By doing this, you can ensure that users who are performing critical functions always have the necessary CPU resources available, regardless of what other users may be doing at the same time. In this chapter, youll learn how to create and manage resource plans in a database.

How Resource Management Works

Resource management works by dividing users into groups based on common resource requirements. A resource plan is then put into place that allocates CPU time amongst the groups that have been defined. This allows you to ensure that no single user, or group of users, uses up all the processing capacity.

780

Part VI Advanced Topics

Understanding plans, directives, and consumer groups

The resource plan is the basis for resource management in a database. A resource plan functions at the instance level, and it consists of a number of resource directives that control how CPU time is allocated to the users connected to that instance. You may define several resource plans for a database, but only one plan can be in effect for an instance at any given time. Resource plans are made up of resource directives. A resource directive is a statement giving a user or a named group of users a specific allotment of CPU time. This allotment is expressed as a percentage of the whole. Resource directives also perform two other functions. You can use them to prioritize groups of consumers, and you can use them to place limits on the degree of parallelism available to a consumer group. Finally, at the bottom of all this is the resource consumer group. A resource consumer group is a named group of users who each have similar resource requirements. For example, you may have a decision support consumer group and a customer care consumer group. The diagram shown in Figure 30-1 illustrates how you can use the directives for a resource plan to apportion CPU resources to the various consumer groups in a database. Figure 30-1 shows two consumer groups: the decision support group and the customer care group. The decision support group consists of users who are executing long-running, CPU-intensive, ad hoc queries. The customer care group is composed of users responding to phone calls and other client inquiries. They tend to execute short, predefined queries. Recognizing that its more important to respond quickly to a customer, 80 percent of the CPU resources have been dedicated to the customer care group. Only 20 percent can be used by the decision support users.

Understanding priority
In addition to allocating CPU by percentage, you can also prioritize those allocations into as many as eight levels. By assigning priorities, you can further subdivide CPU capacity. With respect to the example shown previously in Figure 30-1, you could subdivide the decision support users into two groups: one for vice presidents and one for other executives. Figure 30-2 illustrates this, showing that the vice presidents get most of the decision support CPU capacity. Here, the customer care group gets 80 percent of CPU allocation. This is just as before. The remaining 20 percent still goes to the decision support users, but that 20 percent has been divided between two distinct subgroups. Vice presidents get 70 percent of the 20 percent allocated to decision support, while all other executives get 30 percent of that 20 percent.

Chapter 30 Implementing Resource Management

781

Resource Plan

Plan Directives

80 percent of CPU

20 percent of CPU

Customer Care Consumer Group

Decision Support Consumer Group

Figure 30-1: Resource directives apportion CPU resources to consumer groups.

Resource Plan

Level 1 80 percent Plan Directives Level 2 70 percent Level 2 30 percent

Customer Care Consumer Group

Vice-President Consumer Group

Other Executives Consumer Group

Figure 30-2: Decision support users will get bumped by the higher-priority customer care users.

782

Part VI Advanced Topics

Nesting plans
Resource plans may also be nested. You can divide one plan into two or more subplans. As with resource priorities, you can also use nested plans to divide and subdivide CPU allocation between various groups and subgroups. However, when a system is not fully loaded, Oracle distributes extra CPU time differently depending on whether plans or priorities are involved. Figure 30-3 shows another way of dividing the CPU time among the three consumer groups shown earlier.

Resource Plan

Plan Directives

Level 1 80 percent

Level 1 20 percent

Customer Care Consumer Group

Decision Support Resource Plan

Level 1 70 percent

Level 1 30 percent

Plan Directives

Vice-President Consumer Group

Other Executives Consumer Group

Figure 30-3: CPU allocation divided between three consumer groups

At first glance, it appears that the results of using nested resource plans are the same as you get when you prioritize CPU time. A difference does exist, though, and its an important one. The key to understanding the difference lies in understanding

Chapter 30 Implementing Resource Management

783

that extra CPU time is allocated to other users in the same plan based on the priority of those users. With a single plan, such as that shown in Figure 30-2, any extra CPU time is allocated to users on a priority basis. So if the vice presidents arent using all of their allotted CPU time, Oracle will reallocate that CPU time on a priority basis. Thus, it might go to the customer care users because they are priority 1 before it would go to the priority 2 users. The rules change, however, when a resource plan contains one or more subplans. As long as there is at least one user for a subplan, the subplan gets all of its CPU allotment. With respect to Figure 30-3, if there was only one decision support user, that user would be able to use all of the CPU allocated to the decision support plan. In other words, excess CPU allocation within the decision support group goes to other decision support users. Only if no decision support users are logged on at all will that 20 percent become available to the customer care users.

How to Create a Resource Plan

In order to use Oracle8is resource management features, you need to create a resource plan for your database. The resource plan identifies the consumer groups and allocates resources among them. The process for creating and implementing a resource plan for a database looks like this: 1. Create a work area for use in building the new plan. 2. Create the plan. 3. Create resource consumer groups. 4. Create resource plan directives. 5. Validate the plan. 6. Move the plan from the work area. 7. Set the active plan for the instance. The work area used to build new resource plans is known as the pending area. The process for defining a plan can get fairly complex if you have a lot of different priorities and subplans. The pending area gives you a place to create and revise a plan at your leisure, without having to worry that your partially built plan will affect database operations. This becomes especially important if you happen to be revising the plan that is currently active. Two built-in PL/SQL packages are used for creating and managing resource plans. You use the DBMS_RESOURCE_MANAGER package to create plans, plan directives, and consumer groups. You use the DBMS_RESOURCE_MANAGER_PRIVS package to grant privileges related to resource plans.

784

Part VI Advanced Topics

Prerequisites
To work with resource plans, you need to hold a special privilege known as ADMINISTER_RESOURCE_MANAGER. This privilege is not a standard system privilege, nor is it a role. Its a privilege that exists only within the context of resource management.

Granting the ADMINISTER_RESOURCE_MANAGER Privilege

The SYSTEM user and the DBA role each hold the ADMINISTER_RESOURCE_MANAGER privilege by default. The SYSTEM user, or a user with the DBA role, can grant the ADMINISTER_RESOURCE_MANAGER privilege to other users by making a call to the GRANT_SYSTEM_PRIVILEGE procedure in the DBMS_RESOURCE_MANAGER_PRIVS package. For example, the following call grants this privilege to the user SEAPARK:
DBMS_RESOURCE_MANAGER_PRIVS.GRANT_SYSTEM_PRIVILEGE ( SEAPARK, ADMINISTER_RESOURCE_MANAGER, FALSE);

The third argument indicates whether the user getting the privilege is allowed to further grant that privilege to others. A value of TRUE allows the user to do that. A value of FALSE prevents the user from further granting the privilege. This is exactly like the WITH ADMIN OPTION of SQLs GRANT command.
Note

Granting someone the ADMINISTER_RESOURCE_MANAGER privilege allows him or her to create and manage plans, but it doesnt provide access to the system views that return information about resource plans. You need to grant SELECT access to those views as a separate operation.

Determining Who Has the ADMINISTER_RESOURCE_MANAGER Privilege

If you want to find out which users hold the ADMINISTER_RESOURCE_MANAGER privilege, you can query the DBA_RSRC_MANAGER_SYSTEM_PRIVS view. This view returns one row for each user with the privilege. Consider this example:
SQL> SELECT * 2 FROM dba_rsrc_manager_system_privs; GRANTEE -------------------CTXSYS DBA EXP_FULL_DATABASE IMP_FULL_DATABASE MDSYS SYSTEM PRIVILEGE -----------------------------ADMINISTER RESOURCE MANAGER ADMINISTER RESOURCE MANAGER ADMINISTER RESOURCE MANAGER ADMINISTER RESOURCE MANAGER ADMINISTER RESOURCE MANAGER ADMINISTER RESOURCE MANAGER ADMIN_OPTION ------------NO YES NO NO NO YES

The USER_RSRC_MANAGER_SYSTEM_PRIVS view returns the same information, but only for the current logged-on user. You can query from that if you just want to check whether you have the privilege yourself.

Chapter 30 Implementing Resource Management

785

Note

The DBA_SYS_PRIVS view also shows who has the ADMINISTER RESOURCE MANAGER privilege. Thats rather odd, because you cant use the standard GRANT and REVOKE commands to manage it.

Creating the pending area

The first step in the process of creating a new resource plan is to create a pending area. Do that with a call to DBMS_RSRC_MANAGER.CREATE_PENDING_AREA. Consider this example:
SQL> EXECUTE DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA(); PL/SQL procedure successfully completed.

Everything else that you do now will be done in the pending area. When the new plan is defined as you want it to be, you can commit the pending changes.

Creating the plan

You create a plan by making a call to the DBMS_RESOURCE_MANAGER packages CREATE_PLAN procedure. All you need is a name for the plan and a comment describing the plan. The examples in this chapter show you how to implement the scenario shown in Figure 30-3. In that scenario, there was a plan and a subplan. The following example creates these two plans. The top-level plan is named NORMAL, while the plan for decision support users is named DECISION.
BEGIN DBMS_RESOURCE_MANAGER.CREATE_PLAN ( NORMAL, Use this plan for normal operations.); DBMS_RESOURCE_MANAGER.CREATE_PLAN ( DECISION, The decision support subplan.); END; /

Creating these plans really gives you nothing more than two names. For those plans to mean anything, you need to define consumer groups and then create plan directives to allocate resources among those groups. Also, the link between the two plans is defined using a plan directive. Youll see how this is done later in this chapter.

786

Part VI Advanced Topics

Creating resource consumer groups

Before you can create plan directives, you need to create consumer groups. Only after you have your plans and consumer groups defined can you link the two using directives. To create a consumer group, you need a name and a comment. With that information, you make a call to the CREATE_CONSUMER_GROUP procedure in the DBMS_RESOURCE_MANAGER package. Listing 30-1 shows the code needed to create the three consumer groups shown in Figure 30-3.

Listing 30-1: Creating consumer groups

BEGIN DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( Customer Care, Customer care users take phone calls from clients. ); DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( VP DSS Users, Vice-President decision support users ); DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( Other DSS Users, Other decision support users ); END; /

The next step is to link your newly created consumer groups to your resource plans.

Creating resource plan directives

With the consumer groups and resource plans created, now you can create resource plan directives to allocate resources between them. You use the DBMS_RESOURCE_MANAGER packages CREATE_PLAN_DIRECTIVE procedure to do this. A directive always links a resource plan with either another resource plan or with a consumer group. Every plan has a certain percentage of database resources to

Chapter 30 Implementing Resource Management

787

allocate. The top-level plan has 100 percent of those resources. The directives for each plan must then further allocate the resources that have been assigned to that plan. In our case (refer back to Figure 30-3), the first split involves giving 80 percent of database resources to the customer care group and 20 percent to the decision support group. The code in Listing 30-2 makes this initial 80/20 split.

Listing 30-2: Creating the directives for an 80/20 resource split

BEGIN DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL, Customer Care, Resource allocation for customer care group., cpu_p1 => 70 ); DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL, DECISION, Resource allocation for decision support users., cpu_p1 => 20 ); END; /

The first call to CREATE_PLAN_DIRECTIVE allocates 70 percent of CPU time to the customer care group under the normal plan. The second call allocates 20 percent of CPU time to the decision support group. Why a 70/20 split instead of the 80/20 split called for in our scenario? The missing 10 percent is for a special group called OTHER_GROUPS. Oracle requires that some resources be set aside for users and groups for which you have not explicitly allocated resources. To further subdivide the decision support groups 20 percent, you execute the code shown in Listing 30-3.

Listing 30-3: Subdividing resource allocation

BEGIN DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( DECISION,
Continued

788

Part VI Advanced Topics

Listing 30-3 (continued)

VP DSS Users, For the vice-presidents., cpu_p1 => 70 ); DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( DECISION, Other DSS Users, For the other executives., cpu_p1 => 30 ); END; /

The first parameter to the CREATE_PLAN_DIRECTIVE procedure is the plan name. This time, the plan name given is DECISION. Thats because this 70/30 split applies to the decision support group. Finally, assign that 10 percent that we held back earlier to the OTHER_GROUPS group. Here is the code to do this. Notice that the 10 percent comes from the plan named NORMAL. It could come from any plan, but NORMAL is where we held back the 10 percent, so well use this 10 percent.
BEGIN DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL, OTHER_GROUPS, For users not part of any group., cpu_p1 => 10 ); END; /

The OTHER_GROUPS parameter is a group name that Oracle recognizes automatically. You dont have to create that group. You just have to create a plan directive that allocates resources to it.

Submitting the pending area

After you have created the resource plan and the consumer groups, and after you have created the plan directives necessary to apportion resources amongst the various groups, you are ready to make your changes permanent. This involves two steps: validating the pending area and submitting the pending area.

Chapter 30 Implementing Resource Management

789

Validating the Pending Area

Before you make the changes in the pending area permanent, you need to validate them using the VALIDATE_PENDING_AREA procedure in the DBMS_RESOURCE_ MANAGER package. The VALIDATE_PENDING_AREA procedure verifies that the following statements are true: Consumer group names and plan names referenced by plan directives really exist. Plans have directives. Plans are not nested in such a way that circular references exist. You have not deleted a plan that is currently being used as the top-level plan by a running database instance. Your percentages dont add up to more than 100 percent. You dont have a plan and a resource group with the same name. Somewhere, you have a plan directive that allocates resources to a group named OTHER_GROUPS. This is for users who havent specifically been assigned to a group in the currently active plan. The call to VALIDATE_PENDING_AREA is simple, and it looks like this:
BEGIN DBMS_RESOURCE_MANAGER.VALIDATE_PENDING_AREA(); END; /

If validation fails, you will receive an error message. The following message shows the error message that you will receive if you forget to allocate resources for OTHER_GROUPS:
ERROR at line 1: ORA-29382: validation of pending area failed ORA-29377: consumer group OTHER_GROUPS is not part of top-plan NORMAL ORA-06512: at SYS.DBMS_RMIN, line 249 ORA-06512: at SYS.DBMS_RESOURCE_MANAGER, line 254 ORA-06512: at line 2

If you receive an error, you need to fix it and then retry the validation. The DBMS_ RESOURCE_MANAGER package does implement procedures for updating and deleting resource plans, consumer groups, and plan directives. These procedures are described later in this chapter.

790

Part VI Advanced Topics

Submitting the Pending Area

If you can successfully validate the pending area, then its time to submit your changes and make them permanent. The call to the SUBMIT_PENDING_AREA procedure in the following code takes the changes from the pending area and puts them into effect:
BEGIN DBMS_RESOURCE_MANAGER.SUBMIT_PENDING_AREA(); END; /

If all youve done is modify existing plans and directives, you can probably stop here. If you are implementing resource management for the first time, you will now need to assign users to the new consumer groups that youve created. After that, you will need to issue an ALTER SYSTEM command to activate your new plan.
Note

The SUBMIT_PENDING_AREA procedure makes an implicit call to VALIDATE_ PENDING_AREA. Changes are always validated prior to being submitted.

Placing users into groups

You can place users only into groups that exist in the permanent area. If you have a new consumer group that youve created and it exists only in the pending area, you will need to wait until after submitting your changes to assign users to that group. Before placing a user into a consumer group, you must grant that user switch privileges on the group. The switch privilege allows a user to switch into a consumer group. Its a strange-sounding name, but thats what Oracle chose to use.

Granting Switch Privileges

To grant a user switch privileges on a group, use the GRANT_SWITCH_CONSUMER_ GROUP procedure in the DBMS_RESOURCE_MANAGER_PRIVS package. The code in the following example grants the user SEAPARK access to the customer care consumer group:
BEGIN DBMS_RESOURCE_MANAGER_PRIVS.GRANT_SWITCH_CONSUMER_GROUP ( SEAPARK, Customer Care, FALSE); END; /

You can actually grant a user switch privileges on several consumer groups, enabling that user to switch back and forth between groups at will. That can be useful if you have one user who runs two different types of applications. If youve written the applications in-house, you can program the applications to automatically switch the user to the appropriate consumer group.

Chapter 30 Implementing Resource Management

791

Tip

If you dont want users changing their consumer group setting, then grant them switch privileges only on one group, and make that group their initial group. They wont be able to switch out of it.

Setting a Users Initial Consumer Group

To set a users initial consumer group, which is the one assigned when the user first connects to an instance, use the SET_INITIAL_CONSUMER_GROUP procedure. The following example sets the initial group for the SEAPARK user to be the customer care group:
BEGIN DBMS_RESOURCE_MANAGER.SET_INITIAL_CONSUMER_GROUP ( SEAPARK, Customer Care); END; /

Once logged on, users can switch themselves to other consumer groups, providing they have been granted access to those groups, by using the DBMS_RESOURCE_ MANAGER packages SWITCH_CURRENT_CONSUMER_GROUP procedure. You can also change groups for a user by using the SWITCH_CURRENT_CONSUMER_GROUP_FOR_ SESS and SWITCH_CURRENT_CONSUMER_GROUP_FOR_USER procedures. Youll read more about these procedures later in this chapter.

Setting the plan for an instance

Finally, you need to set your new plan as the current plan for the instance. You can do that in one of two ways. You can set the resource plan for an instance dynamically by using the ALTER SYSTEM command, or you can set a parameter in the instances parameter file.
Note

You need the ALTER command.

SYSTEM system privilege to issue the ALTER

SYSTEM

The RESOURCE_MANAGER_PLAN parameter defines the current resource plan for an instance. The following ALTER SYSTEM command sets it to the plan created in this chapter, which is named NORMAL:
ALTER SYSTEM SET resource_manager_plan = normal;

To set the plan used when you first start the instance, you can place a line like the following in your instances initialization parameter file:
resource_manager_plan = normal

792

Part VI Advanced Topics

Using the ALTER SYSTEM command, you can change resource plans at will. You can use one plan during the day and a different plan at night. One plan might tilt the balance of resources towards online users, while the other might favor decision support users. The possibilities are endless. Oracle8is resource management feature gives you a great deal of flexibility in controlling how a database is used.
Note

Remember that you must stop and restart your database before any changes that you make in your initialization parameter file take effect.

Using multilevel plans

The preceding example implemented the scenario described in Figure 30-3. This scenario contained two plans, each with one level of resource allocation. Figure 30-2 illustrated an alternate scenario containing one plan and two levels of resource allocation underneath that plan. The difference between the two approaches lies in how excess CPU time for a plan is allocated. The code shown in Listing 30-4 implements the scenario shown in Figure 30-2.

Listing 30-4: Implementing a multi-lever resource plan

BEGIN --Create one plan. DBMS_RESOURCE_MANAGER.CREATE_PLAN ( NORMAL, Use this plan for normal operations.); --Create the three consumer groups. DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( Customer Care, Customer care users take phone calls from clients. ); DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( VP DSS Users, Vice-President decision support users ); DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP ( Other DSS Users, Other decision support users ); --Create the plan directives to allocate --resources to the three groups. DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL,

Chapter 30 Implementing Resource Management

793

Customer Care, Resource allocation for customer care group., cpu_p1 => 70 ); DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL, VP DSS Users, Resource allocation for the vice presidents, cpu_p2 => 70 ); DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL, Other DSS Users, Resource allocation for the other executives, cpu_p2 => 30 ); --Dont forget the special case of OTHER_GROUPS. DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( NORMAL, OTHER_GROUPS, For users not part of any group., cpu_p1 => 10 ); END; /

Notice that this listing contains only one plan: the Normal plan. Three consumer groups are defined the same as in the previous scenario. The major difference is in how resources are allocated to those groups. The customer care group is allocated 70 percent of CPU resources at level 1. That leaves 30 percent for the other two groups. That 30 percent is allocated between the other groups using the CPU_P2 parameter. Level 1 users take priority over any level 2 users, so if the vice presidents arent using all of their CPU allocation, the customer care users, not the other executives, will get first crack at it.

Making changes
To make changes to resource plans, consumer groups, and plan directives, you need to follow this procedure: 1. Create a pending area. 2. Make whatever changes you need to make.

794

Part VI Advanced Topics

3. Validate the pending area. 4. Commit the changes in the pending area. This procedure is not very different from the one used to create a resource plan in the first place. The key difference is that here you are making modifications. The DBMS_RESOURCE_MANAGER package contains a number of routines that can be used to modify consumer groups and plan directives, and the interface to these routines is very similar to the various create routines that youve read about so far. For example, Listing 30-5 shows two plan directives being modified. Ten percent is taken from the customer care group and given over to the special group named OTHER_GROUPS.

Listing 30-5: Modifying resource plan directives

SQL> EXECUTE DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA(); PL/SQL procedure successfully completed. SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.UPDATE_PLAN_DIRECTIVE > (NORMAL,CUSTOMER CARE,NEW_CPU_P1=>60); PL/SQL procedure successfully completed. SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.UPDATE_PLAN_DIRECTIVE > (NORMAL,OTHER_GROUPS,NEW_CPU_P1=>20); PL/SQL procedure successfully completed. SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.VALIDATE_PENDING_AREA; PL/SQL procedure successfully completed. SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.SUBMIT_PENDING_AREA; PL/SQL procedure successfully completed.

In the same manner, you can also update consumer groups, delete consumer groups, delete plan directives, and even delete resource plans.

Chapter 30 Implementing Resource Management

795

The DBMS_RESOURCE_MANAGER Reference

The DBMS_RESOURCE_MANAGER package has entry points for creating, updating, and deleting resource plans, plan directives, and consumer groups. Youve seen most of the create procedures in this chapters examples. Each of those create procedures has corresponding update and delete procedures. All of these procedures are described in this section.

How to reference a procedure

The procedures described in this section are all part of the DBMS_RESOURCE_ MANAGER package. For simplicity, the package name has been omitted from the procedure definitions. Whenever you use a procedure, you must preface it with the package name, as shown in the following example:
DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA;

Notice the period separating the package name from the procedure name. The use of a period for that purpose is standard within PL/SQL.

Optional parameters
Many of the procedures in the DBMS_RESOURCE_MANAGER package have optional parameters in their interfaces. An optional parameter is one that you dont have to pass when you call the procedure. The nature of these procedures is such that its quite common to omit a number of parameters, so passing parameters using named notation rather than position notation is often convenient. You use positional notation to pass parameters by position, as shown in the following example:
DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( my plan, my group, null, null, 80);

In this example, the first parameter that is listed in the procedure call corresponds to the first formal parameter defined for the procedure, the second parameter that is listed corresponds to the second formal parameter, and so forth. The 80 in this example corresponds to the CPU_P2 parameter. The two NULL parameters correspond to the COMMENT and CPU_P1 parameters. Nulls need to be passed in as placeholders here, to make the value of 80 correspond with the fifth formal parameter, which is CPU_P2.

796

Part VI Advanced Topics

An easier way to skip parameters is to use named notation. By naming each parameter explicitly, you relieve yourself of the burden of passing nulls for parameters that you want to skip. You can even mix positional and named location if you like. The following example uses positional notation for the first two param-eters and then switches to named notation for the third:
DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE ( my plan, my group, CPU_P2=>80);

No values at all were specified for the COMMENT and CPU_P1 parameters, which has the same effect as passing in nulls.
Note

With named notation, your parameters dont need to be passed in any particular order. With positional notation, the order determines the correspondence between the actual and formal parameters.

The pending area

Oracle requires that resource plan changes be made in the pending area, not to the live plan being used for the instance. Only after the changes have been validated can they be put into effect.

Creating the Pending Area

To create a pending area and begin a new round of changes, use the CREATE_
PENDING_AREA procedure. This is shown as follows: CREATE_PENDING_AREA;

There are no parameters for this procedure.

Validating the Pending Area

After youve made changes to resource plans, consumer groups, and resource plan directives, validate those changes before committing them. Use the VALIDATE_ PENDING_AREA procedure for that purpose:
VALIDATE_PENDING_AREA;

There are no parameters for this procedure. If the procedure detects any problems with the changes that youve made in the pending area, you will receive an error message. Fix the problem identified by the error message, and try the validation again. If you have multiple problems, you may have to iterate through this process several times.

Chapter 30 Implementing Resource Management

797

Submitting the Pending Area

To submit the changes in the pending area, use the SUBMIT_PENDING_AREA procedure:
SUBMIT_PENDING_AREA;

There are no parameters for this procedure. Note that a call to SUBMIT_PENDING_ AREA implies a call to VALIDATE_PENDING_AREA as well. Oracle wont allow the changes to be submitted if a validation error occurs.

Erasing the Pending Area

If you are in the middle of making changes and decide that you dont want to make them, you can erase the pending area by calling the CLEAR_PENDING_AREA procedure:
CLEAR_PENDING_AREA;

There are no parameters for this procedure. Clearing the pending area gets rid of it completely. If you want to make changes afterwards, you will need to issue another call to CREATE_PENDING_AREA.

Resource plans
Resource plans describe how a database is to allocate resources. The DBMS_ RESOURCE_MANAGER package contains procedures for creating, updating, and deleting these plans.

Creating Resource Plans

Use the CREATE_RESOURCE_PLAN procedure to create a resource plan:
CREATE_PLAN ( plan comment cpu_mth IN VARCHAR2, IN VARCHAR2, IN VARCHAR2 DEFAULT EMPHASIS, max_active_sess_target_mth IN VARCHAR2 DEFAULT MAX_ACTIVE_SESS_ABSOLUTE, parallel_degree_limit_mth IN VARCHAR2 DEFAULT PARALLEL_DEGREE_LIMIT_ABSOLUTE);

The following list describes the parameters in this syntax: plan A name for the plan that you are creating. This may be up to 30 characters long.

798

Part VI Advanced Topics

comment A comment describing the plan. This may be up to 2,000 characters long. cpu_mth The method to use in allocating CPU resources. The default is EMPHASIS. max_active_sess_target_mth The method to use in allocating the maximum number of sessions. The default is MAX_ACTIVE_SESS_ABSOLUTE. parallel_degree_limit_mth The method to use in limiting the degree of parallelism. This defaults to PARALLEL_DEGREE_LIMIT_ABSOLUTE, which is currently the only supported method.

Modifying Resource Plans

Use the UPDATE_RESOURCE_PLAN procedure to update a resource plan, as follows:
UPDATE_PLAN ( plan new_comment new_cpu_mth new_max_active_sess_target_mth new_parallel_degree_limit_mth IN IN IN IN IN VARCHAR2, VARCHAR2 DEFAULT VARCHAR2 DEFAULT VARCHAR2 DEFAULT VARCHAR2 DEFAULT

NULL, NULL, NULL, NULL);

See the CREATE_RESOURCE_PLAN procedure for descriptions of these parameters. When updating a plan, identify the plan by name and pass in only those parameters whose values you want to change. To change a plans comment, for example, identify the plan by using the PLAN parameter and pass the new comment in the COMMENT parameter.
Note

You cant change a plans name. If you dont like the name, you must delete and re-create the plan.

Deleting Resource Plans

Use the DELETE_RESOURCE_PLAN procedure to delete a plan, as follows:
DELETE_PLAN ( plan IN VARCHAR2);

Pass a resource plan name, using the plan parameter, to identify the plan that you want to delete. If you want to delete not only a resource plan but also any plan directives, consumer groups, and subplans associated with the plan, you can use the following DELETE_RESOURCE_PLAN_CASCADE procedure:
DELETE_PLAN_CASCADE ( plan IN VARCHAR2);

Chapter 30 Implementing Resource Management

799

Use the plan parameter to pass in the name of the plan that you want to delete. When using DELETE_PLAN_CASCADE, be sure that you really do want to delete all the consumer groups and subplans that fall under the plan that you are deleting.

Resource plan directives

Resource plan directives form the real meat of any resource plan. Resource plans can have one or more directives, and it is these directives that describe exactly how resources are to be allocated to the various consumer groups.

Creating Plan Directives

Use the CREATE_PLAN_DIRECTIVE procedure to create a resource plan directive. See Listing 30-6.

Listing 30-6: Syntax for the CREATE_PLAN_DIRECTIVE procedure

CREATE_PLAN_DIRECTIVE ( plan group_or_subplan comment cpu_p1 cpu_p2 cpu_p3 cpu_p4 cpu_p5 cpu_p6 cpu_p7 cpu_p8 max_active_sess_target_p1 parallel_degree_limit_p1 IN IN IN IN IN IN IN IN IN IN IN IN IN VARCHAR2, VARCHAR2, VARCHAR2, NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT

NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);

The following list describes the parameters for this procedure: plan The name of the resource plan to which you want the directive to be attached. group_or_subplan The name of a group or another plan. This directive specifies the amount of resources to be allocated to the group or plan that you name. comment A comment about this directive.

800

Part VI Advanced Topics

cpu_p1 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 1 allocation, with 1 being the highest priority. cpu_p2 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 2 allocation. cpu_p3 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 3 allocation. cpu_p4 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 4 allocation. cpu_p5 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 5 allocation. cpu_p6 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 6 allocation. cpu_p7 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 7 allocation. cpu_p8 A value from 0100 specifying the percentage of CPU to allocate to the named group or plan. This is a priority 8 allocation. max_active_sess_target_p1 A target for the maximum number of sessions. This parameter is currently ignored. Oracle plans to add this functionality sometime in the future. parallel_degree_limit_p1 A limit on the degree of parallelism that users who fall under this particular directive can use.

Modifying Plan Directives

Use the UPDATE_PLAN_DIRECTIVE procedure to modify the settings for an existing directive. See Listing 30-7.

Listing 30-7: Syntax for the UPDATE_PLAN_DIRECTIVE procedure

UPDATE_PLAN_DIRECTIVE ( plan group_or_subplan comment cpu_p1 cpu_p2 cpu_p3 cpu_p4 cpu_p5 cpu_p6 IN IN IN IN IN IN IN IN IN VARCHAR2, VARCHAR2, VARCHAR2, NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT NUMBER DEFAULT

NULL, NULL, NULL, NULL, NULL, NULL,

Chapter 30 Implementing Resource Management

801

cpu_p7 cpu_p8 max_active_sess_target_p1 parallel_degree_limit_p1

IN IN IN IN

NUMBER NUMBER NUMBER NUMBER

DEFAULT DEFAULT DEFAULT DEFAULT

NULL, NULL, NULL, NULL);

See the CREATE_PLAN_DIRECTIVE procedure for parameter descriptions. To update a directive, pass in the plan and group_or_subplan parameters to identify the directive. Then pass in values only for those parameters that you wish to change.

Deleting Plan Directives

Use the DELETE_PLAN_DIRECTIVE procedure to delete a plan directive:
DELETE_PLAN_DIRECTIVE ( plan IN VARCHAR2, group_or_subplan IN VARCHAR2);

Together, the plan and group_or_subplan parameters identify the directive that you want to delete.

Consumer groups
Consumer groups represent groups of users who share a common need for resources. Rather than allocating resources to each user individually, you assign each user to an appropriate group and allocate resources to that group.

Creating Consumer Groups

Use the CREATE_CONSUMER_GROUP procedure to create a new consumer group, as follows:
CREATE_CONSUMER_GROUP ( consumer_group IN VARCHAR2, comment IN VARCHAR2, cpu_mth IN VARCHAR2 DEFAULT ROUND-ROBIN);

The following list describes the parameters for this procedure: consumer_group The name of the consumer group that you want to create. comment A comment describing the consumer group. cpu_mth The CPU resource allocation method to use for this consumer group. The default method is ROUND-ROBIN, which is also the only method currently supported.

802

Part VI Advanced Topics

Modifying Consumer Groups

Use the UPDATE_CONSUMER_GROUP procedure to modify the settings for a consumer group, as follows:
UPDATE_CONSUMER_GROUP ( consumer_group IN VARCHAR2, new_comment IN VARCHAR2 DEFAULT NULL, new_cpu_mth IN VARCHAR2 DEFAULT NULL);

See the CREATE_CONSUMER_GROUP procedure for the parameter descriptions. To update a consumer group, identify the consumer group by name using the consumer_group parameter, then pass in new values for the other parameters that you want to change.

Deleting Consumer Groups

Use the DELETE_CONSUMER_GROUP procedure to delete a consumer group, as follows:
DELETE_CONSUMER_GROUP ( consumer_group IN VARCHAR2);

Pass the consumer group name in the consumer_group parameter to identify the group that you want to delete.

Consumer group assignments

The DBMS_RESOURCE_MANAGER package implements three procedures that allow you to assign a user to a consumer group. You can set a users initial group assignment, and you can switch users to new groups while they are connected to the database.

Setting a Users Initial Consumer Group

To set the consumer group to which a user is first assigned after connecting to the database, use the SET_INITIAL_CONSUMER_GROUP procedure, as follows:
SET_INITIAL_CONSUMER_GROUP ( user IN VARCHAR2, consumer_group IN VARCHAR2);

The following list describes the parameters for this procedure: user The name of the user consumer_group The name of the consumer group to which you want to assign the user

Chapter 30 Implementing Resource Management

803

For a user to be part of a consumer group, that user must be granted switch privileges on that group. Use the DBMS_RESOURCE_MANAGER_PRIVS package, described later in this chapter, to grant access to a consumer group.

Switching a Session to Another Group

You can switch an active session to another consumer group at any time by using the SWITCH_CONSUMER_GROUP_FOR_SESS procedure, as follows:
SWITCH_CONSUMER_GROUP_FOR_SESS ( session_id IN NUMBER, session_serial IN NUMBER, consumer_group IN VARCHAR2);

The following list describes the parameters for this procedure: session_id The session ID number for the session that you want to switch session_serial The session serial number for the session that you want to switch consumer_group The new consumer group assignment for that session Together, the session_id and session_serial parameters identify the session that you want to switch. You can get a list of active sessions, including IDs and serial numbers, by querying the v$session view.

Switching a User to Another Group

You can switch an active user to another consumer group at any time by using the SWITCH_CONSUMER_GROUP_FOR_USER procedure, as follows:
SWITCH_CONSUMER_GROUP_FOR_USER ( user IN VARCHAR2, consumer_group IN VARCHAR2);

The following list describes the parameters for this procedure: user The user that you want to switch consumer_group The new consumer group assignment for that user When you issue a call to the SWITCH_CONSUMER_GROUP_FOR_USER procedure, all current sessions for the specified user will be switched.
Note

The SWITCH_CONSUMER_GROUP_FOR_USER procedure doesnt change the users initial setting. The next time the user connects, the user will be assigned to the group specified as his or her initial group. To change the initial group, use the SET_INITIAL_CONSUMER_GROUP procedure.

804

Part VI Advanced Topics

The DBMS_RESOURCE_MANAGER_PRIVS Reference

The DBMS_RESOURCE_MANAGER_PRIVS package contains four procedures that allow you to control what a user can do using the DBMS_RESOURCE_MANAGER package. Using DBMS_RESOURCE_MANAGER_PRIVS, you can identify users who will be allowed to create and change resource plans for a database. You can also grant users the privilege of changing their own consumer group assignments.
Note

The procedures described in this section are all part of the DBMS_RESOURCE_ MANAGER_PRIVS package. Remember that when referencing a procedure, you must prepend the package name to the procedure name. You reference GRANT_ SYSTEM_PRIVILEGE, for example, by writing the following: DBMS_RESOURCE_MANAGER_PRIVS.GRANT_SYSTEM_PRIVILEGE

The ADMINISTER_RESOURCE_MANAGER privilege

The ADMINISTER_RESOURCE_MANAGER privilege gives you the ability to create and manage resource plans for a database. It also gives you the ability to place users into consumer groups. To grant and revoke this privilege, you must hold it with the admin option. The default DBA role that you get when you create a database gives you this.

Granting the ADMINISTER_RESOURCE_MANAGER Privilege

You can use the GRANT_SYSTEM_PRIVILEGE procedure to grant the ADMINISTER_RESOURCE_MANAGER privilege to a user or a role, as follows:
GRANT_SYSTEM_PRIVILIGE ( grantee_name IN VARCHAR2, privilege_name IN VARCHAR2 DEFAULT ADMINISTER_RESOURCE_MANAGER, admin_option IN BOOLEAN);

The following list describes the parameters for this procedure: grantee_name The name of the user or role to which you want to grant the privilege. privilege_name The name of the privilege to grant. Currently, the only privilege that you can grant is ADMINISTER_RESOURCE_MANAGER. admin_option A TRUE condition allows the grantee to grant this privilege to other users. A FALSE condition does not.

Chapter 30 Implementing Resource Management

805

Revoking ADMINISTER_RESOURCE_MANAGER
You use the REVOKE_SYSTEM_PRIVILEGE procedure to revoke the ADMINISTER_ RESOURCE_MANAGER privilege from a user or a role, as follows:
REVOKE_SYSTEM_PRIVILIGE ( grantee_name IN VARCHAR2, privilege_name IN VARCHAR2 DEFAULT ADMINISTER_RESOURCE_MANAGER);

The following list describes the parameters for this procedure: grantee_name The name of the user or role from which you want to revoke a privilege. privilege_name The name of the privilege to revoke. Currently, this must be ADMINISTER_RESOURCE_MANAGER.

Switch privileges
Switch privileges are issued to users to allow them to switch themselves to a resource consumer group. If you assign a default resource consumer group to a user, you must at least grant the user switch privileges to that group. If you want the user to be able to choose from among several resource groups, you must grant switch privileges for each of those groups.
Note

To restrict a user to just one consumer group, grant switch privileges to the user of the group and make the group the users default consumer group.

Granting Switch Privileges

To grant switch privileges to a user or to a role, use the GRANT_SWITCH_CONSUMER_GROUP procedure, as follows:
GRANT_SWITCH_CONSUMER_GROUP ( grantee_name IN VARCHAR2, consumer_group IN VARCHAR2, grant_option IN BOOLEAN);

The following list describes the parameters for this procedure: grantee_name The name of the user or role to which you want to grant the privilege. consumer_group The name of a consumer group. This is the group to which the privilege applies.

806

Part VI Advanced Topics

grant_option The grant option flag. This may be either TRUE or FALSE, and it works like the WITH GRANT OPTION of the SQL GRANT command. A TRUE condition allows the user to further grant the identical switch privilege to other users. A FALSE condition does not.

Revoking Switch Privileges

To revoke switch privileges from a user or role, use the REVOKE_SWITCH_
CONSUMER_GROUP procedure, as follows: REVOKE_SWITCH_CONSUMER_GROUP ( grantee_name IN VARCHAR2, consumer_group IN VARCHAR2);

The following list describes the parameters for this procedure: grantee_name The name of the user or role from which you want to revoke the privilege consumer_group The name of a consumer group

Resource Management and the Data Dictionary

You can query a number of data dictionary views to find information relative to resource management in a database. These views are described in Table 30-1.

Table 30-1 Resource Manager Data Dictionary Views

View Name Description Shows you the switch privileges that have been granted to users and roles for the various consumer groups in a database. Returns information about all the consumer groups in a database. Tells you who has been granted the

DBA_RSRC_CONSUMER_GROUP_PRIVS

DBA_RSRC_CONSUMER_GROUPS DBA_RSRC_MANAGER_SYSTEM_PRIVS

ADMINISTER_RESOURCE_MANAGER
privilege.

DBA_RSRC_PLAN_DIRECTIVES DBA_RSRC_PLANS

Returns information about all resource plan directives. Returns information about all resource plans.

Chapter 30 Implementing Resource Management

807

View Name

Description Returns information about all users in the database. The INITIAL_RSRC_ CONSUMER_GROUP column shows you the initial consumer group assignment for each user. Tells you to which consumer groups you have access. Tells you whether you have been granted the ADMINISTER_RESOURCE_MANAGER privilege. Returns information about available parallel degree limit methods. Returns information about all currently active resource consumer groups. Returns information about available CPU allocation methods for consumer groups. Returns the names of all currently active resource plans. Returns information about available resource allocation methods. Returns information about all active database sessions. The RESOURCE_ CONSUMER_GROUP column shows you the consumer group to which each session currently belongs.

DBA_USERS

USER_RSRC_CONSUMER_GROUP_PRIVS USER_RSRC_MANAGER_SYSTEM_PRIVS

V$PARALLEL_DEGREE_LIMIT_MTH V$RSRC_CONSUMER_GROUP V$RSRC_CONSUMER_GROUP_CPU_MTH V$RSRC_PLAN V$RSRC_PLAN_CPU_MTH V$SESSION

As with most data dictionary views, the column names are fairly self-explanatory. In the following example, the DBA_RSRC_CONSUMER_GROUP_PRIVS view is queried to see a list of switch privileges held by the users:
SQL> SELECT * 2 FROM dba_rsrc_consumer_group_privs 3 ORDER BY grantee, granted_group; GRANTEE --------------PUBLIC PUBLIC SEAPARK SYSTEM GRANTED_GROUP ---------------------DEFAULT_CONSUMER_GROUP LOW_GROUP CUSTOMER CARE SYS_GROUP GRANT ----YES NO NO NO INI --YES NO YES YES

The INITIAL column in this view indicates the default consumer group assignment.

808

Part VI Advanced Topics

Summary
In this chapter, you learned: Resource management is a new Oracle feature that allows you to allocate CPU resources among users and groups of users. Resource management requires that users be divided into groups called consumer groups. A resource plan is then put into effect for the database. That plan contains plan directives that specify how CPU resources are to be allocated among the various consumer groups. For added versatility, subplans may also be used. Resource plan changes are always made in a pending area, which you must first create using DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA. After completing your changes, validate them by calling DBMS_RESOURCE_MANAGER. VALIDATE_PENDING_AREA. If validation succeeds, submit the changes by calling the DBMS_RESOURCE_MANAGER.SUBMIT_PENDING_AREA procedure. Submitting the changes makes them permanent. To manage resource plans and consumer groups, you need to hold the ADMINISTER_RESOURCE_MANAGER privilege. This isnt quite the same as a system privilege, and its granted using the DBMS_RESOURCE_MANAGER_ PRIVS.GRANT_SYSTEM_PRIVILEGE procedure.