Natural Buffer Pool

This document covers the following topics:


General Information

The Natural buffer pool is used to share Natural objects between several Natural processes that access objects on the same computer. It is a storage area into which compiled Natural programs are placed in preparation for their execution. Programs are moved into and out of the buffer pool as Natural users request Natural objects.

Since Natural generates reentrant Natural object code, it is possible that a single copy of a Natural program can be executed by more than one user at the same time. For this purpose, each object is loaded only once from the system file into the Natural buffer pool, instead of being loaded by every caller of the object.

The following topics are covered below:

Objects in the Buffer Pool

Objects in the buffer pool can be any executable objects such as programs and dialogs. The following executable objects are only placed in the buffer pool for compilation purposes: local data areas, parameter data areas and copycodes.

When a Natural object is loaded into the buffer pool, a control block called a directory entry is allocated for that object. This control block contains information such as the name of the object, to which library or application the object belongs, from which database ID and Natural system file number the object was retrieved, and certain statistical information (for example, the number of users who are concurrently executing a program).

Resource Handling

Resources are loaded into the buffer pool if they reside in a library of a Natural system file (for example, FUSER) and if their names do not exceed 32 characters (including the file extension).

Each resource that resides in the directory which is assigned to the environment variable NATGUI_BMP or whose name is longer than 32 characters, is loaded directly into the Natural process every time it is accessed (that is: the resource is not loaded into the buffer pool).

Multiple Buffer Pools

Depending on the individual requirements, it is possible to run different buffer pools of the same Natural version simultaneously on the same computer.

For each buffer pool, synchronization can be enabled in the Configuration Utility (see also Setting up a Buffer Pool below). All buffer pools which contain objects from the same system file and for which synchronization has been enabled are then synchronized automatically.

Important:
If the system file resides on a shared drive, synchronization only works if the file system on the server is NTFS.

The following applies when synchronization has been enabled: If an object that is loaded to more than one buffer pool is modified by one Natural process, it is first marked as invalid. When the object is no longer used by any process, it is deleted from the buffer pool. The next time this object is requested by a process, it will be loaded into the buffer pool again.

Storing Objects in the Buffer Pool

When a user executes a program, a call is made to the buffer pool manager. The directory entries are searched to determine whether the program has already been loaded into the buffer pool. If it does not yet exist in the buffer pool, a copy is retrieved from the appropriate library and loaded into the buffer pool.

When a Natural object is being loaded into the buffer pool, a new directory entry is defined to identify this program, and one or more other Natural objects which are currently not being executed may be deleted from the buffer pool to make room for the newly loaded object.

For this purpose, the buffer pool maintains a record of which user is currently using which object, and it detects situations in which a user exits Natural without releasing all its objects. It dynamically deletes unused or out-of-date objects to accommodate new objects belonging to other applications.

Fast Locate

When a Natural object is executed, the Natural runtime system remembers the object name, the library (name, database ID and file number) and the address of the corresponding buffer pool directory entry. This data is referred to as "fast locate information".

When a Natural object is executed again, the Natural runtime system passes the fast locate information to the buffer pool manager and performs a time-saving fast locate call. A fast locate call bypasses the normal locate procedure including the steplib search and the search in the buffer pool. It is therefore the most efficient way to locate an object. It provides significantly better performance of subsequent program loads especially when steplib libraries are involved in multi-user environments.

The address of an object saved as fast locate information is no longer valid once the object is removed from the buffer pool, overwritten by another object or reloaded to another buffer pool location. If the fast locate call does not find the object at the given address, the object is searched in the buffer pool. If not found in the buffer pool, the object is reloaded from the system file.

This section covers the following topics:

Fast Locate at Object Resume

Fast locate calls are issued when an object is accessed or resumed. An object resume operation is performed, for example, when an object continues to execute after a CALLNAT statement. For object resume operations, the Natural runtime system keeps fast locate information of the calling object for each program level on the internal stack.

Fast Locate Table

The Natural runtime system keeps fast locate information about each accessed object in the internal fast locate table. The fast locate table also contains information about all libraries in which an object was searched. For a subsequent call, a fast locate is issued if the current library and associated steplibs are still the same.

