Common Natural GBP Operating Functions under z/OS and z/VSE

This document provides a summary of those operating functions of the Natural global buffer pool which are identical under z/OS and z/VSE.

The section covers the following topics:


Global Buffer Pool Manager Parameter Module

The global buffer pool parameter module NATGBPRM is used to set global processing options which apply to all functions and buffer pools. The global buffer pool parameter module is delivered in source and object form with all defaults set.

The following parameter is available:

UCTRAN - Lower/Mixed Case Support

This parameter enables or disables the lower/mixed case support for the global buffer pool messages.

UCTRAN=NO Lower/mixed case support is fully enabled.

This is the default value.

UCTRAN=YES All global buffer pool messages are issued in upper case.

Global Buffer Pool Operating Functions

The following functions are available:

Note:
If no function is specified, CREATE is assumed when the profile parameter BPNAME is specified, otherwise NOP is assumed.

ADDCACHE - Allocate Cache for an Existing Global Buffer Pool

This function adds cache storage to an existing global buffer pool.

CREATE - Create Global Buffer Pool

This function creates a global buffer pool with the specified parameters.

DELCACHE - Release Cache of a Global Buffer Pool

This function removes the cache storage of a global buffer pool without shutting down the buffer pool itself.

FSHUT - Shut Down Global Buffer Pool

The global buffer pool is shut down, and the storage area is released.

If there are no active objects in the buffer pool, FSHUT is executed immediately.

If there are still active objects in the buffer pool, this will be indicated to the operator. Depending on the setting of the parameter CONFIRM, the operator is asked for a confirmation or FSHUT is executed immediately.

GLOBALS - Show Global Parameter Settings

This function shows all global parameter settings, that is, parameters which do not only apply to the statement for which they have been specified.

In addition, the storage key of the global buffer pool(s) is shown.

LISTCACHE - List All Global Buffer Pool Caches Owned by Job

This function lists all global buffer pool caches currently owned by the job.

NOP - No-Operation

This function code particularly can be used to set global parameters.

REFRESH - Re-initialize Global Buffer Pool

With the REFRESH command it is possible to re-initialize an already active buffer pool. As no storage allocation takes place, the buffer pool size and location (above or below 16 MB) remain unchanged. However, it is possible to change the text-block size (see NATBUFFER parameter).

You should use this function only if the Current Use Count (see Fields for Buffer Pool Objects in SYSBPM Directory Information) is equal to zero (see warning below) or if the buffer pool has been destroyed.

Warning:
If you re-initialize the buffer pool while Natural objects are being executed by active sessions in this buffer pool, the results of the active sessions are unpredictable and Natural may even abend.

SHOWBP - Show Existing Buffer Pools

Displays all buffer pools currently existing.

TERMINATE - Terminate GBP Operating Program

The GBP operating program is terminated. This termination does not affect any active global buffer pool.

ZAPS - Display Zaps Applied to GBP

Displays all Zaps applied to the global buffer pool operating program.

Global Buffer Pool Function Parameters

The functions of the Natural GBP operating program can be controlled with the aid of parameters. These parameters can be specified in any sequence. They can be abbreviated so that they are still unique.

Note:
If you like to start multiple global buffer pools with an associated cache, you are recommended to use a single job or (under z/OS only) a single started task and to supply the different CREATE commands in an input data set. See Example 4 in the section Natural Global Buffer Pool under z/OS or Example 4 in the section Natural Global Buffer Pool under z/VSE.

The following parameters are available:

BPNAME - Name of Global Buffer Pool

BPNAME=value is required (except for the TERMINATE function). It specifies the name of the global buffer pool to be created.

Value Explanation
8 bytes The name of the global buffer pool.

Note:
If the specified name is shorter than 8 bytes, blanks will be appended to it.

* For the functions DELCACHE and FSHUT, you may supply a value of "*" to process all buffer pools for the specified Natural subsystem.

