Using the Buffer Pool Monitor (NATBPMON)

This document covers the following topics:

Invoking the NATBPMON Utility
NATBPMON Commands
Displaying the Objects in the Buffer Pool
Specifying a Pattern
Displaying the Buffer Pool Settings
Statistical Information About the Buffer Pool

See also Natural Buffer Pool which provides general information on the buffer pool and explains how to start the buffer pool.

Warning:
This utility should not be generally accessible to all users of Natural, because its use can cause damage to the work of other users of the buffer pool.

Invoking the NATBPMON Utility

You can invoke the NATBPMON utility either for the default buffer pool NATBP or for another existing buffer pool.

The NATBPMON administrator can always invoke the utility. If the maximum buffer pool user limit is reached, the administrator accesses the utility as an emergency user. Only one additional buffer pool administrator can use NATBPMON at a time. You can define a Natural buffer pool administrator in the local configuration file in the Configuration utility.

Start of instruction set To invoke the NATBPMON utility

If the default buffer pool NATBP is to be used, enter the following command in the command line:
```
NATBPMON
```
Or:
If another buffer pool is to be used, enter the following command in the command line:
```
NATBPMON BP=buffer-pool-name
```
The following prompt appears:
```
NATBPMON>
```
If you want the NATBPMON utility to terminate with an appropriate error message, add GIVERC to your command in the command line.

NATBPMON Commands

The following commands can be entered at the NATBPMON prompt:

Command	Description
`CLEAR`	This is the same as the `ZERO` command.
`CORPSES`	Displays the list of corpses. A corpse is an object that has been deleted, but was still being used in the buffer pool when its deletion took place. Once this object is no longer used, it will automatically disappear from the list of corpses. Note: The column cusr which is shown with the `DIR` command indicates if an object is being used.
`DELETE {pattern\|[*]}`	Deletes an object from the buffer pool. All objects can be deleted from the buffer pool by using an asterisk (*). A pattern is used to specify a collection of objects, similar to current operating systems which allow the specification of a class of files with wildcards. For further information, see Specifying a Pattern.
`DIR {pattern\|[*]}`	Displays a directory containing all objects in the buffer pool. For further information, see the sections Specifying a Pattern and Displaying the Objects in the Buffer Pool.
`DUMP`	Used for error analysis. Important: Do not use this command unless you are requested to do so by Software AG Support.
`EXIT`	Exits the `NATBPMON` utility.
`FIN`	Exits the `NATBPMON` utility. This is the same as the `EXIT` command.
`HELP`	Displays a list of all available commands of the `NATBPMON` utility.
`IPCRM`	Frees the resources allocated to the buffer pool. This command should only be used following a `SHUTDOWN` command when there are no active users.
`KILL n`	Kills the specified buffer pool user. `n` is the number of the user to be "killed". This number corresponds to the index number as displayed by the `WHO` command.
`PARAM`	Displays the buffer pool settings. For further information, see Displaying the Buffer Pool Settings.
`QUIT`	Exits the `NATBPMON` utility. This is the same as the `EXIT` command.
`SHUTDOWN [FORCE [grace-period]]`	Without the option `FORCE`: Shuts down the buffer pool. No new processes will be able to use the buffer pool once this command has been issued. The `NATBPMON` utility is able to run with a buffer pool which has the shutdown status "pending"; all commands of the `NATBPMON` utility are available in this case. As soon as all users have stopped using the buffer pool, the buffer pool's resources can be deleted with the `IPCRM` command. The option `FORCE` requires `NATBPMON` to be executed with super user rights. After `SUDO` or `SU` has validated the password and given control to `NATBPMON`, any new sessions will be inhibited to log in and the terminate signal `SIGTERM` will be sent to all active Natural sessions. `NATBPMON` will then wait the number of seconds defined with the parameter `grace-period` before the IPC resources used by the buffer pool are removed from the system. If the optional parameter `grace-period` is omitted (or set to 0), `NATBPMON` will wait until all processes performed their cleanup processing. This process can be considered as an emergency stop. If it is executed without super user rights, no action takes place and a message reporting the incapability to execute the command is sent. See also Shutting Down and Restarting the Buffer Pool. Note: To start the buffer pool after shutdown, you can use the utility `NATBPSRV`.
`STATUS`	Displays statistical information about the buffer pool. For further information, see Statistical Information About the Buffer Pool.
`SWAP`	Only available for a read-only buffer pool. Tags a read-only buffer pool as "obsolete". All Natural sessions attached to such a buffer pool will detach from that buffer pool and attach to the alternate buffer pool.
`VERIFY [NOW\|ON\|OFF]`	This command cannot be used on a read-only buffer pool, because the required exclusive access is not available for it. Performs, enables, or disables buffer pool consistency checks. If the command is entered on its own or with the `NOW` option, any existing consistency error is reported, otherwise consistency checks are performed and the result is returned. If the option `ON` is provided, consistency checks are performed after each consolidation (see `Consolidations` in the output of the `STATUS` command) until a consistency error is detected or until disabled again with the `OFF` option. By default, no automatic consistency checks are performed.
`WHO`	Displays a list of all users who are using the buffer pool. The following statistics are displayed: a number that the `NATBPMON` utility automatically assigns to each buffer pool user (index) and the user ID, terminal ID and process ID of the process using the buffer pool (tid).
`WRITE`	Writes a buffer pool object onto the disk. You are prompted to specify an index and a file name. Note: The column "indx" which is shown with the `DIR` command shows the index numbers.
`ZERO`	Resets to 0 all counters that are displayed by the `STATUS` command.