The fast locate table is a hash table. The entries can be directly accessed without searching for an object name. The hash value is calculated from the object name. It determines the slot index number for the object. If another object has the same hash value (hash collision), a normal locate call is performed and the entry in the fast locate table is overwritten.

If an object for the library given in the fast locate table is neither found in the buffer pool nor in the system file (which means that the object has been deleted or moved to another library), a normal locate call with the full steplib search is scheduled automatically.

The Locate Statistics of the buffer pool monitor shows how many locate attempts were made and how many of these attempts were fast locate calls (see Statistical Information About the Buffer Pool). These values can be used to review the efficiency of the fast locate table. If the fast locate table is activated for an application that calls the same objects many times, and if these objects are contained in a steplib library, the following applies:

  • The number of locate attempts should decrease significantly (compared with a deactivated fast locate table).

  • The number of fast locate attempts should be close to the number of locate attempts.

Fast Locate Table with BPSFI=ON

If the BPSFI (Object Search First in Buffer Pool) profile parameter is set to ON, the fast locate table is activated by default. It is initialized at the start of the Natural session and it is not cleared implicitly during the running session. It can be deactivated or cleared with the application programming interface USR3004N as described in the section Maintaining the Fast Locate Table.

Performance with BPSFI=ON

In the following example, a subprogram is called 3,000,000 times. In the first test, the subprogram is found in the current library, then in Steplib 1, Steplib 2, and so on. The red line shows the elapsed time needed for the program load with a deactivated fast locate table, the green line with an activated fast locate table.

graphics/ops-bp-bpsfi-on.png

The diagram above shows that there is no performance improvement if the object is found in the current library. The more steplibs there are involved in object search operations, the higher is the performance improvement. For five steplibs, the program loads require less than half the time.

Fast Locate Table with BPSFI=OFF

If the BPSFI profile parameter is set to OFF, the fast locate table is deactivated by default. It can be activated or cleared with the application programming interface USR3004N as described in the section Maintaining the Fast Locate Table. It is initialized at the start of the Natural session and it is implicitly cleared when the application is back on Program Level 0 (NEXT prompt).

Activation of the fast locate table for BPSFI=OFF can lead to unexpected results in the following scenario:

  • The list of steplibs contains the libraries S1 and S2 whereby S1 is searched before S2.

  • An object from S2 is accessed during the current Natural session.

  • Another Natural session copies a new version of this object into S1.

If the application is still running (not back on Program Level 0 in between) and the object is accessed again, the new version of the object will not be used.

If you want to activate the fast locate table when BPSFI=OFF is set, make sure that the scenario described above cannot occur.

If BPSFI=ON is set, object names should always be unique across all libraries involved in object search operations. This also guarantees that such scenarios do not occur.

Performance with BPSFI=OFF

In the following example, a subprogram is called 3,000,000 times. In the first test, the subprogram is found in the current library, then in Steplib 1, Steplib 2, and so on. The red line shows the elapsed time needed for the program load with a deactivated fast locate table, the green line with an activated fast locate table.

graphics/ops-bp-bpsfi-off.png

The diagram above shows that there is no performance improvement if the object is found in the current library. The more steplibs there are involved in object search operations, the higher is the performance improvement. Since the search operation on the system file is considerably slower than the search in the buffer pool, the improvement is much higher than the corresponding improvement when BPSFI=ON set. For five steplibs, the program load is about 20 times faster. If the fast locate table is activated, in general, the time needed for subsequent program loads for BPSFI=OFF is about the same as for BPSFI=ON, and it is always about the time needed to search for an object in the current library only.

Performance in a Multi-User Environment

If an object is searched in a (read/write) buffer pool or on the system file, lock operations are issued to ensure that no other session performs changes concurrently. The lock operations serialize the access to the buffer pool, one session is processed after the other.

The fast locate table reduces the number of locate calls if steplibs are involved. Therefore, less lock operations are required, and overall performance of the buffer pool is improved.

In the following example, a subprogram is called 3,000,000 times, and the subprogram is always found in Steplib 5. In the first test, only one session is active. In the second test, two sessions execute the same application simultaneously, then three sessions, and so on. The red line shows the elapsed time needed for the program load with a deactivated fast locate table, the green line with an activated fast locate table.

