Natural Global Buffer Pool under z/OS

#### Search Results

Search

# Natural Global Buffer Pool under z/OS

This document describes purpose and usage of a Natural global buffer pool (GBP) under the operating system z/OS.

The section covers the following topics:

- Using a Natural Global Buffer Pool

- Prerequisites

- Operating the Natural Global Buffer Pool

- Global Buffer Pool Manager Parameter Module

- Global Buffer Pool Operating Functions

- Global Buffer Pool Function Parameters

- Examples of NATBUFFER Specifications

- Sample NATGBPvr Execution Jobs

- Localization

- Messages

## Using a Natural Global Buffer Pool

### Purpose

The Natural global buffer pool is a segment of storage assigned from the z/OS extended common system area (ECSA) above 16 MB (or from CSA storage below, if requested), used by Natural to load and execute Natural programs.

### Benefits

Using a global buffer pool, multiple Natural sessions under different TP monitors (multiple copies of CICS, TSO, IMS TM, etc.) and/or in multiple batch sessions share the same area - thus requiring less storage than would be required for a local buffer pool in each environment.

## Prerequisites

The following prerequisites must be met if you want to use a global buffer pool:

1. The module `NATGBPvr` must have been linked into an Authorized Program Facility (APF) library; see the corresponding step in Installing Natural on z/OS in the Installation for z/OS documentation.

2. The global buffer pool must have been started; see the corresponding step in Installing Natural on z/OS in the Installation for z/OS documentation.

## Operating the Natural Global Buffer Pool

The global buffer pool is operated using the program `NATGBPvr` which must be executed from within an Authorized Program Facility (APF) library.

The following topics are covered below:

- Allocation of the Natural GBP

- Setting up the Natural GBP

- Starting the Natural GBP Operating Program

- Stopping the Natural GBP Operating Program

Note
In the following document, vrs or vr represents the relevant version of the product. For information on product versions, see Version in the Glossary.

### Allocation of the Natural GBP

If the z/OS parameter `ALLOWUSERKEYCSA(YES)` has explicitly been specified in `SYS1.PARMLIB(DIAGxx)`, a Natural global buffer pool is allocated in user key, so that Natural sessions accessing a global buffer pool have write permission for that buffer pool.

If `ALLOWUSERKEYCSA(NO)` is in effect, a Natural global buffer pool is allocated in system key; therefore, Natural sessions accessing a global buffer pool do not have any write permission for that buffer pool. These Natural sessions call the Authorized Services Manager (ASM) to perform all buffer pool functions. As a consequence, installation of the ASM is mandatory. The ASM is not only called to load a Natural object into the buffer pool but also to maintain the use count of a Natural object if the execution of this Natural object is started or terminated. The calls to the Authorized Services Manager will increase Natural’s resource consumption. The overhead is hard to predict and depends on the application profile (ratio of program calls to program execution time).

### Setting up the Natural GBP

The functions provided by the operating program `NATGBPvr` are activated in that they are

- specified in a parameter card (`PARM`=),

- read from a file (see below),

- or supplied by the `MODIFY` operator command.

`NATGBPvr` expects the first command in the parameter field (`PARM`=) of the `EXEC` statement.

You may enter:

- one of these functions

- or a reference to an input file with `CF=dd-name`, where `dd-name` represents a DD name defined in the JCL. Only "card image" files are supported, that is, `RECFM=F,LRECL=80`, and only the first 72 bytes of the input record are honored. Every record included from the input file represents a command. Blank records or records prefixed with an asterisk (*) are ignored. A file is processed until End-Of-File (EOF). Example: `PARM='CF=SYSIN1'`

If the parameter field is not supplied or blank, the commands will be read from file `SYSIN` by default.

It is only possible to enter one function at a time at the console or one function per line using the command file, otherwise an error message will be returned.

Each command received, from the parameter card, from file input or from operator console input is shown on the operator console.

### Starting the Natural GBP Operating Program

To start the program `NATGBPvr`, either start a started task or submit a job, which executes `NATGBPvr`.

Important
To ensure that the global buffer pool is retained after a system failure, the global buffer pool should be started automatically during machine IPL.

### Stopping the Natural GBP Operating Program

After all commands are processed, the program `NATGBPvr` terminates, unless

