Using the IBM-supplied governor exit routine

The governor exit routine supplied by IBM controls how many rows a user can retrieve from the database. The governor exit routine is shipped with two predefined values for the number of rows:

A row prompt value warns users when the number of rows retrieved reaches 25,000, at which time the user sees the message shown in Figure 212.
Figure 212. Message displayed when a resource limit is approaching. The n symbol in the figure represents an NLID from Table 1
```
DSQUn00 QMF governor prompt:
   Command has fetched 25,000 rows of data.
 
==> To continue QMF command press the "ENTER" key.
==> To cancel QMF command type "CANCEL" then press the "ENTER" key
==> To turn off prompting type "NOPROMPT" then press the "ENTER" key 
```
A row limit value cancels data retrieval when 100 ,000 rows have been retrieved, if the user presses the Enter key in response to the message in Figure 212. When the IBM-supplied governor cancels data retrieval, the user sees the message shown in Figure 213.
Figure 213. Message displayed when a resource limit is exceeded
```
Row limit exceeded!  Your command canceled by QMF governor.
```

When running a procedure, you might get a message that your procedure was canceled, rather than the message in Figure 213. For example, if your procedure contains a command that requires the report to complete (such as ERASE), you receive the message shown in Figure 214.

Figure 214. Message displayed when a procedure is canceled

Procedure canceled.

Users using the SYSTEM profile, are already set up to use these default values of 25, 000 and 100, 000.

If you want to define your own limits for when the user is warned and when data retrieval is canceled, see Defining your own resource limits.

Activating the default limits

Follow this procedure to set up the governor exit routine to warn a user when the number of rows retrieved from the database reaches 25, 000 and to cancel the QMF activity when the number of rows retrieved reaches 100 ,000:

Run the query shown in below from the SQL query panel.
Figure 215. Activating default values for the IBM-supplied governor
```
UPDATE Q.RESOURCE_VIEW
SET INTVAL=0
WHERE RESOURCE_OPTION='SCOPE' AND
      RESOURCE_GROUP='SYSTEM'
```
Set a value of SYSTEM for the RESOURCE__GROUP field of the user's profile. For example, the UPDATE statements in Figure 216 activate default values for user JONES (using English QMF) and user SCHMIDT (using German QMF).
Important: Always specify a value for the TRANSLATION column, or you might change more rows in Q.PROFILES than you intend.

Figure 216. Updating a user's resource group

Base QMF (English)

German NLF

UPDATE Q.PROFILES

UPDATE Q.PROFILES

SET RESOURCE__GROUP = 'SYSTEM'

SET RESOURCE__GROUP = 'SYSTEM'

WHERE CREATOR='JONES' AND

WHERE CREATOR='SCHMIDT' AND

TRANSLATION='ENGLISH'

TRANSLATION='DEUTSCH'
Instruct users to reconnect to the database to activate the new values.

If you want to define row limits other than the defaults of 25, 000 and 100, 000, read How a governor exit routine controls resources. Then see the procedure in Defining your own resource limits.

How a governor exit routine controls resources

The governor uses two types of information to control resources.

Information about the resource limits you set for a user, defined in a resource control table called Q.RESOURCE_TABLE.
Information about the state of the user's session, which tells the governor how close the user's activity is coming to the resource limits defined for the resource group the user is in. This information is passed to the governor exit routine in the IBM-supplied control blocks DXEGOVA and DXEXCBA.

How the governor knows what the resource limits are

Each row of the IBM-supplied Q.RESOURCE_TABLE contains:

The name of a resource group (RESOURCE_GROUP), which characterizes one or more users whose activities you want to govern in the same manner.
The name of the resource (RESOURCE_OPTION) you want to limit for the group of users named in RESOURCE_GROUP.
Values (INTVAL, FLOATVAL, or CHARVAL) that define the limit for the resource option. Resource options can have integer values, floating-point values, or character values.

Table 78 shows the structure of the Q.RESOURCE_TABLE as it is shipped by IBM. Q.RESOURCE_TABLE has the index Q.RESOURCE_INDEX. Keyed columns are RESOURCE_GROUP and RESOURCE_OPTION.

The Q.RESOURCE_TABLE is shipped by IBM with a predefined resource group called SYSTEM. The SYSTEM resource group has three predefined resource options for CICS. Use the CHARVAL column to indicate the limits defined in each row, as shown.

