Chapter 30

ImplementingResourceManagement

Resource management is a new feature in Oracle8i thatallows you to apportion CPU resources amongst various

users and groups of users. The potential for one user or groupof users to consume an inordinate amount of resources hasalways existed. In prior releases of Oracle, you could attemptto address such problems through user profiles, but userprofiles are limited. They can cut off a user after that userconsumes a certain amount of CPU or I/O, but they can’t dothe same for a group of users. Also, user profiles cannot meterresources such that a user can spread the effort of executing alarge query out over a larger period of time.

Oracle8i’s resource management feature brings flexibility tothe table. You can apportion CPU time to different user groupson a percentage basis, and you can identify some groups ashaving a higher priority than others. By doing this, you canensure that users who are performing critical functions alwayshave the necessary CPU resources available, regardless ofwhat other users may be doing at the same time. In thischapter, you’ll learn how to create and manage resourceplans in a database.

How Resource ManagementWorks

Resource management works by dividing users into groupsbased on common resource requirements. A resource planis then put into place that allocates CPU time amongst thegroups that have been defined. This allows you to ensure thatno single user, or group of users, uses up all the processingcapacity.

3030C H A P T E R

✦ ✦ ✦ ✦

In This Chapter

How resourcemanagement works

How to create aresource plan

TheDBMS_RESOURCE_MANAGER reference

TheDBMS_RESOURCE_MANAGER_PRIVSreference

Resource manage-ment and the datadictionary

✦ ✦ ✦ ✦

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 779

780 Part VI ✦ Advanced Topics

Understanding plans, directives, andconsumer groupsThe resource plan is the basis for resource management in a database. A resourceplan functions at the instance level, and it consists of a number of resourcedirectives that control how CPU time is allocated to the users connected to thatinstance. You may define several resource plans for a database, but only one plancan be in effect for an instance at any given time.

Resource plans are made up of resource directives. A resource directive is a state-ment giving a user or a named group of users a specific allotment of CPU time. Thisallotment is expressed as a percentage of the whole. Resource directives alsoperform 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 aconsumer group.

Finally, at the bottom of all this is the resource consumer group. A resourceconsumer group is a named group of users who each have similar resource require-ments. For example, you may have a decision support consumer group and acustomer care consumer group.

The diagram shown in Figure 30-1 illustrates how you can use the directives for aresource plan to apportion CPU resources to the various consumer groups in adatabase.

Figure 30-1 shows two consumer groups: the decision support group and thecustomer care group. The decision support group consists of users who areexecuting long-running, CPU-intensive, ad hoc queries. The customer care group iscomposed of users responding to phone calls and other client inquiries. They tendto execute short, predefined queries. Recognizing that it’s more important torespond quickly to a customer, 80 percent of the CPU resources have been dedi-cated to the customer care group. Only 20 percent can be used by the decisionsupport users.

Understanding priorityIn addition to allocating CPU by percentage, you can also prioritize those alloca-tions into as many as eight levels. By assigning priorities, you can further subdivideCPU capacity. With respect to the example shown previously in Figure 30-1, youcould subdivide the decision support users into two groups: one for vice presidentsand one for other executives. Figure 30-2 illustrates this, showing that the vicepresidents get most of the decision support CPU capacity.

Here, the customer care group gets 80 percent of CPU allocation. This is just asbefore. The remaining 20 percent still goes to the decision support users, but that20 percent has been divided between two distinct subgroups. Vice presidents get 70percent of the 20 percent allocated to decision support, while all other executivesget 30 percent of that 20 percent.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 780

781Chapter 30 ✦ Implementing Resource Management

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

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

Resource Plan

Customer CareConsumer Group

Level 180 percent

Other ExecutivesConsumer Group

Level 230 percent

PlanDirectives

Vice-PresidentConsumer Group

Level 270 percent

Resource Plan


80 percent of CPU

Decision SupportConsumer Group

20 percent of CPUPlanDirectives

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 781