graphics/ops-bp-bpsfi-on-session.png

As indicated in Performance with BPSFI=ON, the program load with a single session is more than 2 times faster if the object is found in Steplib 5 with BPSFI=ON set. If multiple sessions access the buffer pool simultaneously, the tests show that the performance can be 3 to 5 times faster.

Maintaining the Fast Locate Table

Usage of the fast locate table can be activated and deactivated by calling the application programming interface (API) USR3004N. The API can also be used to get the current state of the fast locate table, to clear the fast locate table and to receive statistical data. The API is delivered in the SYSEXT library. For more information on using APIs, see the section SYSEXT Utility - Natural Application Programming Interfaces in the Utilities documentation.

Start of instruction setTo use API USR3004N

  • Copy the USR3004N subprogram to the SYSTEM library, to the appropriate steplib library, or to the required library.

    The function to be performed by USR3004N requires that the respective parameter value (ON, OFF, STATE, CLEAR or COUNT) is specified first in the CALLNAT statement. The parameter values can be specified in uppercase or lowercase. On return, P-RETURN contains the return code, whereby Return Code 0 indicates that the function performed successfully. All parameters are optional for compatibility with previous versions of the API on the mainframe.

Start of instruction setTo activate the fast locate table

  • Call USR3004N with the following CALLNAT statement:

    CALLNAT 'USR3004N' 'ON' P-STATE 2X P-RETURN-CODE

Start of instruction setTo deactivate the fast locate table

  • Call USR3004N with the following CALLNAT statement:

    CALLNAT 'USR3004N' 'OFF' P-STATE 2X P-RETURN-CODE

Start of instruction setTo retrieve the current state of fast locate table usage

  • Call USR3004N with the following CALLNAT statement:

    CALLNAT 'USR3004N' 'STATE' P-STATE 2X P-RETURN-CODE

    If the P-STATE state field is TRUE, the fast locate table is used. The state field is returned for each API function.

Start of instruction setTo clear the fast locate table

  • Call USR3004N with the following CALLNAT statement:

    CALLNAT 'USR3004N' 'CLEAR' P-STATE 2X P-RETURN-CODE

    As described in Fast Locate Table with BPSFI=OFF, unexpected results can be encountered if the fast locate table is used with BPSFI=OFF. For BPSFI=OFF, the fast locate table is cleared when the application is back on Program Level 0 (NEXT prompt). A restart of the application therefore ensures that the latest version of the object is found.

    Since a server in a client/server environment never reaches Program Level 0, you can clear the fast locate table by using the CLEAR function of USR3004N to ensure that the latest version of the object is found.

Start of instruction setTo receive slot counts of the fast locate table

  • Call USR3004N with the following CALLNAT statement:

    CALLNAT 'USR3004N' 'COUNT' P-STATE P-SLOTS-USED P-SLOTS-TOTAL
      P-RETURN-CODE

    The counters indicate how well the hash function operates. The hash function is used to calculate the slot index number in the fast locate table.

    Field Description
    P-SLOTS-USED Shows the number of slots in the fast locate table that are currently occupied.

    The hash function operates well if this number increases with the number of objects accessed until close to the total number of slots.

    P-SLOTS-TOTAL Shows the total number of slots available in the fast locate table.

    The used hash function requires that the total number is a prime number. There are 593 slots available in the fast locate table.

Read-Only Buffer Pool

A read-only buffer pool is a special buffer pool that only allows read access. If an object is not found in the read-only buffer pool, Natural issues error 82 (object not found). As no attempt is made to retrieve the missing object in the system files, all lock operations on the system file as well as on the buffer pool are skipped. Account data are gathered.

A read-only buffer pool is defined in the Configuration Utility (see also Setting up a Buffer Pool below).

The utility NATBPSRV expects a preload list in a file named <bufferpool-name>.PRL at the location of the Natural parameter files, which is defined in the local configuration file (installation assignments). For example, if the name of the read-only buffer pool is "ROBP", the file name must be ROBP.PRL.

A preload list can be generated using the Natural utility CRTPRL. This utility extracts the contents of a buffer pool and merges it with the existing preload data of a buffer pool.

The preload list in the PRL file contains records with comma-separated data in the following form:

