Natural Global Buffer Pool under z/VSE

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

The section covers the following topics:

Certain parts of the Natural global buffer pool are identical under z/VSE and z/OS. These parts are concentrated in a separate section (see Common GBP Operating Functions under z/OS and z/VSE) which covers the following topics:

Using a Natural Global Buffer Pool

Purpose

The Natural global buffer pool is a segment of storage assigned from the z/VSE system GETVIS storage above 16 MB (or from storage below, if requested), used by Natural to load and execute Natural programs. The Natural global buffer pool is allocated in storage key 9, so that all participating partitions have write-access to it.

Benefits

Using a global buffer pool, multiple Natural sessions under different TP monitors (multiple copies of CICS, Com-plete, 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

  1. The global buffer pool manager module NATGBPvr must have been linked, and the start and stop jobs must have been created. See the corresponding step in the section Installing Natural on z/VSE in the Installation for z/VSE documentation.

  2. A Natural global buffer pool under z/VSE requires the subsystem storage protection facility of an ESA/390 or compatible processor. Consequently, it also requires a minimum operating system level of z/VSE Version 2 Release 4 for support of this hardware feature.

Operating the Natural Global Buffer Pool

The global buffer pool is operated by the program NATGBPvr which is contained in and executed from the Natural load library.

The following topics are covered below:

Setting Up the Natural GBP

The functions available from the operating program NATGBPvr are activated in that they are

  • provided by a parameter card (PARM=),

  • read from a file (see below)

  • or supplied by the operator (AR command MSGxx with xx being the z/VSE partition ID) unless NATGBPvr has not been terminated.

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

You may enter:

  • one of the functions described in the section Common GBP Operating Functions under z/OS and z/VSE

  • or a reference to an input file with CF=dlbl-name, where dlbl-name represents a DLBL name defined in the JCL or the z/VSE (partition) standard labels. 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. An asterisk (*) for dlbl-name indicates to the module NATGBPvr that input has to be read from SYSIPT. A file is processed until End-Of-File (EOF).

    Example: PARM='CF=SYSIN1'

If the parameter field is not supplied or is blank, the commands will be read from SYSIPT 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 and is logged to SYSLST.

Starting the Natural GBP Operating Program

To start the program NATGBPvr, submit a job that 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 operating 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.

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 further information on product versions, see Version in the Glossary.

Example 1:

// JOB GBPSTART 
/*
/* 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.
/* 
// LIBDEF PHASE,SEARCH=SAGLIB.NATLIB
// EXEC NATGBPvr,SIZE=NATGBPvr,PARM='BPN=NATvrGBP,N=(1000)'
/*
// EXEC LISTLOG
/&

Example 2:

// JOB GBPRES 
/* 
/* 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 AR command MSG partition-id: 
/* the job GBPRES will then prompt for console input.
/*
// LIBDEF PHASE,SEARCH=SAGLIB.NATLIB
// EXEC NATGBPvr,SIZE=NATGBPvr,PARM='BPN=GBP,N=(,BL,1),S=SAGS,R=Y'
/* 
// EXEC LISTLOG
/&

Example 3:

// JOB 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. 
/*
// LIBDEF PHASE,SEARCH=SAGLIB.NATLIB
// EXEC NATGBPvr,SIZE=NATGBPvr,PARM='FSHUT,BPN=GBP'
/*
// EXEC LISTLOG
/&

Example 4: 

// JOB GBPSTRT2 
/* Read commands from SYSIPT:
/* 
/* 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.
/*
/* If the buffer pools should shut down, wake up the sleeping job by the MSG partition ID
/* and enter the parameter "CF=*" to execute the corresponding FSHUTs. 
/*
// LIBDEF PHASE,SEARCH=SAGLIB.NATLIB
// EXEC NATGBPvr,SIZE=NATGBPvr 
CREATE,BPN=NATGBP1,S=Nvrs,N=(1M),BPC=2M
CREATE,BPN=NATGBP2,S=Nvrs,N=(2M)
SHOWBP S=Nvrs
/*
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 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 NATGBPvr has to be relinked.

To relink NATGBPvr, use the following JCL: 

// OPTION CATAL,LIST 
ACTION NOAUTO,SMAP
PHASE NATGBPvr,*   
INCLUDE NATGBPMG
INCLUDE NATGBPRM
INCLUDE NATGBPTX
INCLUDE NATBPMGR 
ENTRY CMSTART 
/*

Messages

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