Nesting plansResource plans may also be nested. You can divide one plan into two or moresubplans. As with resource priorities, you can also use nested plans to divide andsubdivide CPU allocation between various groups and subgroups. However, when asystem is not fully loaded, Oracle distributes extra CPU time differently dependingon whether plans or priorities are involved. Figure 30-3 shows another way ofdividing the CPU time among the three consumer groups shown earlier.

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

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

Resource Plan


Level 180 percent

Other ExecutivesConsumer Group

Level 130 percent

PlanDirectives

Level 170 percent

Level 120 percent

Decision SupportResource Plan

PlanDirectives

Vice-PresidentConsumer Group

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 782


that extra CPU time is allocated to other users in the same plan based on thepriority of those users.

With a single plan, such as that shown in Figure 30-2, any extra CPU time is allo-cated to users on a priority basis. So if the vice presidents aren’t using all of theirallotted CPU time, Oracle will reallocate that CPU time on a priority basis. Thus, itmight go to the customer care users because they are priority 1 before it would goto 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 CPUallotment. 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 toother decision support users. Only if no decision support users are logged on at allwill that 20 percent become available to the customer care users.

How to Create a Resource PlanIn order to use Oracle8i’s resource management features, you need to create aresource plan for your database. The resource plan identifies the consumer groupsand allocates resources among them. The process for creating and implementing aresource 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 differentpriorities and subplans. The pending area gives you a place to create and revise aplan at your leisure, without having to worry that your partially built plan will affectdatabase operations. This becomes especially important if you happen to berevising 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, andconsumer groups. You use the DBMS_RESOURCE_MANAGER_PRIVS package to grantprivileges related to resource plans.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 783


PrerequisitesTo work with resource plans, you need to hold a special privilege known asADMINISTER_RESOURCE_MANAGER. This privilege is not a standard system privilege,nor is it a role. It’s a privilege that exists only within the context of resourcemanagement.

Granting the ADMINISTER_RESOURCE_MANAGER PrivilegeThe SYSTEM user and the DBA role each hold the ADMINISTER_RESOURCE_MANAGERprivilege by default. The SYSTEM user, or a user with the DBA role, can grant theADMINISTER_RESOURCE_MANAGER privilege to other users by making a call to theGRANT_SYSTEM_PRIVILEGE procedure in the DBMS_RESOURCE_MANAGER_PRIVSpackage. 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 tofurther grant that privilege to others. A value of TRUE allows the user to do that. Avalue of FALSE prevents the user from further granting the privilege. This is exactlylike the WITH ADMIN OPTION of SQL’s GRANT command.

Granting someone the ADMINISTER_RESOURCE_MANAGER privilege allows himor her to create and manage plans, but it doesn’t provide access to the systemviews that return information about resource plans. You need to grant SELECTaccess to those views as a separate operation.

Determining Who Has the ADMINISTER_RESOURCE_MANAGER PrivilegeIf you want to find out which users hold the ADMINISTER_RESOURCE_MANAGERprivilege, you can query the DBA_RSRC_MANAGER_SYSTEM_PRIVS view. This viewreturns one row for each user with the privilege. Consider this example:

SQL> SELECT *2 FROM dba_rsrc_manager_system_privs;

GRANTEE PRIVILEGE ADMIN_OPTION-------------------- ------------------------------ -------------CTXSYS ADMINISTER RESOURCE MANAGER NODBA ADMINISTER RESOURCE MANAGER YESEXP_FULL_DATABASE ADMINISTER RESOURCE MANAGER NOIMP_FULL_DATABASE ADMINISTER RESOURCE MANAGER NOMDSYS ADMINISTER RESOURCE MANAGER NOSYSTEM ADMINISTER RESOURCE MANAGER YES

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

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 784


The DBA_SYS_PRIVS view also shows who has the ADMINISTER RESOURCEMANAGER privilege. That’s rather odd, because you can’t use the standard GRANTand REVOKE commands to manage it.

