Common Memory Pools

This document describes the programs that are provided to start and stop global common memory pools in Natural under BS2000/OSD and the macros that enable you to define local (or global) common memory pools in Natural under BS2000/OSD

This section covers the following topics:

Global Common Memory Pools

The following programs are provided to start and stop global common memory pools in Natural under BS2000/OSD:

Note:
In the following, vrs or vr represents the relevant product version.

CMPSTART Program

The program CMPSTART does the following:

  • It starts global common memory pools with its own start task.

  • It loads a defined module into a global common memory pool.

  • It initializes a global common memory pool.

The keyword parameters TXTSIZE and BPLIST (see below) are only valid for program CMPSTART and when starting a Natural global buffer pool.

The keyword parameters JV and JVSUFX (see below) are only valid for program CMPSTART when starting a global common memory pool.

All other keyword parameters are identical with the keyword parameters for the macro ADDON used for generating the module BS2STUB.

The following keyword parameters are available:

TXTSIZE | BPLIST | JV | JVSUFX

TXTSIZE - Buffer-Pool Text-Record Size

This keyword parameter defines the Natural buffer-pool text-record size in KB.

TXTSIZE=xx Possible values for xx are: 1, 2, 4, 8, 12, 16.
TXTSIZE=4 By default, the Natural buffer pool has a text-record size of 4 KB.
BPLIST - Preload List For Global Buffer Pool

This keyword parameter defines the name of a preload list for a Natural global buffer pool. The defined Natural programs of the preload list will be loaded into the Natural global buffer pool when the first user logs on.

BPLIST=name See the Natural profile parameter BPLIST.
JV - Create a Job Variable

This keyword parameter defines whether a job variable shall be created. This job variable enables the status of the common memory pool to be controlled in the job control language.

JV=0 The common memory pool is not ready (in creation mode).
JV=1 The common memory pool is ready (successfully enabled and initialized).

The name of the job variable has 2 parts:

  • Part 1 is the name of the common memory pool (operand of keyword parameter NAME)

  • Part 2 is the operand of keyword parameter JVSUFX (see below).

Logic of Job Variable Navigation:

When the program CMPSTART has started, a check is made whether the job variable is available. If so, the value of the job variable is set to "0". If not, the job variable is cataloged and its value is set to "0". When the common memory pool was successfully enabled and initialized, the value of the job variable is set to "1". When the global common memory pool is terminated, the job variable is erased.

JV=YES A job variable shall be created.
JV=NO By default, no job variable will be used.
JVSUFX - Suffix of the Job Variable Name

This keyword parameter defines the second part of the job variable name.

JVSUFX=xxxxxxxx Maximally 8 characters for the second part of the job variable name.
JVSUFX=.SAG.JV This is the default value.

Example: 

NAME=EDTvrsGA,TYPE=EDT,JV=YES,JVSUFX=.SAG##JV . . . . .

where vrs represents the relevant product version.

The job variable name is EDTvrsGA.SAG##JV.

Operator Commands

These operator commands terminate a global common memory pool:

/INTRtsn,STOP

or

/INTRtsn,END

This operator command displays the global common memory pool's name, position, address, size and activation time on the console: 

/INTRtsn,DPRM

This operator command terminates the global common memory pool's start task with a dump: 

/INTRtsn,DUMP

Examples:

  • To start a global load pool (environment-independent nucleus) 

    /.NATSHRE LOGON