database-ID,file-number,library,object-name,kind,type

The keywords in the file have the same meaning as the keywords shown by the DIR command of the NATBPMON utility.

With the exception of directory-describing records (the kind of object is D, which means the object is part of FILEDIR.SAG), a value must be assigned to all keywords. Examples:

Keywords NATBPSRV loads the following into the buffer pool
222,111,MY_LIB,PGM1,G,P Object code of program PGM1 from library MY_LIB which is located on database 222 and file number 111.
222,113,*,*,D LIBDIR.SAG which is located on FNAT=222,113.
222,111,MY_LIB,*,D FILEDIR.SAG from library MY_LIB which is located on FUSER=222,111 .

Using a read-only buffer pool has the disadvantage that the application must be known in detail (as missing objects cannot be loaded). This means that all objects needed by an application must be specified in the preload list. In seldom cases, the complete set of objects needed by an application can be determined in advance.

Secondary Read/Write Buffer Pool

Natural can run with a read-only buffer pool as the primary buffer pool. Such a buffer pool is not modifiable. Objects missing in the read-only buffer pool cannot be loaded. If an object is not found in the read-only buffer pool, Natural issues error 82 (object not found). To avoid this, Natural can attach during execution to a secondary standard buffer pool (which allows read/write access) and activate the missing objects there. If a call to locate an object in the primary buffer pool fails, the secondary buffer pool operates as a backup buffer pool. The dynamic parameter BPID2 identifies the secondary buffer pool.

Other than for the read-only buffer pool, object locking through semaphores takes place each time the secondary buffer pool is accessed.

The preload list of the read-only buffer pool can be updated/enhanced by merging the contents of the secondary read/write buffer pool with the preload list of a read-only buffer pool using the utility CRTPRL.

Alternate Read-Only Buffer Pool

For a read-only buffer pool, it is possible to define the name of an alternate buffer pool in the Configuration Utility (see also Setting up a Buffer Pool below).

Using the SWAP command of the NATBPMON utility, which is only available for a read-only buffer pool, you can tag a read-only buffer pool as "obsolete". All Natural sessions attached to an obsolete buffer pool will detach from this buffer pool and will attach to the alternate buffer pool - but only if the alternate buffer pool is also a read-only buffer pool. The swap from one buffer pool to the other occurs either when Natural tries to load a new object (for example, when executing a CALLNAT or RETURN statement) or when Natural tries to interpret a command which has been put on the stack. The IPC resources (that is, the shared memory segment) of a buffer pool tagged as obsolete can be removed after issuing the SWAP command of the NATBPMON utility. This feature allows exchanging a buffer and its contents by another read-only buffer pool with updated contents without stopping Natural sessions.

Creating a Preload List Using the CRTPRL Utility

The Natural utility CRTPRL, which is located in the library SYSBPM, is used to create a preload list for a read-only buffer pool.

The utility uses the content of a source buffer pool as the basis for the preload list and checks whether the preload list already exists for a read-only (target) buffer pool:

  • If the preload list exists, the existing data in the preload list is merged with the data from the source buffer pool, and the preload list is saved with the new content.

  • If the preload list does not yet exist, it is created using the content from the source buffer pool.

The content of the resulting preload list determines the content of the read-only buffer pool. The preload list is read by the utility NATBPSRV which loads the corresponding objects into the read-only buffer pool.

Restrictions

When using the Natural buffer pool, only minimum restrictions must be considered:

  • When a Natural session hangs up, do not terminate it by using the Windows Task Manager.

    If this session is currently performing changes to the buffer pool internal data structures, an interruption may occur at a stage where the update is not fully completed. If the buffer pool internal data structures are inconsistent, this could have negative effects.

    Note:
    This can only happen when the Natural nucleus is executing buffer pool routines.

Setting up a Buffer Pool

The buffer pool assignments are stored in the local configuration file. To set up a buffer pool, you have to specify specific values in the local configuration file using the Configuration Utility. For a list of these values, see Buffer Pool Assignments in the Configuration Utility documentation.

Using the Natural Buffer Pool Service

Natural uses a Windows service, the Software AG Natural n.n Buffer Pool Service, to start the Buffer Pool Server when the PC is booted.