Creating the pending areaThe first step in the process of creating a new resource plan is to create a pendingarea. Do that with a call to DBMS_RSRC_MANAGER.CREATE_PENDING_AREA. Considerthis 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 newplan is defined as you want it to be, you can commit the pending changes.

Creating the planYou create a plan by making a call to the DBMS_RESOURCE_MANAGER package’sCREATE_PLAN procedure. All you need is a name for the plan and a commentdescribing the plan.

The examples in this chapter show you how to implement the scenario shown inFigure 30-3. In that scenario, there was a plan and a subplan. The following examplecreates these two plans. The top-level plan is named NORMAL, while the plan fordecision support users is named DECISION.

BEGINDBMS_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 plansto mean anything, you need to define consumer groups and then create plan direc-tives to allocate resources among those groups. Also, the link between the twoplans is defined using a plan directive. You’ll see how this is done later in thischapter.

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 785


Creating resource consumer groupsBefore you can create plan directives, you need to create consumer groups. Onlyafter you have your plans and consumer groups defined can you link the two usingdirectives.

To create a consumer group, you need a name and a comment. With thatinformation, you make a call to the CREATE_CONSUMER_GROUP procedure in theDBMS_RESOURCE_MANAGER package. Listing 30-1 shows the code needed tocreate the three consumer groups shown in Figure 30-3.

Listing 30-1: Creating consumer groups

BEGINDBMS_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 resourceplans.

Creating resource plan directivesWith the consumer groups and resource plans created, now you can createresource plan directives to allocate resources between them. You use theDBMS_RESOURCE_MANAGER package’s CREATE_PLAN_DIRECTIVE procedure todo this.

A directive always links a resource plan with either another resource plan or witha consumer group. Every plan has a certain percentage of database resources to

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 786


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

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

BEGINDBMS_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 thecustomer care group under the normal plan. The second call allocates 20 percent ofCPU time to the decision support group. Why a 70/20 split instead of the 80/20 splitcalled for in our scenario? The missing 10 percent is for a special group calledOTHER_GROUPS. Oracle requires that some resources be set aside for users andgroups for which you have not explicitly allocated resources.

To further subdivide the decision support group’s 20 percent, you execute the codeshown in Listing 30-3.

Listing 30-3: Subdividing resource allocation


‘DECISION’,

Continued

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 787


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. That’s because this 70/30 split appliesto 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 namedNORMAL. It could come from any plan, but NORMAL is where we held back the 10percent, so we’ll use this 10 percent.


‘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 automati-cally. You don’t have to create that group. You just have to create a plan directivethat allocates resources to it.

Submitting the pending areaAfter you have created the resource plan and the consumer groups, and after youhave created the plan directives necessary to apportion resources amongst thevarious groups, you are ready to make your changes permanent. This involves twosteps: validating the pending area and submitting the pending area.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 788


Validating the Pending AreaBefore you make the changes in the pending area permanent, you need to validatethem using the VALIDATE_PENDING_AREA procedure in the DBMS_RESOURCE_MANAGER package. The VALIDATE_PENDING_AREA procedure verifies that thefollowing statements are true:

✦ Consumer group names and plan names referenced by plan directivesreally 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 planby a running database instance.

✦ Your percentages don’t add up to more than 100 percent.

✦ You don’t have a plan and a resource group with the same name.

✦ Somewhere, you have a plan directive that allocates resources to a groupnamed OTHER_GROUPS. This is for users who haven’t specifically beenassigned to a group in the currently active plan.

The call to VALIDATE_PENDING_AREA is simple, and it looks like this:

BEGINDBMS_RESOURCE_MANAGER.VALIDATE_PENDING_AREA();

END;/

If validation fails, you will receive an error message. The following message showsthe error message that you will receive if you forget to allocate resources forOTHER_GROUPS:

ERROR at line 1:ORA-29382: validation of pending area failedORA-29377: consumer group OTHER_GROUPS is not part of top-plan NORMALORA-06512: at “SYS.DBMS_RMIN”, line 249ORA-06512: at “SYS.DBMS_RESOURCE_MANAGER”, line 254ORA-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 deletingresource plans, consumer groups, and plan directives. These procedures aredescribed later in this chapter.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 789


