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

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:

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.

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:

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.
100 This is the default value.

Messages

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