Natural is installed with the default buffer pool NATBP. NATBP is also used as the default buffer pool name at Natural startup (a different buffer pool can be defined using the profile parameter BPID).

You can modify the service configuration to meet your requirements. This is explained in the following topics:

Buffer Pool Service Commands

The file natbpsvc.exe, which is stored in the Natural bin directory, is used to execute the service commands.

The following service commands can be specified in the Command Prompt window of Windows:

Command Description
NATBPSVC INSTALL mode
Installs the buffer pool service. mode can be one of the following:
manual Default. The service is installed and must be started manually (either with the START command or by starting the Software AG Natural n.n Buffer Pool Service in Windows).
automatic The service is installed and is automatically started when the PC is booted.
NATBPSVC CREATE buffer-pool-name Creates a new buffer pool to be started by the service. The service checks whether the buffer pool with the specified name is defined in the Natural parameter file.
NATBPSVC START Starts the service (if not yet active) and all created buffer pools (see the CREATE command) for which the start parameter has been set to "yes" (see the SET command).
NATBPSVC START buffer-pool-name Starts the specified buffer pool. If the service has not been started (either automatically at boot time or manually by the user) an error message appears.
NATBPSVC SET buffer-pool-name start=mode
Defines whether the specified buffer pool is to be started when the service is started. mode can be one of the following:
yes The buffer pool is started.
no Default. The buffer pool is not started.
NATBPSVC STOP Stops the service and all previously started buffer pools.
NATBPSVC STOP buffer-pool-name Stops the specified buffer pool.
NATBPSVC SHOW Displays the configuration parameters for all buffer pools that are defined for the service, that is: whether these buffer pools are to be started when the service is started.
NATBPSVC SHOW buffer-pool-name Displays the configuration parameters for the specified buffer pool, that is: whether this buffer pool is to be started when the service is started.
NATBPSVC STATUS Displays the status of all buffer pools that are defined for the service, that is: whether these buffer pools are active or not active.
NATBPSVC STATUS buffer-pool-name Displays the status of the specified buffer pool, that is: whether this buffer pool is active or not active.
NATBPSVC DELETE buffer-pool-name Deletes the specified buffer pool from the service.
Warning:
Do not delete the default buffer pool NATBP, as it is possible that Natural may not function properly anymore.
NATBPSVC REMOVE Removes the service from the system.

Example: Starting Natural with Your Own Buffer Pool

This example explains how to create a new buffer pool with the name MYBP and how to start Natural with your new buffer pool.

Start of instruction setTo start Natural with your own buffer pool

  1. Use the Configuration Utility to define an additional buffer pool with the name MYBP in the local configuration file. See Buffer Pool Assignments in the Configuration Utility documentation.

    Note:
    For this example, you can use the same values as defined for the default buffer pool NATBP.

  2. Invoke the Command Prompt window of Windows.

  3. Go to the Natural bin directory which contains the file natbpsvc.exe.

  4. Enter the following command to create a buffer pool with the name MYBP:

    NATBPSVC CREATE MYBP

    The following information is shown:

    %NATBPSVC-I: Natural n.n Buffer Pool Service
    %NATBPSVC-I: New buffer pool 'MYBP' created
    %NATBPSVC-I: Natural n.n Buffer Pool Service

    Important:
    When the buffer pool with the specified name has not yet been defined in the local configuration file, a corresponding message is shown instead. Make sure to define the buffer pool in the local configuration file before you proceed with the steps below.

  5. Enter the following command to define that your buffer pool is to be started when the service is started:

    NATBPSVC SET MYBP start=yes

    The following information is shown:

    %NATBPSVC-I: Natural n.n Buffer Pool Service
    %NATBPSVC-I: Configuration successfully set
    %NATBPSVC-I: Natural n.n Buffer Pool Service
  6. Enter the following command to start your buffer pool now (without having to restart the service):

    NATBPSVC START MYBP

    The following information is shown:

    %NATBPSVC-I: Natural n.n Buffer Pool Service
    %NATBPSVC-I: Send request to Natural n.n Buffer Pool Service
    %NATBPSVC-I: Buffer pool 'MYBP' started
    %NATBPSVC-I: Natural n.n Buffer Pool Service
  7. Enter the following command to display the status of all buffer pools that are currently defined for the service:

    NATBPSVC STATUS

    The following information is shown:

    %NATBPSVC-I: Natural n.n Buffer Pool Service
    %NATBPSVC-I: Send request to Natural n.n Buffer Pool Service
    %NATBPSVC-I:    MYBP is active
                    NATBP is active
    %NATBPSVC-I: Natural n.n Buffer Pool Service
  8. Start Natural with the dynamic parameter BPID as shown below:

    natural BPID=MYBP