Submitting the Pending AreaIf you can successfully validate the pending area, then it’s time to submit yourchanges and make them permanent. The call to the SUBMIT_PENDING_AREAprocedure in the following code takes the changes from the pending area andputs them into effect:

BEGINDBMS_RESOURCE_MANAGER.SUBMIT_PENDING_AREA();

END;/

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

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

Placing users into groupsYou can place users only into groups that exist in the permanent area. If you have anew consumer group that you’ve created and it exists only in the pending area, youwill 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 switchprivileges on the group. The switch privilege allows a user to switch into a consu-mer group. It’s a strange-sounding name, but that’s what Oracle chose to use.

Granting Switch PrivilegesTo 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 thefollowing example grants the user SEAPARK access to the customer care consumergroup:

BEGINDBMS_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 beuseful if you have one user who runs two different types of applications. If you’vewritten the applications in-house, you can program the applications to automati-cally switch the user to the appropriate consumer group.

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 790


If you don’t want users changing their consumer group setting, then grant themswitch privileges only on one group, and make that group their initial group. Theywon’t be able to switch out of it.

Setting a User’s Initial Consumer GroupTo set a user’s initial consumer group, which is the one assigned when the user firstconnects to an instance, use the SET_INITIAL_CONSUMER_GROUP procedure. Thefollowing example sets the initial group for the SEAPARK user to be the customercare group:

BEGINDBMS_RESOURCE_MANAGER.SET_INITIAL_CONSUMER_GROUP (

‘SEAPARK’, ‘Customer Care’);END;/

Once logged on, users can switch themselves to other consumer groups, providingthey have been granted access to those groups, by using the DBMS_RESOURCE_MANAGER package’s SWITCH_CURRENT_CONSUMER_GROUP procedure. You can alsochange groups for a user by using the SWITCH_CURRENT_CONSUMER_GROUP_FOR_SESS and SWITCH_CURRENT_CONSUMER_GROUP_FOR_USER procedures. You’ll readmore about these procedures later in this chapter.

Setting the plan for an instanceFinally, you need to set your new plan as the current plan for the instance. Youcan do that in one of two ways. You can set the resource plan for an instancedynamically by using the ALTER SYSTEM command, or you can set a parameterin the instance’s parameter file.

You need the ALTER SYSTEM system privilege to issue the ALTER SYSTEMcommand.

The RESOURCE_MANAGER_PLAN parameter defines the current resource plan for aninstance. The following ALTER SYSTEM command sets it to the plan created in thischapter, which is named NORMAL:

ALTER SYSTEMSET resource_manager_plan = normal;

To set the plan used when you first start the instance, you can place a line like thefollowing in your instance’s initialization parameter file:

resource_manager_plan = normal

Note

Tip

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 791


Using the ALTER SYSTEM command, you can change resource plans at will. You canuse one plan during the day and a different plan at night. One plan might tilt thebalance of resources towards online users, while the other might favor decisionsupport users. The possibilities are endless. Oracle8i’s resource managementfeature gives you a great deal of flexibility in controlling how a database is used.

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

Using multilevel plansThe preceding example implemented the scenario described in Figure 30-3. Thisscenario contained two plans, each with one level of resource allocation. Figure30-2 illustrated an alternate scenario containing one plan and two levels of resourceallocation underneath that plan. The difference between the two approaches lies inhow excess CPU time for a plan is allocated. The code shown in Listing 30-4implements 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’,

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 792


‘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);

--Don’t 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 consumergroups are defined — the same as in the previous scenario. The major differenceis in how resources are allocated to those groups. The customer care group isallocated 70 percent of CPU resources at level 1. That leaves 30 percent for theother two groups. That 30 percent is allocated between the other groups using theCPU_P2 parameter. Level 1 users take priority over any level 2 users, so if the vicepresidents aren’t using all of their CPU allocation, the customer care users, not theother executives, will get first crack at it.

