Version 4.2.6
 —  Operations  —

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 following topics are covered:

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

See also:


Using a Natural Global Buffer Pool

Definition

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.

Top of page

Operating the Natural Global Buffer Pool

The following topics are covered below:

Installing the Natural GBP Operating Program

Note:
vrs stands for version, release and system maintenance level of the product.

The global buffer pool is operated by the program NATGBPvr which must be executed from an authorized library.

During the installation of Natural, the modules NATGBPvr is linked into an APF-authorized library.

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 Authorized Services Manager is mandatory. The Authorized Services Mangager ist 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 programm calls to program execution time).

Setting up the Natural Global Buffer Pool

The functions available from NATGBPvr are activated in that they are

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

You may enter:

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 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, NATGBPvr terminates, unless

NATGBPvr will return one of the following condition codes:

0 All functions executed successfully.
20 An error has occurred; see the message log for details.

Top of page

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 stands for the relevant version, release, system maintenance level numbers. For further 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 3 global buffer pools (subsystem ID Nvrs) with name
//*   NATGBP1 - size=1024KB and a cache with size 2048KB
//*   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, send 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  
//*

Top of page

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:

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

Top of page