Displaying the Objects in the Buffer Pool

The DIR command displays a list of objects. This list contains the following information:

Column Explanation

indx A number that the NATBPMON utility automatically assigns to an object when it is loaded into the buffer pool.

cusr The current number of users that are using an object in the buffer pool.

pusr The peak number of concurrent activations of an object in the buffer pool.

nusg The number of times an object has been activated in the buffer pool.

Specifies whether an object is being loaded into the buffer pool from the system file. Has one of the following values:
0	The object is not being loaded.
1	The object is being loaded.

size Specifies the size (in bytes) of an object in the buffer pool.

gpv The version number of the generated program.

key

Specifies the following information about an object:
D	Database ID.
F	File number.
L	The library in which the object is located.
N	The name of the object. Numbers and the at sign (@) indicate chunks of FILEDIR.SAG for the currently loaded library.
K	The kind of object (`G`=generated object module; `S`=source; `D`=part of FILEDIR.SAG).
T	The object type (which is blank when `D` is shown in the `K` field).

When the DIR command is issued, all objects in the pool will be displayed in a notation similar to the following:

indx:    index of the element  
 cusr:    current number of concurrent users  
 pusr:    peak number of concurrent users  
 nusg:    number of usages  
 g   :    set if object is generating
 gpv :    version of generated program

indx | cusr | pusr |  nusg  |  g  |  size  |  gpv  |  key
-----+------+------+--------+-----+--------+-------+---------------------------------------------------
 1   |  0   |  1   |    4   |  0  |   920  |       |  (D=99 F=101 L="DEMO" N="SEL-MAP" K='G' T='M') 
 2   |  1   |  7   |    2   |  0  |  3096  |       |  (D=99 F=101 L="DEMO" N="EMWND" K='G' T='P') 
 3   |  4   |  9   |    4   |  0  |   604  |       |  (D=99 F=101 L="DEMO" N="HDR" K='G' T='P') 
 4   |  2   |  3   |    7   |  0  |   412  |       |  (D=99 F=101 L="RPA" N="MMUPROG1" K='G' T='P') 
 5   |  0   |  1   |    5   |  0  |   372  |       |  (D=99 F=101 L="RPA" N="MMUPROG2" K='G' T='P') 
 6   |  0   |  5   |    4   |  0  |   372  |       |  (D=99 F=101 L="RPA" N="MMUPROG3" K='G' T='P')

Specifying a Pattern

A pattern can be specified with the commands DIR and DELETE. The examples in this section apply to the DIR command.

To select some objects, it is possible to restrict the values of certain key fields by specifying a matching pattern expression.