Making changesTo make changes to resource plans, consumer groups, and plan directives, youneed to follow this procedure:

1. Create a pending area.

2. Make whatever changes you need to make.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 793


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 inthe first place. The key difference is that here you are making modifications. TheDBMS_RESOURCE_MANAGER package contains a number of routines that can be usedto modify consumer groups and plan directives, and the interface to these routinesis very similar to the various create routines that you’ve read about so far. Forexample, Listing 30-5 shows two plan directives being modified. Ten percent istaken from the customer care group and given over to the special group namedOTHER_GROUPS.

Listing 30-5: Modifying resource plan directives

SQL> EXECUTE DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA();


SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.UPDATE_PLAN_DIRECTIVE -> (‘NORMAL’,’CUSTOMER CARE’,NEW_CPU_P1=>60);


SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.UPDATE_PLAN_DIRECTIVE -> (‘NORMAL’,’OTHER_GROUPS’,NEW_CPU_P1=>20);


SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.VALIDATE_PENDING_AREA;


SQL> SQL> EXECUTE DBMS_RESOURCE_MANAGER.SUBMIT_PENDING_AREA;


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

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 794


The DBMS_RESOURCE_MANAGER ReferenceThe DBMS_RESOURCE_MANAGER package has entry points for creating, updating, anddeleting resource plans, plan directives, and consumer groups. You’ve seen most ofthe create procedures in this chapter’s examples. Each of those create procedureshas corresponding update and delete procedures. All of these procedures aredescribed in this section.

How to reference a procedureThe procedures described in this section are all part of the DBMS_RESOURCE_MANAGER package. For simplicity, the package name has been omitted from theprocedure definitions. Whenever you use a procedure, you must preface it withthe 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 useof a period for that purpose is standard within PL/SQL.

Optional parametersMany of the procedures in the DBMS_RESOURCE_MANAGER package have optionalparameters in their interfaces. An optional parameter is one that you don’t have topass when you call the procedure. The nature of these procedures is such that it’squite common to omit a number of parameters, so passing parameters using namednotation rather than position notation is often convenient.

You use positional notation to pass parameters by position, as shown in thefollowing 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 correspondsto the first formal parameter defined for the procedure, the second parameter thatis listed corresponds to the second formal parameter, and so forth. The 80 in thisexample corresponds to the CPU_P2 parameter. The two NULL parameters corre-spond to the COMMENT and CPU_P1 parameters. Nulls need to be passed in asplaceholders here, to make the value of 80 correspond with the fifth formalparameter, which is CPU_P2.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 795


An easier way to skip parameters is to use named notation. By naming each param-eter explicitly, you relieve yourself of the burden of passing nulls for parametersthat 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 andthen 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 hasthe same effect as passing in nulls.

With named notation, your parameters don’t need to be passed in any particularorder. With positional notation, the order determines the correspondencebetween the actual and formal parameters.

The pending areaOracle requires that resource plan changes be made in the pending area, not to thelive plan being used for the instance. Only after the changes have been validatedcan they be put into effect.

Creating the Pending AreaTo 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 AreaAfter you’ve made changes to resource plans, consumer groups, and resource plandirectives, 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 problemswith the changes that you’ve made in the pending area, you will receive an errormessage. Fix the problem identified by the error message, and try the validationagain. If you have multiple problems, you may have to iterate through this processseveral times.

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 796


Submitting the Pending AreaTo submit the changes in the pending area, use the SUBMIT_PENDING_AREAprocedure:

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 won’t allow thechanges to be submitted if a validation error occurs.

Erasing the Pending AreaIf you are in the middle of making changes and decide that you don’t want to makethem, you can erase the pending area by calling the CLEAR_PENDING_AREAprocedure:

CLEAR_PENDING_AREA;

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

Resource plansResource plans describe how a database is to allocate resources. The DBMS_RESOURCE_MANAGER package contains procedures for creating, updating, anddeleting these plans.