- `RESIDENT=Y` was specified

- or a buffer pool with a cache was created.

`NATGBPvr` will return one of the following condition codes:

Condition Code | Explanation
--- | ---
`0` | All functions executed successfully.
`20` | An error has occurred; see the message log for details. See also the `CC` function parameter of the global buffer pool.

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

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

- HELP - Shows an overview of the available syntax

- ADDCACHE - Allocate Cache for an Existing Global Buffer Pool

- CREATE - Create Global Buffer Pool

- DELCACHE - Release Cache of a Global Buffer Pool

- FSHUT - Shut Down Global Buffer Pool

- GLOBALS - Show Global Parameter Settings

- LISTCACHE - List All Global Buffer Pool Caches Owned by Job

- NOP - No Operation

- REFRESH - Re-initialize Global Buffer Pool

- SHOWBP - Show Existing Buffer Pools

- TERMINATE - Terminate GBP Operating Program

- ZAPS - Display Zaps Applied to GBP

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

### HELP - Shows an overview of the available syntax

This function prints a list of the available syntax commands and, where applicable, the default values of the function parameters.

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

Note
A data space Cache can only be deleted by the task which owns it. An "above the bar" memory object Cache can be deleted by any task.

### FSHUT - Shut Down Global Buffer Pool

The global buffer pool is shut down and the storage area, including buffer pool and cache storage, 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 can be used to set global parameters. It does not perform any buffer pool operation.

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

The following parameters are available:

- `BPNAME` - Name of Global Buffer Pool
- `BPLIST` - Name of Preload List
- `BPCSIZE` - Buffer Pool Cache Size
- `C64` - Type of Buffer Pool Cache Storage
- `CC` - Count Condition Code
- `CONFIRM` - `FSHUT` Confirmation
- `IDLE` - Wait Time before Check
- `METHOD` - Search Algorithm for Allocating Space in Buffer Pool
- `NATBUFFER` - Buffer Size, Mode, Text Block Size
- `RESIDENT` - Behavior after Function Execution
- `SUBSID` - Natural Subsystem ID
- `TYPE` - Type of Buffer Pool

### 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 "*". `FSHUT` shuts down all the buffer pools for the specified natural subsystems. If sub parameter `CONFIRM` is set to `Y`, you must also provide additional confirmation. `DELCACHE` deletes all data space caches owned by the task from the specified natural subsystem. To delete caches located in "above the bar" memory, you must also provide a complete BPNAME and SUBSID.

### 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 used to allocate a Buffer Pool Cache.