Using the Utility NATBPSRV for Creating the Buffer Pool

The buffer pool is created using the utility NATBPSRV.

The buffer pool server is automatically started by the Natural Buffer Pool Service.

Note:
The utility NATBPSRV should not be accessible to all Natural users, because it can cause damage to the work of other buffer pool users.

NATBPSRV allocates the resources required by the buffer pool and creates the permanent communication facilities (that is, shared memory and semaphores) used for the buffer pool. The necessary specifications for the resources and facilities are made with the Configuration Utility (see Setting up a Buffer Pool).

By default, the buffer pool NATBP is started. If another buffer pool is to be started, you specify its name with the following NATBPSRV command line option:

NATBPSRV BP = buffer-pool-name

Monitoring the Buffer Pool

The Buffer Pool Monitor is used to oversee the buffer pool's activity during its operation. The Buffer Pool Monitor can also be used to shut down the buffer pool when Natural must be stopped on a computer.

The Buffer Pool Monitor collects information on the current state of your Natural buffer pool.

If multiple buffer pools are active on the same computer and an object that is loaded to more than one buffer pool is modified by a Natural process, the object will only be removed from the buffer pool to which the modifying Natural process is attached. To ensure that modified objects are also removed from other buffer pools on the same computer to which the object is currently loaded, you can enable the buffer pool synchronization in the Configuration Utility.

Natural provides two versions of the Buffer Pool Monitor: a graphical user interface and the NATBPMON utility which is a command line version.

For detailed information for how to use the different versions of the Buffer Pool Monitor, see Using the GUI Version of the Buffer Pool Monitor and Using the Command Line Version of the Buffer Pool Monitor (NATBPMON).

Trouble Shooting

This section describes problems that may occur when using the Natural buffer pool and how to solve them.

The following are typical command output examples, with an explanation of what went wrong during execution.

Problem 1

Either Natural or the Natural Buffer Pool Monitor cannot be started.

Example 1

The following examples describe the most typical problems you are likely to encounter as a Natural administrator or user. These problems occur when you start Natural or the NATBPMON utility, and the buffer pool is not active.

  • You try to start Natural and the following message appears:

    Natural Startup Error 16: Unable to open buffer pool.
    Buffer pool error: "unexpected system call error occurred" (20)
    Buffer pool could not attach to the global shared memory.
  • You try to start the Natural Buffer Pool Monitor and the following message appears:

    Cannot get shared memory 
    Buffer pool error: "unexpected system call error occurred" (20)
    Buffer pool could not attach to the global shared memory.

Solution

Start the buffer pool service as described in Using the Natural Buffer Pool Service.

Example 2

The following examples describe the most typical problems you are likely to encounter as a Natural administrator or user. These problems occur when you start Natural or the NATBPMON utility, and the buffer pool has been started with a different internal version.

  • You try to start Natural and the following message appears:

    Natural Startup Error 16: Unable to open buffer pool.
    Buffer pool error: "Buffer pool does not correspond with your version of Natural"(25).
    Internal version of buffer pool is 0 but requested internal version is 1. 
  • You try to start the Natural Buffer Pool Monitor and the following message appears:

    Buffer pool error: Buffer pool does not correspond with your version of Natural (25).
    Internal version of buffer pool is 0 but requested internal version is 1.

Solution

Verify that your Natural version corresponds to your buffer pool version number and that the internal buffer pool version (BP version) is also correct. Restart the buffer pool with the same version as Natural but make sure that no other users are active.

Important:
The internal buffer pool version number (BP version) can vary in between service pack releases (third digit of the product version number). For example, a buffer pool that has been initiated using Natural Version vrs cannot be used with Natural Version vr(s+1) and vice versa.