DEFINE BUFFPOOL (define a buffer pool) on z/OS

Use the MQSC command DEFINE BUFFPOOL to define a buffer pool that is used for holding messages in main storage.

Using MQSC commands on z/OS

For information on how you use MQSC commands on z/OS®, see Sources from which you can issue MQSC and PCF commands on IBM® MQ for z/OS.

You can issue this command from sources 1. For an explanation of the source symbols, see Sources from which you can issue MQSC and PCF commands on IBM MQ for z/OS.

Syntax diagram for DEFINE BUFFPOOL
Usage notes
Parameter descriptions for DEFINE BUFFPOOL

Syntax diagram for DEFINE BUFFPOOL

Synonym: DEF BP

DEFINE BUFFPOOL

Usage notes

Specify DEFINE BUFFPOOL commands in a data set identified by the CSQINP1 DD concatenation in the queue manager started task procedure.
Use the DISPLAY USAGE TYPE(PAGESET) command to display buffer pool information (see DISPLAY USAGE (display usage information) on z/OS ).
Use the ALTER BUFPOOL command to dynamically change the settings of a predefined buffer pool (see ALTER BUFFPOOL (alter buffer pool settings) on z/OS ).

Parameter descriptions for DEFINE BUFFPOOL

If more than one DEFINE BUFFPOOL command is issued for the same buffer pool, only the last one is processed.

(buf-pool-id)

Buffer pool identifier.

This parameter is an integer in the range zero through 99.

BUFFERS( integer )

This parameter is required and is the number of 4096 byte buffers to be used in this buffer pool.

If the value of the LOCATION parameter is BELOW, the minimum value of buffers is 100 and the maximum value is 500,000. If the value of the LOCATION parameter is ABOVE, then valid values are in the range of 100 to 999999999 (nine nines). The storage used for buffers in a buffer pool with LOCATION ABOVE is obtained in multiples of 4MB. Therefore specifying a BUFFERS value which is a multiple of 1024 will make the most efficient use of storage.

When defining a buffer pool care should be taken to ensure that there is sufficient storage available for it either above or below the bar. For more information, see Address space storage.

LOCATION(LOC)(BELOW or ABOVE)

LOCATION and LOC are synonyms and either, but not both, can be used.

The LOCATION or LOC parameter specifies where the memory used by the specified buffer pool is located.

Attention: From IBM MQ 9.1, LOCATION(BELOW) is deprecated and you should use LOCATION(ABOVE) only.

This memory location can be either ABOVE (64 bit) or BELOW (31 bit) the bar. Valid values for this parameter are BELOW or ABOVE, with BELOW being the default.

For more information, see Address space storage.

PAGECLAS( 4KB or FIXED4KB )

Optional parameter that describes the type of virtual storage pages used for backing the buffers in the buffer pool.

This attribute applies to all buffers in the buffer pool, including any that are added later as a result of using the ALTER BUFFPOOL command. The default value is 4KB, which means that pageable 4KB pages are used to back the buffers in the pool.

4KB is the only valid value if the buffer pool has its LOCATION attribute set to BELOW. If the buffer pool has its LOCATION attribute set to ABOVE, it is also possible to specify FIXED4KB. This means that fixed 4KB pages, which are permanently in real storage and are never paged out to auxiliary storage, are used to back the buffers in the buffer pool.

The PAGECLAS attribute of a buffer pool can be altered at any time. However, the alteration only takes place when the buffer pool switches location from above the bar, to below the bar, or the other way round. Otherwise, the value is stored in the log of the queue manager and is applied when the queue manager next restarts.

When you specify PAGECLAS(FIXED4KB) the whole buffer pool is backed by page-fixed 4KB pages, so ensure that there is sufficient real storage available on the LPAR. Otherwise, the queue manager might not start, or other address spaces might be impacted. For more information, see Address space storage.

See IBM MQ Support Pac MP16: IBM MQ for z/OS - Capacity planning & tuning for advice on when to use the FIXED4KB value of the PAGECLAS attribute.

REPLACE/NOREPLACE

Optional attribute describing whether this definition of a buffer pool overrides any definition that might already be contained in the log of the queue manager.

The queue manager records the current buffer pool settings in checkpoint log records. These buffer pool settings are automatically restored when a queue manager is later restarted. This restoration occurs after processing of the CSQINP1 data set.

Therefore, if you have used ALTER BUFFPOOL since the buffer pool was last defined, any DEFINE BUFFPOOL command in CSQINP1 is ignored at restart, unless the REPLACE attribute is specified.

Attention: If you specify the REPLACE attribute on the DEFINE BUFFPOOL command in CSQINP1, then some time later you specify the ALTER BUFFPOOL command to increase the buffer pool size (for example because of an increase in workload, and therefore an increase in demand on buffer pool usage) this could lead to an issue when the queue manager is next restarted.

Following restart, your buffer pools would revert to the original size defined in CSQINP1 and hence not be able to handle the increased workload. Therefore, you should consider removing the REPLACE attribute from the DEFINE BUFFPOOL commands in CSQINP1 as soon as the buffer pools are successfully defined.

This will ensure that any changes made to the buffer pools, as a result of specifying ALTER BUFFPOOL commands, are preserved across restarts of the queue manager.

REPLACE: This definition of the buffer pool overrides the definition stored in the log of the queue manager, if there is one. If the definition in the log of the queue manager is different from this definition, the differences are discarded and message CSQP064I is issued.
NOREPLACE: This is the default value, and provides the same behavior as with previous releases of IBM MQ. If there is a definition of the buffer pool in the log of the queue manager, that definition is used and this definition is ignored.

Attention: The queue manager records the current buffer pool settings in checkpoint log records. These buffer pool settings are automatically restored when a queue manager is later restarted. This restoration occurs after processing of the CSQINP1 data set. Therefore, if you have used ALTER BUFFPOOL since the buffer pool was last defined, any DEFINE BUFFPOOL command in CSQINP1 has been ignored at restart, unless the REPLACE attribute has been specified.