To restrict the allowed field values of a given field, the following pattern notation must be used:

name=expression

You can specify multiple patterns by separating them with a comma.

The specified patterns must all match their corresponding fields in order to accept the entire key.

The expression accepts the specification of the wildcard characters "*" and "?".

The character "*" matches any or no occurrences of a sequence of characters, and the wildcard character "?" matches exactly one specific character.

Examples

To select all objects of type P in the sample above, the following command would be used:

DIR T=P

To select all programs in the demo library, the following command would be used:

DIR T=P, L=DEMO

To select all objects containing an M in their name, the following command would be used:

DIR N=*M*

Displaying the Buffer Pool Settings

The following settings are displayed with the PARAM command:

SHM active since .......: 13-AUG-2024 19:39:21, Version 9.3(932) BP version 2
Last time cleared ......: 13-AUG-2024 19:39:21

Bpid ...................: TESTRW
Readonly ...............: no
Shmkey .................: 0x39211291
Semkey .................: 0x39211291
Memsize ................:      10485748
Maxusers ...............:           200

SHM active since	Date and time when the buffer pool was started, the version number of the program that started it and created the shared memory, and the internal buffer pool format version that is incremented on every structural change.
Last time cleared	Date and time when the buffer pool statistical information was most recently cleared (either implicitly on buffer pool creation, or explicitly via the `CLEAR` or `ZERO` command).
Bpid	Buffer pool ID.
Readonly	Indicates whether this is a special buffer pool which only allows read access.
Shmkey	Unique name used to create a buffer pool or to connect to a buffer pool.
Semkey	Unique name used to synchronize accesses to the buffer pool memory.
Memsize	Size of the available shared memory.
Maxusers	Maximum number of users that can have simultaneous access to the buffer pool.

See Buffer Pool Assignments in the Configuration Utility documentation.

Statistical Information About the Buffer Pool

The following statistics are displayed with the STATUS command:

Buffer Pool Monitor version 9.3(932F00) of 07/18/2024
NATBPMON>st
SHM active since .......: 13-AUG-2024 19:39:21, Version 9.3(932F00)
Last time cleared ......: 13-AUG-2024 19:39:21
Bpid ...................: TESTRW
Allocated memory (b) ...:        255280 Max users ............:           200
Smallest allocation ....:            48 Current users ........:             2
Largest allocation .....:         97624 Peak users ...........:             2
Free memory (b) ........:      10230480 Dead users purged ....:             0
Smallest free ..........:           368
Largest free ...........:      10228240 Peak parallel usages .:             1

Dormant objects ........:            12 Smallest object (b) ..:           108
Active objects .........:             0 Largest object (b) ...:         31228
Generating objects .....:             0 Total object sizes ...:        120638
Obsolete objects .......:             0
Dormant objects purged .:             0 Object reusage factor :          6.29

Attempted locates ......:           183 Stored objects .......:             0
Attempted fast locates .:            79 Loaded objects .......:            24
Successful fast locates :            62 Activated objects ....:           151
Percent ................:         78.48 Aborted loads ........:             0

Read operations ........:           334 Update operations ....:            81
Sync read operations ...:             0 Consolidations .......:             5

