-ALTER GROUPBUFFERPOOL (Db2)

Abbreviation

-ALT GBPOOL

Environment

This command can be issued from a z/OS® console, a DSN session under TSO, a DB2I panel (DB2 COMMANDS), an IMS or CICS® terminal, or a program using the instrumentation facility interface (IFI).

Data sharing scope: Group

Authorization

Db2 commands that are issued from a logged-on z/OS console or TSO SDSF can be checked by Db2 authorization using primary and secondary authorization IDs. A logged-on z/OS user ID must be defined in RACF or a similar security server.

Option descriptions

(gbpname)

Specifies the Db2 group buffer pool to alter.

• 4-KB group buffer pools are named GBP0 through GBP49
• 8-KB group buffer pools are named GBP8K0 through GBP8K9
• 16-KB group buffer pools are named GBP16K0 through GBP16K9
• 32-KB group buffer pools are named GBP32K through GBP32K9

(structure-name)

Specifies the coupling facility structure for the group buffer pool. The coupling facility structure name has the format, groupname_gbpname.

groupname is the Db2 data sharing group name and the underscore (_) separates groupname and gbpname.

GBPCACHE

Specifies whether gbpname is to be used for both caching data and cross-invalidation, or just for cross-invalidation.

(YES)

Indicates that gbpname is used for caching data and cross-invalidation.

Any no-data-caching attribute that is specified at either the page set or group buffer pool level takes precedence over a caching specification. The following table illustrates the precedence of a no-data-caching specification.

Table 1. Precedence of a no-data-caching specification

Group buffer pool specification	Page set specification	Attribute that takes precedence
GBPCACHE(NO)	GBPCACHE CHANGED GBPCACHE ALL	GBPCACHE(NO)
GBPCACHE(YES)	GBPCACHE NONE	GBPCACHE NONE

(NO)

Indicates that gbpname is used only for cross-invalidation. This group buffer pool contains no data entries. The GBPCACHE option of table spaces or index spaces that use this group buffer pool is ignored.

AUTOREC

Specifies whether automatic recovery by Db2 takes place when a structure failure occurs or when the connectivity of all members of the group to the group buffer pool is lost.

(YES)

Enables Db2 to automatically recover page sets and partitions that have a status of group buffer pool RECOVER pending (GRECP) and that have pages on the logical page list.

(NO)

Disables automatic recovery. Issue a START DATABASE command to recover page sets and partitions that have a status of GRECP or that have pages on the logical page list.

RATIO (ratio)

Changes the ratio of the number of directory entries to the number of data pages in the group buffer pool; that is, how many directory entries exist for each data page.

ratio can be a decimal number from 1.0 to 1024, inclusive. Any digits after the first decimal place are ignored; for example, 5.67 is treated as 5.6. If ratio is greater than 25, any digits after the decimal point are ignored; for example, 25.98 is treated as 25. A group buffer pool is defined with a default ratio of 10. (Group buffer pools that were defined before APAR PH13045 was applied in Db2 12 were defined with a default ratio of 5.)

The actual number of directory entries and data pages that are allocated depends on the size of the coupling facility structure, which is specified in the coupling facility policy definitions (CFRM policy).

CLASST (class-threshold1,class-threshold2)

Changes the threshold at which data in the class castout queue is cast out to disk.

class-threshold1 is a percentage of the number of data entries and can be an integer between 0 and 90, inclusive. The default class-threshold1 value when a group buffer pool is defined is 5.

For example, CLASST(10,0) starts class castout when the number of pages in that class equals 10% of the group buffer pool page capacity.

class-threshold2 is an absolute number of pages. You can use class-threshold2 when you need a relatively low threshold value for a large group buffer pool but class-threshold1 does not provide the necessary granularity between the class-threshold1 values of 0 and 1. class-threshold2 can be an integer between 0 and 32767, inclusive. The default class-threshold2 value when a group buffer pool is defined is 0.

For example, CLASST(0,2500) starts class castout when the number of pages in that class reaches 2500.

The value of class-threshold2 is used only when class-threshold1 is 0. If the value of class-threshold1 is non-zero, the value of class-threshold2 is ignored. If both class-threshold1 and class-threshold2 are 0, the class-threshold1 value of 0 is used.

GBPOOLT (integer)

Changes the threshold at which data in the group buffer pool is cast out to disk.

integer is expressed as a percentage of the number of data entries and can range 0 - 90. The default value is when group buffer pool is defined is 30.

For example, GBPOOLT(55) casts out data if the number of pages in the group buffer pool equals 55% of the group buffer pool page capacity.

GBPCHKPT (integer)

Changes the time interval, in minutes, between successive checkpoints of the group buffer pool. integer can range from 1 to 999999. The default value when a group buffer pool is defined is 4 minutes.

The more frequently checkpoints are taken, the less time it takes to recover the group buffer pool if the coupling facility fails.

Usage notes

Default values of unaltered group buffer pools

When you issue an ALTER GROUPBUFFERPOOL command, it does not change any option that you did not explicitly specify. That is, the default is to leave the values unchanged.

An unaltered group buffer pool has the values shown in the following table for the attributes that you can change with the ALTER GROUPBUFFERPOOL command.

Option	Value
GBPCACHE	YES
RATIO	10
CLASST	5,0
GBPOOLT	30 (%)
GBPCHKPT	4 (minutes)

When new values take effect

When you issue the ALTER GROUPBUFFERPOOL command, some option specifications become effective only at the next allocation of the group buffer pool. The following table lists each option, when the new value takes effect, and if the option is applicable for a group buffer pool that is specified as GBPCACHE(NO).

Keyword	New value takes effect	Applicable if GBPCACHE(NO)?
GBPCACHE	at next allocation	N/A
AUTOREC	immediately	No
RATIO	at next allocation 2	No 3
CLASST	immediately	No 3
GBPOOLT	immediately	No 3
GBPCHKPT	immediately	No 3

Notes:

1. You can use the z/OS command SETXCF START,REBUILD to have the change take effect if the group buffer pool is not duplexed. If the group buffer pool is duplexed and you want to change to GBPCACHE(NO), first go back to simplex mode and rebuild. GBPCACHE(NO) is not allowed for duplexed group buffer pools.
2. You can use the z/OS command SETXCF START,REBUILD to have the change take effect if the group buffer pool is not duplexed. If the group buffer pool is duplexed, first go back to simplex mode and rebuild; then optionally go back to duplex mode. If a group buffer pool is duplexed, both instances of that duplexed group buffer pool use the same RATIO value.
3. Db2 issues message DSNB761 when you specify this option for a GBPCACHE(NO) group buffer pool. These settings only take effect after the GBPCACHE attribute has been changed to YES.

Trace information for data sharing members

When this command with group scope is issued in a Db2 data sharing member, it also runs on all other active members. IFICID 090 trace records for other group members can show that the same command was issued by the SYSOPR authorization ID from the 016.TLPKN5F correlation ID, in addition to the trace records from the member where the original command was issued. See Command scope in Db2 data sharing.