Value | Explanation
--- | ---
`100 - 2097148` | When sub parameter `C64=N`, this value is the amount of allocated storage (in KB) for a data space for the buffer pool cache. The specified value is rounded to the next 4KB boundary.
`100 - 58720256` (max 57344MB) | When sub parameter `C64=Y`, this value is the amount of allocated storage (in KB) for an "above the bar" memory object for the buffer pool cache. The specified value is rounded to the next 1MB boundary.

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`.
4. The sub parameter `C64` decides whether the cache is created in the data space or in the "above the bar" 64 bit common memory.

### C64 - Type of Buffer Pool Cache Storage

`C64=value` determines the type of storage for the buffer pool cache. The following values are possible:

Value | Explanation
--- | ---
`Y` | The storage for the buffer pool cache will be an "above the bar" memory object (in 64-bit memory).
`N` | The storage for the buffer pool cache will be a data space. This is the default value.

Note
This parameter is applicable only if `BPCSIZE` is provided.

### 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 `NATGBP1` is stopped and restarted with the following command sequence:

    FSHUT BPN=NATGBP1,S=NAT92,CONFIRM=N,CC=N
    CREATE BPN=NATGBP1,S=NAT92,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
--- | ---
`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. This is the default value.
`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.

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 `SUBSID=`"*" to process a given buffer pool, regardless of the subsystem. Alternatively, you may supply `BPNAME="*"` to process all buffer pools from all subsystems. In this case, the `FSHUT` function will prompt for an additional confirmation, regardless of the value of the `CONFIRM` sub parameter.
3. For further information on the Natural subsystem, see Natural Subsystem (z/OS).

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

## Sample NATGBPvr Execution Jobs

The following examples show sample batch jobs for creating and terminating a global buffer pool.

In the following examples, the notation vrs or vr represents the relevant product version. For information on product versions, see Version in the Glossary.

### Example 1:

    //GBPSTART JOB
    //*
    //* Starts a global buffer pool with the name NATvrGBP, a size of 1 MB and
    //* a text block size of 4 KB. The global buffer pool is allocated above 16 MB.
    //* The subsystem used is NATv.
    //* After the allocation, the job GBPSTART terminates.
    //*
    //STEP EXEC PGM=NATGBPvr,PARM='BPN=NATvrGBP,N=(1M)'
    //SETPLIB DD DISP=SHR,DSN=USER.APF.LINKLIB

### Example 2:

    //GBPRES JOB
    //*
    //* Starts a global buffer pool with the name GBP, a default size of
    //* 100 KB and a text block size of 1 KB. The global buffer pool is allocated
    //* below 16 MB. The subsystem used is SAGS.
    //* After the allocation, the job GBPRES will wait for further commands.
    //* Further commands may be entered using the MODIFY operator command:
    //* F GBPRES,command-string
    //*
    //STEP EXEC PGM=NATGBPvr,PARM='BPN=GBP,N=(,BL,1),S=SAGS,R=Y'

### Example 3:

    //GBPSTOP
    //*
    //* Stops the global buffer pool GPB if it contains no active objects. If it
    //* does contain active objects, the operator console will prompt for a reply.
    //* Depending on the reply, the shutdown will be forced (Y) or aborted (N).
    //* The subsystem used is NATv.
    //*
    //STEP EXEC PGM=NATGBPvr,PARM='FSHUT,BPN=GPB'

### Example 4:

    //GBPSTRT2
    //* Read commands from SYSIN1:
    //*
    //* Start two global buffer pools (subsystem ID Nvrs) with names
    //*   NATGBP1 - size=1024KB and a cache with size 2048KB, and
    //*   NATGBP2 - size=2048KB without cache.
    //* Display all buffer pools of subsystem ID Nvrs.
    //*
    //* Note: The job does not terminate by itself, but stays resident and waits
    //*       for operator commands because it owns the data space allocated for
    //*       buffer pool NATGBP1.
    //*
    //* To shut down the buffer pools, send the operator command MODIFY with
    //* parameter CF=SYSIN2 to execute the corresponding FSHUTs.
    //*
    //STEP EXEC PGM=NATGBPvr,PARM='CF=SYSIN1'
    //SYSIN1  DD *
    CREATE,BPN=NATGBP1,S=Nvrs,N=(1M),BPC=2M
    CREATE,BPN=NATGBP2,S=Nvrs,N=(2M)
    SHOWBP S=Nvrs
    //SYSIN2 DD *
    FSHUT,BPN=NATGBP1,S=Nvrs
    FSHUT,BPN=NATGBP2,S=Nvrs
    SHOWBP S=Nvrs
    //*

## Localization

The module `NATGBPTX` is delivered in source form. It contains all error messages in English in mixed case. The messages can be translated into other languages as required. In this case, the "new" `NATGBPTX` source module has to be assembled and the module `NATGBPvr` has to be relinked.

To issue the global buffer pool messages including their variable parts in upper case, the global buffer pool parameter module `NATGBPRM` has to be assembled with the `UCTRAN` parameter set to `YES`, and the module `NATGBPvr` has to be relinked.

To relink the module `NATGBPvr`, use the following JCL:

    //SYSLIN  DD *
    SETCODE AC(1)
    SETOPT PARM(REUS=RENT)
    INCLUDE NATLIB(NATGBPMG)
    INCLUDE SMALIB(NATGBPRM)
    INCLUDE SMALIB(NATGBPTX)
    INCLUDE NATLIB(NATBPMGR)
    NAME NATGBPvr(R)
    /*

## Messages

Refer to Natural Global Buffer Pool Manager Messages in the Natural Messages and Codes documentation

### On this page

- Using a Natural Global Buffer Pool
- Prerequisites
- Operating the Natural Global Buffer Pool
- Global Buffer Pool Manager Parameter Module
- Global Buffer Pool Operating Functions
- Global Buffer Pool Function Parameters
- Examples of NATBUFFER Specifications
- Sample NATGBPvr Execution Jobs
- Localization
- Messages