General Information
Buffer Pool Monitor version	Version of the buffer pool including its fix level (enclosed in brackets as `vrsFnn`, where `vrs` is the buffer pool version and `nn` is its fix level).
SHM active since	Date and time when the buffer pool was started, and the version number and fix level of the program that started it and created the shared memory.
Last time cleared	Date and time when the buffer pool statistical information was most recently cleared (either implicitly on buffer pool creation, or explicitly via the `CLEAR` or `ZERO` command).
Bpid	Buffer pool ID. If applicable, the read-only and swap status is shown enclosed in brackets.
Memory Allocation
Allocated memory (bytes)	Total of all allocated memory.
Smallest allocation	Smallest amount of allocated memory.
Largest allocation	Largest amount of allocated memory.
Free memory (bytes)	Total of all free memory.
Smallest free	Smallest amount of contiguous free memory.
Largest free	Largest amount of contiguous free memory.
User Statistics
Max users	Maximum number of users that can have simultaneous access to the buffer pool. See Buffer Pool Assignments in the Configuration Utility documentation.
Current users	Number of users currently using the buffer pool.
Peak users	Peak number of users that have been using the buffer pool.
Dead users purged	Number of inactive users that have been deleted from the buffer pool. This number should be close to 0 (zero). An increment of this number indicates that entries for buffer pool users (i.e. Natural sessions) were canceled or killed unconditionally. Each time an entry for such a user is identified by the buffer pool manager, this number is incremented and cleanup is performed to remove residuals which have been left in the buffer pool by a canceled session.
Peak parallel usages	The maximum number of users that have been concurrently using one of the objects in the buffer pool.
Object Use Statistics
Dormant objects	Number of available, but inactive objects. These objects are in the buffer pool, but are not being used. They are available for later use and will become active objects as soon as a buffer pool user requests their availability.
Active objects	Number of active objects. These objects are currently in use by one or more buffer pool users.
Generating objects	Number of objects that are currently being loaded into the buffer pool. These objects will become available as soon as the load operation completes.
Obsolete objects	Number of objects that are to be deleted from the buffer pool, but are still being used. These objects can be displayed by using the `CORPSES` command. An obsolete object is removed from the buffer pool as soon as all users who activated this object have released this object. In a production environment, this number should be 0 (zero). A value other than zero indicates that objects were deleted either using the `DELETE` command of `NATBPMON` or became obsolete because new objects were created (for example, due to a `CATALOG` command).
Dormant objects purged	The number of unused objects deleted from the buffer pool to make room for newly loaded ones.
Object reusage factor	Average number of times an object was reactivated. This number is the ratio of the number of object activations to the number of objects loaded into the buffer pool.
Object Size Statistics
Smallest object (bytes)	Size of smallest object in the buffer pool.
Largest object (bytes)	Size of largest object in the buffer pool.
Total object sizes	Total size of all objects in the buffer pool.
Locate Statistics
Attempted locates	Number of successful and failed object locates. This number tells you how many times the buffer pool manager was asked to locate an object in the buffer pool.
Attempted fast locates	Number of attempted activations with known slot. This is the number of object activations when the former location of an object was known. It is highly probable that an object can be found in the same place in the buffer pool when it is reactivated.
Successful fast locates	Number of successful fast locates.
Percent	Percentage of successful fast locates.
Object Loading Statistics
Stored objects	The number of objects stored in the buffer pool. This is the number of objects that were stored into the buffer pool and which were not loaded from the system file.
Loaded objects	The number of objects loaded from the system file. Each time an object is not found in the buffer pool, it is loaded from the system file. This number is increased each time an object is successfully loaded into the buffer pool.
Activated objects	The number of activated objects. Activation is the process of marking an object which is found in the buffer pool as "in use" by a buffer pool user.
Aborted loads	The number of load operations that were aborted due to memory shortages within the buffer pool, or due to an error when loading an object into the buffer pool. This number should not vary in a noticeable way.
Operation Type Statistics
Read operations	Not available for read-only buffer pools or if only a Natural Runtime license is found. The total number of read operations, both unsynchronized and synchronized. Unsynchronized read operations are fast. Furthermore, multiple operations of this type can be executed in parallel.
Sync read operations	Not available for read-only buffer pools or if only a Natural Runtime license is found. The number of read operations that needed to be synchronized with update operations. Operations of this type cannot be executed in parallel with any other operations.
Update operations	Not available for read-only buffer pools or if only a Natural Runtime license is found. The number of update operations. These are operations that explicitly request exclusive access to the buffer pool (for example to modify it or to obtain a data snapshot). Operations of this type cannot be executed in parallel with any other operations.
Consolidations	Not available for read-only buffer pools or if only a Natural Runtime license is found. For performance reasons and to allow multiple read operations to be executed in parallel, some internal administrative tasks associated with read and update operations are not performed immediately. Instead, they are combined and performed asynchronously in a later consolidation operation. The value shown here is the number of such operations. Operations of this type cannot be executed in parallel with any other operations.