Activating the Natural Buffer Pool on UNIX

Since the Natural buffer pool requires resources that should be created every time your system is booted, a procedure to activate the buffer pool should be called during system startup.

The Natural installation process provides a buffer pool start/stop service procedure. The name of the procedure will be generated depending on the $SAG environment and the Natural version.

Furthermore, the Natural installation process determines the platform automatically and prepares the system (V style or AIX) to execute the start/stop service procedure during start/stop of the system. Depending on the platform, the system directory for initialization and, if needed, the runlevel startup directories will be selected. The start/stop service procedure will be copied to the system directory for initialization and links will be created in the runlevel startup directories.

The Natural installation process installs the buffer pool start/stop service as an optional feature. You can also set up this service manually as described below.

The Natural buffer pool needs some operating system resources for its operation. Therefore, kernel parameters need to be checked and, if necessary, increased as described below.

This document covers the following topics:

Preparing the System V Style Startup Procedure
Preparing the AIX Startup Procedure
Sample of a Buffer Pool Start/Stop Procedure
Changing the Kernel Parameters

To verify the operation of the buffer pool, invoke the NATBPMON utility which is used to monitor the buffer pool's activity.

Preparing the System V Style Startup Procedure

The procedure template rc_srv.tpl in the $NATDIR/$NATVERS/INSTALL directory may be used to create a script, which is used to invoke the Natural buffer pool during system startup.

The following table shows where the init.d and rc3.d directories are located on the various platforms. In the following description, init.d or rc3.d stand for the relevant path indicated below for the platform you are using.

Platform	System Directory for Initialization	Runlevel Startup Directory
Solaris	/etc/init.d	/etc/rc3.d
HP-UX	/sbin/init.d	/sbin/rc3.d
Linux	/etc/init.d	/etc/init.d/rc3.d or /etc/init.d/rc5.d

A sample copy of the buffer pool procedure is shown below. It can be edited with a text editor.

To set up the system, proceed as described below:

Log in as user "root".
Copy the template rc_srv.tpl to the init.d system directory and rename it, for example to sag1nat63bp.
If already available, create a backup copy of your current sag1nat63bp file contained in the init.d directory (see the above table).

Set the following environment variables in the sag1nat63bp procedure:

`NATDIR`	Location where Natural was installed.
`NATVERS`	Natural version number.
`NATADM`	The login name of the Natural system administrator responsible for this buffer pool. It is assumed that this administrator account is called "sag", and that the user ID is already known to the system. It does not have to be a user with root privileges.

Note:
The Bourne shell does not allow blanks before and after the equals sign in the lines to be customized.

Create a link "S99sag1nat63bp" to the sag1nat63bp procedure in the rc3.d directory.

You may create a link to the buffer pool procedure in the runlevel 3 startup directory of your UNIX machine. The rc3.d directory contains several Bourne shell scripts or links to Bourne shell scripts that start with "S" followed by a number, for example "99". A lower number will be executed first. If you add a file or a link to this directory, the respective code is executed when the system changes to "multi-user mode".

When you are using a Natural Development Server, make sure that the Natural Development Server is started after the buffer pool and is stopped before the buffer pool.

Preparing the AIX Startup Procedure

The procedure template rc_srv.tpl in the $NATDIR/$NATVERS/INSTALL directory may be used to create a script which is used to invoke the Natural buffer pool during system startup.

To set up the system, proceed as described below:

Log in as user root.
Copy the template rc_srv.tpl to the etc system directory and rename it, for example to sag1nat63bp.

Set the following environment variables in the sag1nat63bp procedure:

`NATDIR`	Location where Natural was installed.
`NATVERS`	Natural version number.
`NATADM`	The login name of the Natural system administrator responsible for this buffer pool. It is assumed that this administrator account is called "sag", and that the user ID is already known to the system. It does not have to be a user with root privileges.

Note:
The Bourne shell does not allow blanks before and after the equals sign in the lines to be customized.

The /etc/inittab file supplies the script to the init command's role as a general process dispatcher. Therefore, enter a record with the sag1nat63bp script in the /etc/inittab file using the mkitab command. For example:
```
mkitab "sag1nat63bp:3:wait:/etc/sag1nat63bp > dev/console"
```
Verify your changes to make sure that the changes made consist only of those changes desired.