Table 78. Default resource group and options for the IBM-supplied governor exit common to all
GROUP	OPTION	INTVAL	FLOATVAL	CHARVAL
SYSTEM	SCOPE	-	-	Indicate whether governor is active
SYSTEM	ROWLIMIT	100,000	-	Cancel after fetching 100,000 rows
SYSTEM	ROWPROMPT	25,000	-	Prompt user after fetching 25,000 rows

SCOPE = 0: Activates governing for a particular resource group.
Any non-zero value for SCOPE, including a null, deactivates governing for the resource group.
ROWLIMIT = 100,000: If the user decides to continue when warned, the governor exit routine cancels data retrieval activities after 100, 000 rows are retrieved. (Retrieval is for FETCH only.) ROWLIMIT is dependent on the buffer size; therefore, more than 100, 000 rows can be retrieved if the buffer holds a number of rows not divisible by 100, 000.
ROWPROMPT = 25,000: Warns the user when 25, 000 database rows have been retrieved.

IBM also supplies a view of this table, called Q.RESOURCE_VIEW, that includes all five columns of Q.RESOURCE_TABLE. Each time QMF calls the governor exit routine, QMF passes to the routine the resource control information stored in Q.RESOURCE_VIEW. The governor exit routine uses this resource information to help determine when the user reaches a resource limit.

How the governor knows when you reach a resource limit

On a call to the governor exit routine, QMF queries Q.RESOURCE_VIEW, which shows what resource limits are defined in the resource control table for the resource group to which the user belongs. To determine the resource group, QMF checks the value of the RESOURCE_GROUP field of the user's row in the Q.PROFILES table and checks Q.RESOURCE_VIEW for a matching value.

QMF uses two control blocks, DXEGOVA and DXEXCBA, to pass information to the governor exit routine. The DXEGOVA control block contains information from Q.RESOURCE_VIEW about the limits you set for each user. The DXEXCBA control block contains information about the activities the user is performing in the current QMF session, which tells the governor how close the user is coming to the resource limits.

QMF calls the governor exit routine at a number of different points within the QMF session, as shown in Figure 217.

Figure 217. How a governor exit routine works with QMF for VSE

QMF Main Phase DSQQMF points to QMF Edit Exit Phase DSQUECIC via Call. QMF
Edit Exit Phase DSQUECIC which consists of IBM-supplied control programs and
a User edit exit program points to QMF Main Phase via Return.

These calls are called function calls. For more information about function calls, see Points at which QMF calls the governor.

What happens when you reach a resource limit

When the resource control information QMF passes to the governor exit routine indicates that a resource limit has been reached, the IBM-supplied governor exit routine calls the QMF cancellation service to cancel the QMF activity the user tried to perform.

If you use the default limits for number of rows, the IBM-supplied governor exit routine also displays a warning before canceling the activity, as shown in Figure 213. See Defining your own resource limits for how to activate this warning if you are not using the default values for the number of rows retrieved.

The IBM-supplied governor exit routine resets its count of the number of rows upon returning control to QMF, so that the number of rows is not cumulative across calls to the governor.

Defining your own resource limits

This section explains how to create a new resource group, for which the resource is the number of rows retrieved from the database. If you want to define resource limits other than the number of rows, you need to modify the IBM-supplied governor exit routine or write an exit routine of your own. See Modifying the IBM-supplied governor exit routine or writing your own for more information on the facilities you can use.

Use the following procedure to add a resource group to the resource control table. This procedure adds a resource group named GROUP1, where the governor prompts a user in GROUP1 when the number of rows reaches 10, 000, and cancels the user's activity when the number of rows reaches 10,000; it cancels the user's activity when the number of rows reaches 15 ,000. The procedure also shows an example of how to add a user to a resource group.

Run the query below to set the number of rows at which the user is warned of the approaching resource limit.
If you do not want to warn users when they are approaching their limit for the number of rows, skip to step 2
Figure 218. Activating prompting for row limit
```
INSERT INTO Q.RESOURCE__VIEW (RESOURCE__GROUP,RESOURCE__OPTION,INTVAL)
    VALUES('GROUP1','ROWPROMPT',10000)
```