/OPTION DUMP=YES
/SYSFILE SYSDTA=(SYSCMD)
/SYSFILE SYSOUT=LST.NATSHARE
/EXEC (CMPSTART,NATvrs.MOD)
NAME=NATSHARE,SIZE=2MB,POSI=ABOVE,ADDR=250,SCOP=GLOBAL
PFIX=YES,ALNK=NO,LIBR=NATvrs.USER.MOD
/SYSFILE SYSDTA=(PRIMARY)
/LOGOFF
/* NATSHARE IS THE NAME OF THE LINKED NATURAL REENTRANT MODULE. IT IS ALSO THE
/* NAME OF THE COMMON MEMORY POOL. THE ADDRESS OF THE GLOBAL NATURAL LOAD POOL
/* MUST BE DEFINED. THE ADDRESS MUST BE FIXED (PFIX=YES).

    where vrs represents the relevant product version.

  • To start a Natural global buffer pool 

    /.BPvrsGA LOGON
/OPTION DUMP=YES
/SYSFILE SYSDTA=(SYSCMD)
/SYSFILE SYSOUT=LST.BPvrsGA
/EXEC (CMPSTART,NATvrs.MOD)
NAME=BPvrsGA,TYPE=NAT,POSI=ABOVE,SIZE=2048KB,SCOP=GLOBAL
/SYSFILE SYSDTA=(PRIMARY)
/LOGOFF
/* FOR A NATURAL BUFFER POOL, THE OPERAND OF PARAMETER "TYPE" MUST BE DEFINED
/* AS 'NAT'.

    where vrs represents the relevant product version.

  • To start a Natural global buffer pool with ESA data space 

    /.BPvrsA LOGON
/OPTION DUMP=YES
/SYSFILE SYSOUT=LST.BPvrsGA
/SYSFILE SYSDTA=(SYSCMD)
/EXEC (CMPSTART,NATvrs.BS2.MOD)
NAME=BPvrsGA,TYPE=NAT,POSI=ABOVE,SIZE=10MB,ADDR=260,DESA=YES
DATA=32MB
/SYSFILE SYSDATA=(PRIMARY)
/LOGOFF N

    where vrs represents the relevant product version.

CMPEND Program

Program CMPEND terminates the start tasks for all global common memory pools. The input for CMPEND are the names of the global common memory pools.

Example: 

/SYSFILE SYSDTA=(SYSCMD)
/EXEC (CMPEND,NATvrs.MOD)
NATSHARE,BPvrsGA
/* THE DELIMITER FOR THE DEFINED NAMES IS ' ' OR ','.

where vrs represents the relevant product version.

Local Common Memory Pools

The following section describes the macros that enable you to define local (or global) common memory pools in Natural under BS2000/OSD:

BS2STUB Macro

The macro BS2STUB does the following:

  • Starts local common memory pools.

  • Connects to a defined global common memory pool.

  • Loads a defined module into a local common memory pool.

  • Loads dynamically called 3GL programs.

The BS2STUB macro has the following parameters:

name BS2STUB PARMOD=nn,PROGMOD=xxx
name - CSECT Name
name Specifies the CSECT name. The first three characters must not contain the value NAT.
name BS2STUB This is the default name.
PARMOD - Application Address Mode and Location

This parameter specifies whether 24 or 31 bit addressing mode is to be used.

PARMOD=nn Possible values for nn: 24 or 31 (bit).
PARMOD=31 By default, the address mode setting is 31 bit.
PROGMOD - Loading above or below the 16-MB Line

This parameter specifies whether dynamically loaded programs are to be loaded above or below the 16-MB line.

PROGMOD=ANY ANY means that the module is loaded above or below the 16-MB line. This is the default setting.
PROGMOD=24 24 means that the module is loaded below the 16-MB line.

ADDON Macro

The macro ADDON defines a common memory pool in the ADDON table of program BS2STUB. It contains the following keyword parameters which are also applicable to program CMPSTART:

ACCS | ADDR | ALNK | DATA | DESA | LIBR | LOAD | NAME | PFIX | POSI | SCOP | SIZE | STAT | TYPE | WAIT

ACCS - Access To Common Memory Pool

This parameter determines how the common memory pool can be accessed.

ACCS=READ This means the access is read-only (write-protected).

To be able to set ACCS=READ, the user ID must be authorized for the BS2000/OSD CSTMP macro in the user catalog (JOIN command with C-M=YES).

ACCS=WRITE By default, the common memory pool is write-enabled.
ADDR - Size of Common Memory Pool Address

This parameter determines the number of megabytes for the defined address of the common memory pool. The size must be specified. No default value exists.

ADDR=number number must be >=0.
ALNK - Activate AUTOLNK Function

This parameter determines whether the AUTOLNK function of the dynamic binder loader (DBL) is activated.

ALNK=NO The AUTOLNK function is deactivated.
ALNK=YES By default, the AUTOLNK function is activated.
DATA - Size of Data Space Area

This parameter can be specified in conjunction with the DESA parameter and defines the size of the data space area for the buffer pool or swap pool to be started. The following settings are possible:

DATA=nnnMB Specifies the size of the data space area in megabytes.
DATA=nnnKB Specifies the size of the data space area in kilobytes.

Using the DATA parameter in the ADDON macro

  • To start a Natural local buffer pool you specify DESA=YES and use this parameter to determine the size of the data space area in megabytes/kilobytes. The size must be specified, because no default value exists.

  • To connect a Natural global buffer pool or a global swap pool, you specify DESA=YES and omit the DATA parameter, because it has been specified for the CMPSTART Program.

Using the DATA parameter for the CMPSTART program

To start a Natural global buffer pool you specify DESA=YES and use this parameter to determine the size of the data space area in megabytes/kilobytes. The size must be specified, because no default value exists.

DESA - ESA Data Space Area

This parameter must be specified to determine whether or not an ESA data space area is to be created for a Natural buffer pool or a Natural swap pool.

DESA=YES An ESA data space area is to be created.
DESA=NO By default, no ESA data space area is to be created.

  • An ESA data space is only supported for buffer pools of TYPE=NAT or TYPE=SWP.

  • The parameter DESA=YES is relevant only if a global common memory pool (CMPSTART having its own start task) with ESA data space or a local common memory pool (BS2STUB/ADDON) with ESA data space is to be created.

  • For the connection (BS2STUB/ADDON) to an existing global common memory pool, the parameter DESA has no significance.

Warning:
An ESA data space should be created only for one global common memory pool which has its own start task. The ESA data space will no longer be available when the task that created the ESA data space terminates normally or abnormally.
LIBR - Load Library

This parameter determines from where the defined module is to be loaded. No default value exists. If the operand of parameter LIBR is not defined, only a common memory pool will be enabled (ENAMP+REQMP).

LIBR=library library is the name of the load library.
LIBR=BLSLIB The libraries with the link names BLSLIB and BLSLIB01 to BLSLIB99 are to be used.
LIBR=CLASS-4 Module is loaded as subsystem in class 4 memory.
LOAD - Method for Loading a Module into a Common Memory Pool

This parameter determines which macro shall be used for loading a module into a common memory pool.

LOAD=ASHARE The macro ASHARE will be used.

If ASHARE is defined, the operand of parameter PFIX must be YES.

LOAD=BIND By default, the macro BIND will be used..
NAME - Common Memory Pool/Module Name

This parameter determines the name of the module and/or the name of the common memory pool. The name must be specified. No default value exists.

NAME=name name is a valid name of common memory pool or module.

The maximum number of characters in a name is:

8 characters Module name (name of common memory pool); Natural buffer pool.
16 characters All other common memory pools.
PFIX - Fixed Address

This parameter determines whether or not the common memory pool's address should be fixed.

PFIX=YES The common memory pool's address should be fixed.
PFIX=NO By default, the common memory pool's address should not be fixed.

For a global Natural load pool, this parameter must be set to YES.

POSI - Position Relative to 16-MB Line

This parameter determines the position of the common memory pool, which can be above or below the 16-MB line.

POSI=ABOVE The common memory pool is to be located above the 16-MB line.
POSI=BELOW By default, the common memory pool is to be located below the 16-MB line.
SCOP - Scope of Common Memory Pool

This parameter determines the scope of the common memory pool.

SCOP=LOCAL
SCOP=GROUP
SCOP=GLOBAL

For information on the scopes of a common memory pool, see the description of the ENAMP macro in the BS2000/OSD documentation.
SCOP=GLOBAL This is the default setting.
SIZE - Size of Common Memory Pool

This parameter specifies the size of the common memory pool in megabytes/kilobytes.

SIZE=nKB
SIZE=nMB

Specifies the size of the common memory pool in n kilobytes or n megabytes.
SIZE=1MB By default, the common memory pool has a size of 1 megabyte.
STAT - Status of Common Memory Pool

This parameter determines the status of the common memory pool.

STAT=GLOBAL The status of the common memory pool is GLOBAL (started by CMPSTART).
STAT=LOCAL

The status of the common memory pool is LOCAL (started by BS2STUB).

By default, the status of the common memory pool is LOCAL.

Note:
The STAT parameter will be ignored when the program CMPSTART runs.

TYPE - Type of Common Memory Pool

This parameter determines the type of the common memory pool. The type must be specified. No default value exists.

TYPE=COM Natural DCOM pool
TYPE=EDT Editor buffer pool
TYPE=MON Natural monitor pool (SYSMON)
TYPE=NAT Natural buffer pool
TYPE=SRT Sort buffer pool
TYPE=SWP Natural swap pool
TYPE=USR User buffer pool
WAIT - Enabling or Waiting of Common Memory Pool During Application Startup

This parameter determines during startup of an application whether the common memory pool is to be enabled at once or whether the common memory pool is to wait for a request from Natural and is enabled then.

WAIT=YES The common memory pool is to wait for a request from Natural and is enabled then.
WAIT=NO By default, the common memory pool is to be enabled at once.

Note:
The WAIT parameter will be ignored when the program CMPSTART runs.

ADDEND Macro

The macro ADDEND defines the end of macro ADDON's definitions. There are no parameters for ADDEND.

Example of Assembling Macro BS2STUB 

BS2STUBA BS2STUB PARMOD=31,PROGMOD=24            31-BIT ADDRESSING MODE,
*                                                LOAD 3GL PROGRAMS BELOW
* +--------------------------------------------------------------------+ 
* I Define the Natural global load pool with Name NATSHARE 
* +--------------------------------------------------------------------+
         ADDON NAME=NATSHARE,STAT=GLOBAL 
* +--------------------------------------------------------------------+
* I Define the Natural local swap pool 
* +--------------------------------------------------------------------+
         ADDON NAME=SWAPvrsLA,TYPE=SWP,SIZE=16MB,STAT=LOCAL,POSI=ABOVE
* +--------------------------------------------------------------------+
* I Connecting a Natural global buffer pool with ESA data space 
* +--------------------------------------------------------------------+
           ADDON NAME=BPvrsGA,TYPE=NAT,STAT=GLOBAL
* +--------------------------------------------------------------------+
* I Creating/Connecting a Natural local buffer pool with ESA data space
* +--------------------------------------------------------------------+
         ADDON NAME=BPvrsLA,TYPE=NAT,POSI=ABOVE,SIZE=10MB,             -
               STAT=LOCAL,SCOP=LOCAL,DESA=YES,DATA=32MB
         ADDEND
         END

where vrs represents the relevant product version.