Sample of a Buffer Pool Start/Stop Procedure

#!/bin/sh
#
# Copyright (c) 2010 Software AG, Germany. 
#         All rights reserved.
#
# Start/stop script for Natural Buffer Pool
# 
#
#===================================================================
 
NATDIR= <the name of Natural's installation directory, for example, '/opt/softwareag/nat'> 
NATVERS= <Natural version, for example, '63100'>
NATADM=sag
export NATDIR NATVERS
#
#------------------------------------------------------------------- 
#
natstart=$NATDIR/$NATVERS/bin/natstart.bsh 
natbpmon=$NATDIR/$NATVERS/bin/natbpmon

if [ "${LOGNAME}" = "" ]; then
  LOGNAME=root
  HOME=/
  export LOGNAME HOME
fi

case "$1" in
  start)
    echo "Starting Natural Bufferpool ..."
    if [ -x "${natstart}" ]; then
      su $NATADM -c ${natstart} > /dev/console 2> /dev/console
    else
      exit 1
    fi
    echo "done..."
    ;;
  stop)
    echo "Stopping Natural Bufferpool ..."
    if [ -x "${natbpmon}" ]; then 
      su $NATADM -c "${natbpmon} shutdown" > /dev/console 2> /dev/console
    else
      exit 1
    fi
    echo "done..."
    ;;
  *)
    echo "Usage: $0 {start|stop}"
    exit 1
    ;;
esac

#
#===================================================================

The procedure natstart.bsh is called automatically by the system startup procedure and is used to initialize the Natural environment. It needs no customization and is stored under $NATDIR/$NATVERS/bin/natstart.bsh.

Changing the Kernel Parameters

The information below applies to Solaris, HP-UX and Linux.

Note:
Since AIX dynamically adjusts the IPC configuration, kernel parameter changes are not required.

The Natural buffer pool needs the following operating system resources for its operation:

A set of semaphores to enable synchronization between the users.
Shared memory to store the buffer pools objects.

The amount of available shared memory and the semaphores are configured in the kernel. For information on how to change your current kernel, contact your system administrator or consult your respective operating system documentation.

Note:
Since semaphores are also needed to synchronize the access to Natural system files, additional operating system resources should also be considered here.

The following abbreviations are used:

NBP	Number of buffer pools running on one computer.
SMU	Sum of all "maximum users" assignments for all buffer pools.
MAXMEM	Largest buffer pool size value for all buffer pools.
NSF	Number of system files used.

If you have only one buffer pool on your computer, the following values are used:

NBP	1
SMU	"Maximum users" assignment from the buffer pool assignments in the local configuration file.
MAXMEM	Buffer pool size from the buffer pool assignments in the local configuration file.

As not all resources defined by the default parameter settings are used during normal system operation, the default values are sufficient to operate one buffer pool supporting up to 20 users using about 1 MB of memory.

Note:
You can find the default values specific to your environment in your kernel configuration file. Do not decrement any kernel parameters that are above their default values, as other software may need the larger value.

Change the following kernel parameters to the required values as follows:

Name	Required Value
`SEMAEM` ^*	Must be at least SMU.
`SEMMNI`	Increment by (NBP + NSF).
`SEMMNS`	Increment by (SMU + 5 * NBP) + NSF.
`SEMMNU` ^*	Increment by SMU.
`SEMMSL`	Must be at least SMU + 4.
`SEMUME` ^*	Must be at least 5.
`SEMVMX` ^*	Must be at least SMU.
`SHMMAX`	Must be at least MAXMEM.
`SHMMNI`	Increment by NBP.
`SHMSEG`	Must be at least 4.

^* Cannot be modified on Linux.

Review the changes made to the file sag1nat63bp in your init.d directory in case the startup message is not displayed during rebooting.

Note:
If the system should fail to boot after modification (that is, the new kernel cannot be booted), check if there is an error in the startup procedure. Detailed information about trouble-shooting the operating system can be found in your respective operating system manuals. If you cannot solve the problem, contact Software AG support.