Run the query in Figure 219 to set the number of rows at which the governor cancels the user's activity.
Figure 219. Activating cancellation of activities when user reaches row limit
```
INSERT INTO Q.RESOURCE__VIEW (RESOURCE__GROUP,RESOURCE__OPTION,INTVAL)
    VALUES('GROUP1','ROWLIMIT',15000)
```
Run the query shown in below to turn on governing for the GROUP1 resource group. SCOPE is a resource option that activates or deactivates governing. Each resource group in the Q.RESOURCE__TABLE must have a RESOURCE__OPTION called SCOPE, and SCOPE must have a corresponding INTVAL of zero, or the resource group is not governed. Set INTVAL to 1 to deactivate governing.
Figure 220. Turning on the governor for a particular resource group
```
INSERT INTO Q.RESOURCE__VIEW (RESOURCE__GROUP,RESOURCE__OPTION,INTVAL)
    VALUES('GROUP1','SCOPE',0)
```
Run a query similar to the one below to add user JONES to the GROUP1 resource group in the English QMF environment.
Figure 221. Updating a user's resource group
```
UPDATE Q.PROFILES
  SET RESOURCE__GROUP='GROUP1'
  WHERE CREATOR='JONES' AND
  TRANSLATION='ENGLISH'
```
If you are using an NLF: Use a similar query to update a user's profile in an NLF environment, but use a TRANSLATION value from Table 1.
Instruct the user whose profile you updated to end the current QMF session and start another to activate the new values.

Creating your own resource control table

You can create your own table or rename the Q.RESOURCE_TABLE. You can also include additional columns in the table you create, if Q.RESOURCE_VIEW is the view defined in this table, and if the table includes all of the columns shown in Table 79.

Figure 222 shows an example of SQL statements you might use to create a table called MY_RESOURCES. Substitute your own table, column, and table space names in the query. Before creating a new table, ensure you erase the Q.RESOURCE_TABLE from the database, because Q.RESOURCE_VIEW is defined in this table:

DROP TABLE Q.RESOURCE_TABLE

Dropping the Q.RESOURCE__TABLE also drops Q.RESOURCE_VIEW from the database, so you need to recreate both the table and the view, as shown in Figure 222 and Figure 223. Substitute your own dbspace name for SPACE1.

Figure 222. Creating a resource control table or renaming Q.RESOURCE_TABLE

CREATE TABLE MY_RESOURCES
  (GROUP_NAME    CHAR(16) NOT NULL,
   CONSTRAINT    CHAR(16) NOT NULL,
   INTEGER       INTEGER,
   FLOAT_VALUE   FLOAT,
   CHARACTER     VARCHAR(80))
IN DBSPACE1

Always recreate Q.RESOURCE_VIEW if you decide to use a table other than Q.RESOURCE_TABLE or decide to give Q.RESOURCE__TABLE a different name, because QMF queries the view, not the table, to obtain resource control information to pass to the governor exit routine.

Figure 223 shows how to redefine Q.RESOURCE_VIEW as a view on the new table, MY_RESOURCES. Substitute your own table and column names for those in the figure.

Figure 223. Redefining the Q.RESOURCE_VIEW

CREATE VIEW Q.RESOURCE_VIEW
  (RESOURCE_GROUP, RESOURCE_OPTION, INTVAL, FLOATVAL, CHARVAL)
  AS SELECT GROUPNAME, CONSTRAINT, INTEGER, FLOAT_VALUE, CHARACTER
  FROM MY_RESOURCES

Table 79. Structure of the Q.RESOURCE_TABLE table
Column name	Data type	Length (bytes)	Nulls allowed?	Function/values
RESOURCE__GROUP	CHAR	16	No	Contains the name of the resource group. Update the RESOURCE__GROUP field of the user's row in Q.PROFILES to activate governing for that user.
RESOURCE__OPTION	CHAR	16	No	Your own name for a resource you want to monitor.
INTVAL	INTEGER		Yes	Reflects resource limit for resource options that have integer values. For example, number of rows retrieved from the database is a resource that has an integer value.
FLOATVAL	FLOAT		Yes	Reflects resource limit for resource options that have floating point values. FLOATVAL is null for the IBM-supplied governor.
CHARVAL	VARCHAR	80	Yes	Reflects resource limit for resource options that have character values. For example, you might establish a DAY_OF_WEEK resource option and assign MONDAY to CHARVAL so that QMF users can log on to QMF only on Mondays. CHARVAL is used as a comment column in the IBM-supplied governor.

[ Previous Page | Next Page | Contents | Index ]