BPI - Buffer Pool Initialization

#### Search Results

Search

# 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:

1. There are several types of buffer pools for different purposes. It is possible to define backup buffer pools (see examples below).
2. 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:

1. `BPI=(TYPE=NAT,OFF)` deletes all user buffer-pool definitions for Natural; that is, the default values are used for the Natural buffer pool.
2. If `OFF` is used, it must be specified as the last value after `TYPE` and `SEQ`.
3. 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

`C64` | `CSIZE` | `LIST` | `METHOD` | `NAME` | `SEQ` | `SIZE` | `TXTSIZE` | `TYPE`

Notes:

1. 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.

### C64 - Type of Buffer Pool Cache Storage

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

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.

Notes:

1. This subparameter applies to Natural local buffer pools (`TYPE=NAT`) under z/OS only (not for Com-plete).
2. A buffer pool cache is used only if `BPI` subparameter `CSIZE` or profile parameter `BPCSIZE` is set to a non-zero value.
3. 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:

1. If the value specified exceeds the possible maximum value, the possible maximum value will be taken instead.
2. The `CSIZE` specification applies to Natural local buffer pools (`TYPE``=NAT`) only (not for Com-plete).
3. 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.
4. 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:

1. This subparameter applies only to Natural local buffer pools (`TYPE``=NAT`).
2. The `LIST` specification can be overridden dynamically with the profile parameter `BPLIST`.
3. For more information on preload lists, see Preload List in the Operations documentation.
4. 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:

1. This subparameter applies only to Natural local buffer pools (`TYPE``=NAT`).
2. The `METHOD` specification can be overridden dynamically with the profile parameter `BPMETH`.
3. 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:

1. This subparameter applies only to Natural global buffer pools under CICS.
2. For a Natural local buffer pool, the name is blank.
3. 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.
4. 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:

1. The buffer pool defined with the lowest sequence number is called primary buffer pool.
2. For every buffer pool type 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.
3. 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).
4. 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:

1. This subparameter applies to local buffer pools only.
2. In case of a Natural buffer pool (`TYPE=NAT`), the `SIZE` specification can be overridden dynamically with the profile parameter `BPSIZE`.

### 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:

1. This subparameter applies to local buffer pools of `TYPE=NAT` and `TYPE=SORT`.
2. In multi-user environments (for example, under CICS), the `TXTSIZE` specification only affects the very first Natural session which initializes the local buffer pool.
3. 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.
`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.

Notes:

1. 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.
2. 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.

## 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.

### On this page

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