Message Buffer Pool

#### Search Results

Search

# Message Buffer Pool

This part describes the use of the message buffer pool.

Note
The message buffer pool is available under z/OS.

The following topics are covered:

- Purpose

- Prerequisites

- Operating the Message Buffer Pool

- Sample NATMBPvr Execution Jobs

- Message Buffer Pool Operating Functions

- Function Parameters

- Messages

## Purpose

The message buffer pool is a cache memory which is used to store the Natural system messages and the user texts.

Before an error message is output, Natural first checks whether the corresponding message text is available in the message buffer pool. If so, this text is output. Otherwise, the error message would be read from the database, and would be stored in the message buffer pool.

The message buffer pool is available only as a global buffer pool. Its use is optional, and is controlled by the Natural profile parameter `BPI` or the corresponding macro `NTBPI`. When used, the message buffer pool is allocated in a data space.

## Prerequisites

The following prerequisites must be met if you want to use the message buffer pool:

1. The module `NATMBPvr` 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 message buffer pool must have been created and started; see the corresponding step in Installing Natural on z/OS in the Installation for z/OS documentation.

3. The keyword subparameter `TYPE` of profile parameter `BPI` or macro `NTBPI` must be set to `MSG`.

## Operating the Message Buffer Pool

The message buffer pool is operated by the program `NATMBPvr` which must be executed from within an Authorized Program Facility (APF) library.

The following topics are covered below:

- Setting up the Message Buffer Pool

- Starting the Message Buffer Pool Operating Program

- Stopping the Message Buffer Pool 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.

### Setting up the Message Buffer Pool

The functions available from `NATMBPvr` (see also Function Parameters) are activated in that they are

- provided by a parameter card (`PARM=`),

- read from a file (see below),

- or supplied by the `MODIFY` operator command unless `NATMBPvr` has not been terminated.

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

You may enter:

- one of the functions described in the section Common Message Buffer Pool Operating 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 parameter card, from file input or from operator console input is displayed on the operator console.

### Starting the Message Buffer Pool Operating Program

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

### Stopping the Message Buffer Pool Operating Program

The program `NATMBPvr` is stopped by using the `TERMINATE` function (see Common Message Buffer Pool Operating Functions) or, in case of emergency, by using the `CANCEL` operating program.

## Sample NATMBPvr Execution Jobs

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

- Example 1

- Example 2

- Example 3

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

### Example 1

    //MBPSTART JOB
    //*
    //* Starts a message buffer pool with the name NATvrMBP and
    //* a size of 10 MB.
    //* The subsystem used is NATv.
    //*
    //STEP EXEC PGM=NATMBPvr,PARM='BP=NATvrMBP,SI=10'
    //SETPLIB DD DISP=SHR,DSN=USER.APF.LINKLIB

### Example 2

    //MBPRES JOB
    //*
    //* Starts a message buffer pool with the name MBP and a default size of
    //* 100 MB. The subsystem used is SAGS.
    //*
    //STEP EXEC PGM=NATMBPvr,PARM='BP=MBP,S=SAGS'

### Example 3

    //MBPSTRT2
    //* Read commands from SYSIN1:
    //*
    //* Start 2 message buffer pools (subsystem ID Nvrs) with name
    //*   NATMBP1 - size=1000MB
    //*   NATMBP2 - size=2000MB
    //* If the buffer pools should shut down, send operator command MODIFY with
    //* parameter "CF=SYSIN2" to execute the corresponding FSHUTs.
    //*
    //STEP EXEC PGM=NATMBPvr,PARM='CF=SYSIN1'
    //SYSIN1  DD *
    CREATE,BP=NATMBP1,S=Nvrs,SI=1000M
    CREATE,BP=NATMBP2,S=Nvrs,SI=2000M
    SHOWBP S=Nvrs
    //SYSIN2 DD *
    FSHUT,BP=NATMBP1,S=Nvrs
    FSHUT,BP=NATMBP2,S=Nvrs
    //*

## Message Buffer Pool Operating Functions

The following functions are available:

- HELP - Shows an overview of the available syntax

- CREATE - Create a Message Buffer Pool

- FSHUT - Shut Down Message Buffer Pool

- TERMINATE or STOP- Terminate Message Buffer Pool Operating Program

- ZAPS - Display Zaps Applied to Message Buffer Pool

Note
The function names can be abbreviated. It is sufficient to use the first character only, for example `T` for `TERMINATE`.

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

### CREATE - Create a Message Buffer Pool

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

### FSHUT - Shut Down Message Buffer Pool

The message buffer pool with the specified parameters is deallocated.

### TERMINATE or STOP- Terminate Message Buffer Pool Operating Program

The message buffer pool operating program is terminated. Prior to that, all active message buffer pools are deallocated.

### ZAPS - Display Zaps Applied to Message Buffer Pool

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

## Function Parameters

The functions of the message buffer pool operating program can be controlled with the aid of parameters. These parameters can be specified in any sequence. They can be abbreviated.

The following parameters are available:

`BPNAME` | Name of message buffer pool.
`BPLIST` | Name of the preload list (optional).
`SUBSID` | Natural subsystem ID.
`SIZE` | Size of the message buffer pool.

Note
The underlined part of the parameter name marks the shortest possible abbreviation.

### BPNAME - Name of Message Buffer Pool

`BPNAME=value` specifies the name of the message buffer pool to be created.

Value | Explanation
--- | ---
8 bytes | The name of the message buffer pool. Note If the specified name is shorter than 8 bytes, blanks will be appended to it.
`MTBP` | This is the default value.

### BPLIST - Name of Preload List

`BPLIST=value` specifies the name of the optional 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. There is no default value.

### SUBSID - Natural Subsystem ID

`SUBSID=value` specifies the ID of the Natural subsystem.

Value | Explanation
--- | ---
4 bytes | The ID of the Natural subsystem. Note If the specified name is shorter than 8 bytes, blanks will be appended to it.
`NATv` | This is the default value, where `v` is the first digit of the current Natural version.

### SIZE - Size of Message Buffer Pool

`SIZE=value` specifies the size of the message buffer pool.

Value | Explanation
--- | ---
1 - 2000 MB | The size of the message buffer pool.
`1` | This is the default value.

Note
A 1 MB Message Buffer Pool can hold up to 7000 error messages.

## Messages

Refer to Message Buffer Pool Messages in the Messages and Codes documentation.

### On this page

- Purpose
- Prerequisites
- Operating the Message Buffer Pool
- Sample NATMBPvr Execution Jobs
- Message Buffer Pool Operating Functions
- Function Parameters
- Messages