BPI - Buffer Pool Initialization

This Natural profile parameter is used to assign buffer pools to a Natural session. It corresponds to the NTBPI macro in the Natural parameter module.

Possible settings	See BPI Parameter Syntax.
Default setting	See Keyword Subparameters.
Dynamic specification	yes	This parameter can only be specified dynamically. In the Natural parameter module, the macro `NTBPI` is used instead.
Specification within session	no

Notes:

There are several types of buffer pools for different purposes. It is possible to define backup buffer pools (see examples below).
If a buffer pool is unavailable, Natural tries to setup a backup buffer pool of the same type with the next higher sequence number.

The following topics are covered below:

BPI Parameter Syntax
NTBPI Macro Syntax
Keyword Subparameters
Examples of BPI Parameter
Examples of NTBPI Macros

BPI Parameter Syntax

The BPI parameter is specified as follows:

BPI=(keyword-subparameter=value,keyword-subparameter=value,...)

Or, to delete all buffer-pool definitions for a certain type, omit SEQ and specify:

BPI=(TYPE=value,OFF)

See Keyword Subparameters.

Notes:

BPI=(TYPE=NAT,OFF) deletes all user buffer-pool definitions for Natural; that is, the default values are used for the Natural buffer pool.
If OFF is used, it must be specified as the last value after TYPE and SEQ.
To dynamically deactivate a buffer-pool definition, use the special value OFF as follows:If you use the BPI parameter to override an existing buffer pool definition in the Natural parameter module, you must specify new settings in all those subparameters which are to be changed; if you do not, the old settings will still be used. If, for example, you want to change from a global to a local buffer pool, you must specify: NAME=' ' (blank).If you use the BPI parameter to dynamically add a new backup buffer pool definition, you must use the SEQ subparameter to specify a sequence number for it. If you omit the SEQ specification, the definition of the primary buffer pool (SEQ=0) will be overwritten.The NAME, SIZE, LIST, TXTSIZE, CSIZE, METHOD and C64 specifications for the primary buffer pool (SEQ=0) can also be set dynamically with the profile parameters BPNAME, BPSIZE, BPLIST, BPTEXT, BPCSIZE, BPMETH and BPC64.

NTBPI Macro Syntax

The NTBPI macro is specified as follows:

         NTBPI C64=value,                                              *
               CSIZE=value,                                            *
               LIST=value,                                             *
               METHOD=value,                                           *
               NAME=value,                                             *
               SEQ=value,                                              *
               SIZE=value,                                             *
               TXTSIZE=value,                                          *
               TYPE=value

See Keyword Subparameters.

Note:
The value OFF, which is available in the syntax of profile parameter BPI, cannot be specified in the macro NTBPI.

Keyword Subparameters

Notes:

The keyword subparameters SIZE, CSIZE, TXTSIZE, METHOD and C64 do not apply to global buffer pools. They are honored only for the very first session which initializes a local buffer pool.
Under BS2000, the subparameters SIZE and CSIZE are ignored.

C64 - Type of Buffer Pool Cache Storage

C64=value determines the type of storage to be used for the buffer pool cache.

Value Explanation

Value	Explanation
`ON`	Indicates that a memory object "above the bar" (that is, in 64-bit memory) is to be used for the buffer pool cache. Note that `C64=ON` is honored only if the prerequisites are met, namely: z/... architecture hardware, operating system z/OS Version 1.2 or higher. If these prerequisites are not met, the default value is taken.
`OFF`	Indicates that a data space is to be used for the buffer pool cache. This is the default value.

ON

Indicates that a memory object "above the bar" (that is, in 64-bit memory) is to be used for the buffer pool cache.

Note that C64=ON is honored only if the prerequisites are met, namely:

z/... architecture hardware,
operating system z/OS Version 1.2 or higher.

If these prerequisites are not met, the default value is taken.

OFF

Indicates that a data space is to be used for the buffer pool cache.

This is the default value.

Notes:

This subparameter applies to Natural local buffer pools (TYPE=NAT) under z/OS only (not for Com-plete).
A buffer pool cache is used only if BPI subparameter CSIZE or profile parameter BPCSIZE is set to a non-zero value.
The C64 specification can be overridden dynamically with the profile parameter BPC64.

CSIZE - Size of the Local Buffer Pool Cache

CSIZE=value determines the size of the buffer pool cache.