Creating Resource PlansUse the CREATE_RESOURCE_PLAN procedure to create a resource plan:

CREATE_PLAN (plan IN VARCHAR2, comment IN VARCHAR2, cpu_mth 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 30characters long.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 797


✦ comment— A comment describing the plan. This may be up to 2,000characters 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 themaximum number of sessions. The default is ‘MAX_ACTIVE_SESS_ABSOLUTE’.

✦ parallel_degree_limit_mth— The method to use in limiting the degree ofparallelism. This defaults to ‘PARALLEL_DEGREE_LIMIT_ABSOLUTE’, which iscurrently the only supported method.

Modifying Resource PlansUse the UPDATE_RESOURCE_PLAN procedure to update a resource plan, as follows:

UPDATE_PLAN (plan IN VARCHAR2, new_comment IN VARCHAR2 DEFAULT NULL, new_cpu_mth IN VARCHAR2 DEFAULT NULL, new_max_active_sess_target_mth IN VARCHAR2 DEFAULT NULL,new_parallel_degree_limit_mth IN VARCHAR2 DEFAULT 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 parameterswhose values you want to change. To change a plan’s comment, for example,identify the plan by using the PLAN parameter and pass the new comment in theCOMMENT parameter.

You can’t change a plan’s name. If you don’t like the name, you must delete andre-create the plan.

Deleting Resource PlansUse 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 youwant to delete. If you want to delete not only a resource plan but also any plandirectives, consumer groups, and subplans associated with the plan, you can usethe following DELETE_RESOURCE_PLAN_CASCADE procedure:

DELETE_PLAN_CASCADE (plan IN VARCHAR2);

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 798


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 allthe consumer groups and subplans that fall under the plan that you are deleting.

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

Creating Plan DirectivesUse the CREATE_PLAN_DIRECTIVE procedure to create a resource plan directive.See Listing 30-6.

Listing 30-6: Syntax for the CREATE_PLAN_DIRECTIVEprocedure

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

The following list describes the parameters for this procedure:

✦ plan— The name of the resource plan to which you want the directive to beattached.

✦ group_or_subplan— The name of a group or another plan. This directivespecifies the amount of resources to be allocated to the group or plan thatyou name.

✦ comment— A comment about this directive.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 799


✦ cpu_p1— A value from 0–100 specifying the percentage of CPU to allocate tothe named group or plan. This is a priority 1 allocation, with 1 being thehighest priority.

✦ cpu_p2— A value from 0–100 specifying the percentage of CPU to allocate tothe named group or plan. This is a priority 2 allocation.







✦ max_active_sess_target_p1— A target for the maximum number ofsessions. This parameter is currently ignored. Oracle plans to add thisfunctionality sometime in the future.

✦ parallel_degree_limit_p1— A limit on the degree of parallelism thatusers who fall under this particular directive can use.

Modifying Plan DirectivesUse the UPDATE_PLAN_DIRECTIVE procedure to modify the settings for an existingdirective. See Listing 30-7.

Listing 30-7: Syntax for the UPDATE_PLAN_DIRECTIVEprocedure

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

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 800


cpu_p7 IN NUMBER DEFAULT NULL, cpu_p8 IN NUMBER DEFAULT NULL, max_active_sess_target_p1 IN NUMBER DEFAULT NULL, parallel_degree_limit_p1 IN NUMBER DEFAULT NULL);

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

Deleting Plan DirectivesUse 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 thatyou want to delete.

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

Creating Consumer GroupsUse the CREATE_CONSUMER_GROUP procedure to create a new consumer group, asfollows:

CREATE_CONSUMER_GROUP ( consumer_group IN VARCHAR2,comment IN VARCHAR2, cpu_mth IN VARCHAR2 DEFAULT ‘ROUND-ROBIN’);


✦ 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 consumergroup. The default method is ‘ROUND-ROBIN’, which is also the only methodcurrently supported.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 801


Modifying Consumer GroupsUse the UPDATE_CONSUMER_GROUP procedure to modify the settings for a consumergroup, 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 theconsumer_group parameter, then pass in new values for the other parametersthat you want to change.

Deleting Consumer GroupsUse the DELETE_CONSUMER_GROUP procedure to delete a consumer group, asfollows:

DELETE_CONSUMER_GROUP (consumer_group IN VARCHAR2);

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

Consumer group assignmentsThe DBMS_RESOURCE_MANAGER package implements three procedures that allowyou to assign a user to a consumer group. You can set a user’s initial groupassignment, and you can switch users to new groups while they are connectedto the database.

Setting a User’s Initial Consumer GroupTo set the consumer group to which a user is first assigned after connecting to thedatabase, use the SET_INITIAL_CONSUMER_GROUP procedure, as follows:

SET_INITIAL_CONSUMER_GROUP (user IN VARCHAR2, consumer_group IN VARCHAR2);


✦ user— The name of the user

✦ consumer_group— The name of the consumer group to which you want toassign the user

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 802


For a user to be part of a consumer group, that user must be granted switchprivileges 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 GroupYou can switch an active session to another consumer group at any time by usingthe 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);