BPLIST - Name of Preload List

BPLIST=value specifies the name of the preload list.

Value Explanation
8 bytes The name of the preload list.

Note:
If the specified name is shorter than 8 bytes, blanks will be appended to it.

BPCSIZE - Buffer Pool Cache Size

BPCSIZE=value specifies the amount of storage (in KB) used to allocate a data space for the buffer pool cache.

Value Explanation
100 - 2097148 The amount of storage (in KB) used to allocate a data space for the buffer pool cache.

Notes:

  1. The cache size can also be specified in units of MB or GB, for example, by specifying 10M for 10 MB.
  2. If the BPCSIZE parameter is omitted (or set to zero), the buffer pool is not supplied with a cache.
  3. A cache is only supported for buffer pools of TYPE=NAT.

CC - Count Condition Code

CC=value determines whether a condition code is ignored when returned by a command executed by the global buffer pool manager.

Value Explanation
Y The condition code returned after command execution is counted for the condition code of the NATGBPvr job.

This is the default value.

N The condition code returned after command execution is ignored.

This may lead to a job response code of zero although the command execution failed.

Note:
This parameter is valid for all commands.

Example of Command Execution:

The global buffer pool QA82GBP is stopped and restarted with the following command sequence:

FSHUT  BPN=QA82GBP,S=QA82,CONFIRM=N,CC=N            
CREATE BPN=QA82GBP,S=QA82,N=(1024),M=S,BPC=4096,I=60

The FSHUT command usually returns a condition code of 20 when it executes and the buffer pool is not active. However, with CC=N set, any condition code is ignored. In this case, a job response code greater than zero is only returned if the following CREATE command fails.

CONFIRM - FSHUT Confirmation

CONFIRM=value controls the FSHUT behavior if there are still active objects in the buffer pool.

Value Explanation
Y A confirmation for the FSHUT function is required from the operator. The operator can decide to abort or to force the FSHUT function.

This is the default value.

N FSHUT is forced without interaction with the operator.

Note:
This parameter is only valid for the FSHUT command it has been specified with, that is, CONFIRM has to be specified with each FSHUT parameter, and it does not apply to subsequent FSHUT commands.

IDLE - Wait Time before Check

IDLE=value is ignored when the task does not own a buffer pool cache.

Value Explanation
Numeric The number of seconds to elapse before the GBP operating program checks for each buffer pool cache if its associated buffer pool is still active; if not, that buffer pool cache is released; when the last buffer pool cache owned by the task has been released, the task terminates, unless RESIDENT=Y has been specified.
60 This is the default value.

Notes:

  1. IDLE is a "global" parameter. Once specified, IDLE will also apply to subsequent commands, without your having to specify it again.
  2. Under z/OS, the GBP operating program also checks the specified IDLE time value against the job's timeout value: the specified IDLE time value internally may reduce IDLE to prevent timeout abends (S322).

METHOD - Search Algorithm for Allocating Space in Buffer Pool

METHOD=value controls which algorithm is to be used for allocating storage in the Natural buffer pool.

Value Explanation
S Indicates that a selection process is to be used for allocating storage.

The selection process consists of browsing the whole buffer pool directory and comparing different entries in order to find a most suitable entry. This method was formerly known as algorithm 1+2.

This is the default value.

N Indicates that the next available unused or free space is to be used.

The search for the next available space is done from a pointer to directory entries which moves in a wrap-around fashion. This method may be used in combination with a buffer pool cache.

Note:
This parameter is only valid for the CREATE function. If you want to change the allocation method, restart the buffer pool.

NATBUFFER - Buffer Size, Mode, Text Block Size

NATBUFFER=(size,mode,tsize) specifies the size and the mode of the buffer pool, and the text block size.

Syntax Value Explanation
NATBUFFER=(size,mode,tsize) size

is the amount of storage (in KB) to be allocated.