Value	Explanation
`0`	If `BPCSIZE=0` is set, no buffer pool cache is used. This is the default value.
`100 - 2097148` (2 GB - 4 KB)	The buffer pool cache size in KB for cache in data space; that is, with `C64=OFF`. Note: The specified value is rounded to the next 4 KB boundary.
`100 - 58720256` (56 GB)	The buffer pool cache size in KB for cache "above the bar"; that is, with `C64=ON`. Note: The specified value is rounded to the next 1 MB boundary.

Notes:

If the value specified exceeds the possible maximum value, the possible maximum value will be taken instead.
The CSIZE specification applies to Natural local buffer pools (TYPE=NAT) only (not for Com-plete).
Under CICS: The CSIZE specification applies to swap pools (TYPE=SWAP). The value of the CSIZE parameter for a swap pool under CICS must be at least twice the maximum thread size of the associated Natural under CICS environment (see NCMTGD macro in the Natural under CICS documentation), otherwise the CSIZE parameter is ignored. This maximum thread size also has to be provided as roll buffer within the swap pool size specification.
The CSIZE specification can be overridden dynamically with the profile parameter BPCSIZE (only in case of TYPE=NAT). To determine the type of storage for the buffer pool cache, subparameter C64 can be used.
Under BS2000: CSIZE is ignored.
For further information, see Buffer Pool Cache in the Operations documentation.

LIST - Name of Preload List to be Used

LIST=value determines the name of the preload list to be used for this buffer pool.

Value	Explanation
1 - 8 characters	The name of the preload list to be used for this buffer pool.
`' '` (blank)	If `LIST=' '` (blank) is set, no preload list is used. This is the default value.

Notes:

This subparameter applies only to Natural local buffer pools (TYPE=NAT).
The LIST specification can be overridden dynamically with the profile parameter BPLIST.
For more information on preload lists, see Preload List in the Operations documentation.
Preload lists are maintained with the SYSBPM utility; see Preload List Maintenance in the Utilities documentation.

METHOD - Search Algorithm for Allocating Space in Buffer Pool

METHOD=value determines the algorithm for allocating storage in the 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 the 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.

Notes:

This subparameter applies only to Natural local buffer pools (TYPE=NAT).
The METHOD specification can be overridden dynamically with the profile parameter BPMETH.
For further information, see Buffer Pool Search Methods in the Operations documentation

NAME - Name of Global Buffer Pool

NAME=value determines the name of the global buffer pool.

Value	Explanation
1 - 8 characters	The name of the global buffer pool to be used.
`' '` (blank)	A Natural local buffer pool is used. This is the default value.

Notes:

This subparameter applies only to Natural global buffer pools, and to swap pools (TYPE=SWAP) under CICS.
For TYPE=SWAP, the name is the swap pool name which is the key of the associated swap pool definitions in the Natural system file FNAT or FUSER; see parameter SWPINIT in Natural Swap Pool Initialization Control in the Operations documentation.
For a Natural local buffer pool, the name is blank.
Under BS2000: An ADDON macro with the same value for the keyword subparameter NAME is required in the BS2STUB used.
Under IMS TM: Because a Natural session may be executed in different regions, an editor local buffer pool is not possible, but only an editor global buffer pool.
The NAME specification can be overridden dynamically with the profile parameter BPNAME (with TYPE=NAT only).

SEQ - Sequence Number of Buffer Pool

SEQ=value determines the sequence number of the buffer pool.

Value	Explanation
`0` or `1` - `9`	The sequence number of the buffer pool.
`0`	This is the default value.

Notes:

The buffer pool defined with the lowest sequence number is called primary buffer pool.
For every buffer pool type, except TYPE=SWAP, you can define one primary buffer pool and one or more backup buffer pools; that is, alternative buffer pools (of the same type, but with a different sequence number) which will be used if the primary buffer pool is not available at session initialization or cannot be allocated.
Buffer pools of the same type are sorted in order of sequence numbers (should two pools of the same type have the same sequence number, they will be sorted in the order in which they are specified).
If a requested buffer pool is not available, the buffer pool of the same type with the next higher sequence number will be used instead. If that one is not available either, the one with the next higher number will be used, and so on.

SIZE - Size of Buffer Pool

SIZE=value determines the size of the buffer pool.

Value	Explanation
`256` - `2097151`	The buffer pool size in KB for Natural buffer pools.
`100` - `2097151`	The buffer pool size in KB for other buffer pool types
`256`	This is the default value.

Notes:

This subparameter applies to local buffer pools only.
Under CICS: The required "logical" minimum size of a swap pool under CICS computes as total of the NTSWPRM macro SWPSLSZ parameter slot sizes times their (implicit or explicit) factor plus 2 KB for each logical swap pool. When using a swap pool cache (see CSIZE subparameter), additionally the maximum thread size of the associated Natural under CICS environment is required for a roll buffer; that is, it has to be added to the computed value.
In case of a Natural buffer pool (TYPE=NAT), the SIZE specification can be overridden dynamically with the profile parameter BPSIZE.
Under BS2000: The SIZE specification is ignored.

TXTSIZE - Size of Buffer Pool Text Segments

TXTSIZE=value specifies the size of the segments into which the text pool area of the Natural buffer pool is divided.

Value	Explanation
`1`, `2`, `4`, `8`, `12` or `16`	The size of the buffer pool text segments in KB.
`4`	This is the default value.

Notes:

This subparameter applies to local buffer pools of TYPE=NAT, TYPE=SORT, and TYPE=DLI.
In multi-user environments (for example, under CICS), the TXTSIZE specification only affects the very first Natural session which initializes the local buffer pool.
In case of TYPE=NAT, the TXTSIZE specification can be overridden dynamically with the profile parameter BPTEXT.

TYPE - Type of Buffer Pool

TYPE=value determines the type of the buffer pool.

Value	Explanation
`NAT`	Natural buffer pool. This is the default value.
`DLI`	DL/I buffer pool; see Control Blocks in Separate Buffer Pool in the Natural for DL/I documentation.
`EDIT`	Software AG Editor buffer pool; see Editor Buffer Pool in the Operations documentation. Alternatively, an editor auxiliary buffer pool can be defined per session; see profile parameter `EDPSIZE`.
`SORT`	Sort buffer pool; see also keyword subparameter `STORAGE` of profile parameter `SORT` and macro `NTSORT`.
`MON`	Buffer pool for the monitoring function (`SYSMON`) of the SYSTP utility; see Natural Monitoring (SYSMON) in the Utilities documentation.
`MSG`	Message buffer pool; see Message Buffer Pool in the Operations documentation. Note: For this type of buffer pool, only the subparameter `NAME` will be honored.
`SWAP`	Buffer pool to hold the Natural CICS swap pool; see Natural Swap Pool under CICS in the TP Monitor Interfaces documentation.

Notes:

Buffer pools of type NAT, DLI and SORT can be managed with the SYSBPM utility ; see SYSBPM Utility - Buffer Pool Management in the Utilities documentation.
For general information on the Natural buffer pool, see Natural Buffer Pools in the Operations documentation.

Examples of BPI Parameter

Example 1:

BPI=(NAME=' ',SIZE=2000,METHOD=N)

The primary buffer pool is replaced by a local buffer pool of 2000 KB. This definition is equivalent to:

BPNAME=' ',BPSIZE=2000,BPMETH=N

Example 2:

BPI=(SEQ=0,NAME=LBP1),BPI=(SEQ=1,NAME=LBP2),BPI=(SEQ=2,SIZE=500)

First, Natural tries to allocate a global Natural buffer pool with the name LBP1. If this buffer pool is not found, it tries to allocate LBP2. If this is not found, it allocates a local buffer pool with a size of 500 KB.

Example 3:

BPI=(SEQ=0,TYPE=EDITOR,NAME=LBPE1),BPI=(SEQ=1,TYPE=EDITOR,SIZE=500)

First, Natural tries to locate a global editor buffer pool with the name LBPE1. If this is not found, it allocates a local editor buffer pool with a size of 500 KB.

Example 4:

BPI=(TYPE=SWAP,SIZE=500,NAME=SWAPPOOL,CSIZE=2000)

A Natural local swap pool named SWAPPOOL having a size of 500 KB and a cache size of 2000 KB is allocated.

Examples of NTBPI Macros

         NTBPI TYPE=NAT,                                               *
               SEQ=0,                                                  *
               NAME=NATBP1
         NTBPI TYPE=NAT,                                               *
               SEQ=1,                                                  *
               NAME=NATBP2
         NTBPI TYPE=NAT,                                               *
               SEQ=2,                                                  *
               SIZE=1000,                                              *
               METHOD=N

These examples define multiple Natural buffer pools. If the global buffer pool NATBP1 is not available, the global buffer pool NATBP2 will be used instead. If the latter is not available either, a local buffer pool with a size of 1000 KB will be used.