✦ 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 wantto switch

✦ consumer_group— The new consumer group assignment for that session

Together, the session_id and session_serial parameters identify the sessionthat you want to switch. You can get a list of active sessions, including IDs andserial numbers, by querying the v$session view.

Switching a User to Another GroupYou can switch an active user to another consumer group at any time by using theSWITCH_CONSUMER_GROUP_FOR_USER procedure, as follows:

SWITCH_CONSUMER_GROUP_FOR_USER (user IN VARCHAR2, consumer_group IN VARCHAR2);


✦ 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, allcurrent sessions for the specified user will be switched.

The SWITCH_CONSUMER_GROUP_FOR_USER procedure doesn’t change the user’sinitial setting. The next time the user connects, the user will be assigned to thegroup specified as his or her initial group. To change the initial group, use theSET_INITIAL_CONSUMER_GROUP procedure.

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 803


The DBMS_RESOURCE_MANAGER_PRIVSReference

The DBMS_RESOURCE_MANAGER_PRIVS package contains four procedures that allowyou 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 allowedto create and change resource plans for a database. You can also grant users theprivilege of changing their own consumer group assignments.

The procedures described in this section are all part of the DBMS_RESOURCE_MANAGER_PRIVS package. Remember that when referencing a procedure, youmust 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 privilegeThe ADMINISTER_RESOURCE_MANAGER privilege gives you the ability to create andmanage resource plans for a database. It also gives you the ability to place usersinto consumer groups. To grant and revoke this privilege, you must hold it with theadmin option. The default DBA role that you get when you create a database givesyou this.

Granting the ADMINISTER_RESOURCE_MANAGER PrivilegeYou can use the GRANT_SYSTEM_PRIVILEGE procedure to grant theADMINISTER_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);


✦ grantee_name— The name of the user or role to which you want to grant theprivilege.

✦ privilege_name— The name of the privilege to grant. Currently, the onlyprivilege that you can grant is ADMINISTER_RESOURCE_MANAGER.

✦ admin_option— A TRUE condition allows the grantee to grant this privilegeto other users. A FALSE condition does not.

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 804


Revoking ADMINISTER_RESOURCE_MANAGERYou 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’);


✦ grantee_name— The name of the user or role from which you want to revokea privilege.

✦ privilege_name— The name of the privilege to revoke. Currently, this mustbe ADMINISTER_RESOURCE_MANAGER.

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

To restrict a user to just one consumer group, grant switch privileges to the user ofthe group and make the group the user’s default consumer group.

Granting Switch PrivilegesTo grant switch privileges to a user or to a role, use theGRANT_SWITCH_CONSUMER_GROUP procedure, as follows:

GRANT_SWITCH_CONSUMER_GROUP (grantee_name IN VARCHAR2,consumer_group IN VARCHAR2,grant_option IN BOOLEAN);