For the Natural buffer pool (TYPE=NAT), the default and minimum possible size is 256 KB.

For the other buffer pools, the default and minimum possible size is 100 KB.

The specified amount of storage is always rounded up to a multiple of 4 KB.

The pool size can also be specified in units of MB or GB, e.g. by specifying 10M for 10 MB.

Next to the storage specified by size, one page (4 KB) of write protected storage will be allocated for administrative purposes.

mode

determines if the global buffer pool is to be allocated above or below 16 MB.

Possible values are: XA = above (default), BL = below.

tsize

determines the text block size (in KB).

Possible values are: 1, 2, 4, 8, 12, and 16. The default value is 4.

size, mode and tsize have to be specified in the sequence shown above.

Note:
If NATBUFFER is not specified, the default values will be used. See also Examples of NATBUFFER Specifications.

RESIDENT - Behavior after Function Execution

RESIDENT=value specifies the behavior of the GBP operating program after the specified function has been executed. The following values are possible:

Value Explanation
Y The GBP operating program will remain active after executing the specified function and await further commands. Once specified, RESIDENT=Y will also apply to subsequent commands, without your having to specify it again. (To stop the GBP operating program, you use the TERMINATE function.)
N The GBP operating program will terminate after executing the specified function, if no further command is available. If the task owns a buffer pool cache, RESIDENT=N is ignored and the task is not terminated.
A The GBP operating program automatically decides how to behave after having processed all commands. It will terminate if
  • no further command is available and

  • no buffer pool with an associated cache exists that was created by this task.

In other words: If no buffer pool cache is owned by the task, RESIDENT=A works in the same way as RESIDENT=N. When the task owns a buffer pool cache, RESIDENT=A works the same way as RESIDENT=Y, but switches automatically to RESIDENT=N, when the last buffer pool whose associated buffer pool cache was owned by this task has terminated.

This is the default setting.

Note:
RESIDENT is a "global" parameter. Once specified, RESIDENT will also apply to subsequent commands until explicitly specified/overwritten.

SUBSID - Natural Subsystem ID

SUBSID=value specifies the ID of the Natural subsystem.

Value Explanation
4 bytes The 4-byte ID of the Natural subsystem.

Once specified, SUBSID will also apply to subsequent commands, without your having to specify it again.

The default value is NATv, where v is the first digit of the current Natural version.

NATv This is the default value. v is the first digit of the current Natural version.

Notes:

  1. SUBSID is a "global" parameter, that is, once specified, SUBSID will also apply to subsequent commands until explicitly specified/overwritten.
  2. For the functions DELCACHE, FSHUT and SHOWBP, you may supply a value of "*" to process all buffer pools for the specified Natural subsystem.
  3. For further information on the Natural subsystem, see Natural Subsystem (z/OS) or Natural Subsystem (z/VSE).

TYPE - Type of Buffer Pool

TYPE=value specifies the type of the buffer pool. Possible values are:

Value Explanation
NAT Natural buffer pool (this is the default).
SORT Sort buffer pool.
DLI DL/I buffer pool.
EDIT Editor buffer pool.
MON Monitor buffer pool.
RNM Review Natural Monitor buffer pool.

Examples of NATBUFFER Specifications

The following examples refer to the NATBUFFER parameter which is used to set buffer size, mode and text block size, the parameter name being abbreviated (N).

Example 1: To allocate a global buffer pool above 16 MB, with a size of 1 MB and a text block size of 1 KB, you specify:

N=(1000,,1)

or

N=(1M,,1)

Example 2: To allocate a global buffer pool above 16 MB, with a size of 10 MB and a text block size of 4 KB, you specify:

N=(10000)

or

N=(10M)

Example 3: To allocate a global buffer pool above 16 MB, with a size of 256 KB and a text block size of 4 KB, you specify:

N=(,,)

This is equivalent to omitting the NATBUFFER parameter altogether, as it causes the default values to apply.