✦ grantee_name— The name of the user or role to which you want to grant theprivilege.

✦ consumer_group— The name of a consumer group. This is the group towhich the privilege applies.

Note

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 805


✦ 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. ATRUE condition allows the user to further grant the identical switch privilegeto other users. A FALSE condition does not.

Revoking Switch PrivilegesTo 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);


✦ grantee_name— The name of the user or role from which you want to revokethe privilege

✦ consumer_group— The name of a consumer group

Resource Management and theData Dictionary

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

Table 30-1Resource Manager Data Dictionary Views

View Name Description

DBA_RSRC_CONSUMER_GROUP_PRIVS Shows you the switch privileges that have been granted to users and roles for thevarious consumer groups in a database.

DBA_RSRC_CONSUMER_GROUPS Returns information about all theconsumer groups in a database.

DBA_RSRC_MANAGER_SYSTEM_PRIVS Tells you who has been granted theADMINISTER_RESOURCE_MANAGERprivilege.

DBA_RSRC_PLAN_DIRECTIVES Returns information about all resourceplan directives.

DBA_RSRC_PLANS Returns information about all resourceplans.

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 806


View Name Description

DBA_USERS Returns information about all users in the database. The INITIAL_RSRC_CONSUMER_GROUP column shows youthe initial consumer group assignment foreach user.

USER_RSRC_CONSUMER_GROUP_PRIVS Tells you to which consumer groups youhave access.

USER_RSRC_MANAGER_SYSTEM_PRIVS Tells you whether you have been grantedthe ADMINISTER_RESOURCE_MANAGERprivilege.

V$PARALLEL_DEGREE_LIMIT_MTH Returns information about availableparallel degree limit methods.

V$RSRC_CONSUMER_GROUP Returns information about all currentlyactive resource consumer groups.

V$RSRC_CONSUMER_GROUP_CPU_MTH Returns information about available CPUallocation methods for consumer groups.

V$RSRC_PLAN Returns the names of all currently activeresource plans.

V$RSRC_PLAN_CPU_MTH Returns information about availableresource allocation methods.

V$SESSION Returns information about all activedatabase sessions. The RESOURCE_CONSUMER_GROUP column shows youthe consumer group to which eachsession currently belongs.

As with most data dictionary views, the column names are fairly self-explanatory. Inthe following example, the DBA_RSRC_CONSUMER_GROUP_PRIVS view is queried tosee a list of switch privileges held by the users:

SQL> SELECT *2 FROM dba_rsrc_consumer_group_privs3 ORDER BY grantee, granted_group;

GRANTEE GRANTED_GROUP GRANT INI--------------- ---------------------- ----- ---PUBLIC DEFAULT_CONSUMER_GROUP YES YESPUBLIC LOW_GROUP NO NOSEAPARK CUSTOMER CARE NO YESSYSTEM SYS_GROUP NO YES

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

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 807


SummaryIn this chapter, you learned:

✦ Resource management is a new Oracle feature that allows you to allocate CPUresources among users and groups of users.

✦ Resource management requires that users be divided into groups calledconsumer groups. A resource plan is then put into effect for the database.That plan contains plan directives that specify how CPU resources are to beallocated among the various consumer groups. For added versatility, subplansmay also be used.

✦ Resource plan changes are always made in a pending area, which you mustfirst create using DBMS_RESOURCE_MANAGER.CREATE_PENDING_AREA. Aftercompleting your changes, validate them by calling DBMS_RESOURCE_MANAGER.VALIDATE_PENDING_AREA. If validation succeeds, submit the changes bycalling 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 theADMINISTER_RESOURCE_MANAGER privilege. This isn’t quite the same as asystem privilege, and it’s granted using the DBMS_RESOURCE_MANAGER_PRIVS.GRANT_SYSTEM_PRIVILEGE procedure.

✦ ✦ ✦

4623-6 ch30.f.qc 1/28/00 12:35 PM Page 808

Documents

Chapter 30