Configuring Buffering using bufserv

The PI API installation installs the Buffer Server (bufserv) program for buffering data writes. After installation, if buffering using the buffer server is needed, it must be enabled on new installations. Enabling bufserv entails setting the BUFFERING key to 1 (see table below). Upgrades of the PI API will not modify the existing configuration. The following files are installed for buffering support:

File Name Purpose
UNIX Windows
bufserv bufserv.exe Buffering process that sends data queued by PI API programs to the PI Server.
bufutil bufutil.exe Utility for managing buffering process.
isbuf N/A Program to determine if buffering is requested (only distributed previous to version 1.6.0.3 of the PI API). The functionality of this program has been subsumed by the bufutil -i command.
piclient.ini piclient.ini Buffering configuration file.

 

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the $PIHOME/dat subdirectory of the PIHOME directory (typically c:\Program Files\PIPC\dat for Windows and /opt/piapi/dat for UNIX). This file follows the conventions of Microsoft Windows initialization files with sections, keys within sections, and values for keys.  If buffering parameters are changed, the PI API programs and buffering processes must be restarted for those changes to take effect.

Each destination PI server for buffered data will require an entry in the piclient.ini file under the [BUFFEREDSERVERLIST] section.  The entry is of the form:

BUFSERVn=<PI Server Name>

n is an integer, and the list must be numerical order (that is, if there is a BUFSERV2, there must be a BUFSERV1).

Each replicated PI server that is to be configured must have an entry in the piclient.ini file under the [REPLICATEDSERVERLIST] section. The entry is of the form:

REPSERVn=<PI Server Name>

n is an integer, and the list must be numerical order (that is, if there is a REPSERV2, there must be a REPSERV1). In addition, a replicated server must also be in the buffered server list (you cannot send to a replicated server if it does not have a buffer server associated with it).  Note: Only one collective can be targeted in the Replicated Server List, any event sent to a server specified in the Replicated Server List will be distributed to all of the servers specified in the Replicated Server List.

 

As noted in the API Node Buffering section, the event that is distributed is not manipulated in any way.  The multiple destination PI servers must all have synchronized point databases and system times; otherwise the distributed event may fail to be accepted by non-synchronized servers.

 

When bufserv is started, it reads the configure from the piclient.ini file and starts new instances of bufserv for each of the PI servers in the [BUFFEREDSERVERLIST]. If there are n entries in the [BUFFEREDSERVERLIST], then there will be n+1 bufserv processes running. Each new instance of bufserv create shared memory blocks for the buffered events and attempt to connect to their PI server. For versions prior to PI API 2016, PI Trusts must be configured on each of the PI servers to allow the bufserv process to connect with the required permissions. With PI API 2016 or later, PI Mappings must be configured on each of the PI servers to map the Windows credentials of the bufserv process to the required PI identity.

Note: If buffering is enabled, bufserv must be started before any PI API-based applications are started. See Operation of Bufserv for more information.

All other buffering settings are entered in a section called [APIBUFFER].  Currently, each buffer server uses the same set of settings. To modify settings, simply edit the piclient.ini file in a text editor (e.g. Notepad on Windows, vi on UNIX) to the desired values.

The following settings are available for buffering configuration. These settings apply to PI Buffer Subsystem as well as API Buffer Server (bufserv).

Item Values Default Description
PIBUFSS section
BUFFERING 0, 1 1 Whether buffered data be processed by pibufss or bufserv. bufserv = 0, pibufss = 1
APIBUFFER section
BUFFERING 0, 1 0 Turn off/on buffering. OFF = 0, ON = 1
FILEBUFPATH string Windows:
32-bit: %PIHOME%\dat
64-bit: %PIHOME64%\dat

UNIX:
$PIHOME/dat
Location of buffer data files (APIBUF_<server_name>.dat). If the shared memory buffer becomes full, overflow data is written to these files.
Note: Do not use this parameter in the 32-bit piclient.ini when using PI Buffer Subsystem 3.4.375 or earlier, or when using any version of PI Buffer Subsystem with PI API versions earlier than 1.6.2.
PAUSERATE 0 - 2,000,000 2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node. (seconds)
PAUSERATEMS 0 - 2,000,000 (PAUSERATE*1000) PI API 2016 only : The same as the PAUSERATE parameter, but specified in milliseconds to allow subsecond pauses to be configured. (milliseconds) If both PAUSERATE and PAUSERATEMS are specified then PAUSERATEMS has priority.
RETRYRATE 0 - 2,000,000 120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect. (seconds)
MAXFILECOUNT 1 - 9,999 100 PI API 1.6.6 and later on UNIX and Linux only : Maximum number of API disk buffer files. (APIBUF_*.DAT)
MAXFILESIZE 1 - 2,000,000 Windows
(32- and 64-bit):
2,000,000

UNIX:
128,000
Maximum buffer file size before buffering fails and discards events. (Kbytes)
MAXTRANSFEROBJS 1 - 2,000,000 1600 Maximum number of events to send between each SENDRATE pause.
BUF1SIZE 64 - 16,777,216 32768 Primary memory buffer size. (bytes)
BUF2SIZE 64 - 16,777,216 32768 Secondary memory buffer size. (bytes)
SENDRATE 0 - 2,000,000 100 The time to wait between sending up to MAXTRANSFEROBJS to the server. (milliseconds)
PUTSNAPARRAYSIZE 32 - 65,536 800 PI API version 1.6.2 or later : Number of events for each PInet message.
BUF1NAME string PIAPINODEBUFFER1MEM The name of the primary memory buffer. On Windows platforms, the resources are created in the "Global\\" namespace.
BUF2NAME string PIAPINODEBUFFER2MEM The name of the secondary memory buffer. On Windows platforms, the resources are created in the "Global\\" namespace.
BUF1MUTEXNAME string PIAPINODEBUF1MUTEX The name of the primary signaling mutex. On Windows platforms, the resources are created in the "Global\\" namespace.
BUF2MUTEXNAME string PIAPINODEBUF2MUTEX The name of the secondary signaling mutex. On Windows platforms, the resources are created in the "Global\\" namespace.
FILEBUFNAME string PIAPIFILEBUF The name of the file store memory buffer. On Windows platforms, the resources are created in the "Global\\" namespace.
FILEMUTEXNAME string PIAPINODEFILEMUTEX The name of the file store signaling mutex. On Windows platforms, the resources are created in the "Global\\" namespace.

 

Note, when specifying values in the piclient.ini file do not use commas (e.g. specify BUF1SIZE=32678, not BUF1SIZE=32,678).

On UNIX and Windows, in addition to the [APIBUFFER] section, the [PISERVER] section may be used to define whether a connection will use 4 or 8 characters of the user defined procname. See the description of the LONGPROCNAME setting in the piclient.ini file for more information.

On UNIX and Windows, the [PISERVER] section also defines the default PI Server and an optional setting in case the daylight time offset change between the client and server are not synchronized. However, on Windows the default server, PIHOMENODE, and DSTMISMATCH information may also be stored in the pilogin.ini file as well.

Item Values Default Description
PIHOMENODE string none Default server.
DSTMISMATCH 0 - 2,000,000 0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the server and client nodes are in timezones whose DST transition rules differ (seconds).
LONGPROCNAME 0 - 1 0 This item determines whether the PIAPI will send 4 or 8 characters of the user specified procname when connecting to a PI server. The default is to send only the first 4 characters, appended with an "E" for backwards compatibility with PI 2 servers.  Enabling LONGPROCNAME (by setting the value to 1), denotes that the connection to the PI server will advertise the first 8 characters of the user specified procname (or the first 8 characters of the executable name, if the user procname is not set) instead of only the default 4.
Note: Changing this setting can cause issues with existing PI trusts, since PI API may pass a different application name than the name previously configured for the PI trust.

 

There are several example piclient.ini files shown below.

Example 1: Upgrading from an older PIAPI version.  There are two machines:  the interface node, which has an upgrade of the PIAPI node with a previously buffered connection to the default node and the default home node (MyServer1).

 

[PISERVER]
DSTMISMATCH=0
[APIBUFFER]
BUFFERING=1
[BUFFEREDSERVERLIST]
BUFSERV1=MyServer1

 

When the buffer server process (version 1.6.0.0 or greater) after the upgrade is restarted, it checks to see if there is [BUFFEREDSERVERLIST] section is present and if buffering is set to on.  If the buffered server list is present, the entries specified are used.  If no [BUFFEREDSERVERLIST] section is present, but BUFFERING=1, then the parent buffer server process (remember, each member of the buffered server list will have a child process created for it to manage its independent set of buffers) will create the [BUFFEREDSERVERLIST] section with one entry, the default server.  This facilitates the ease of upgrade for the node and migration of the configuration to the new nomenclature.  The [BUFFEREDSERVERLIST] can then be modified by the user as desired.  Of course, any additional changes to the buffered server list by the user will require that the buffer server process (the parent) be restarted to have those changes take effect.

No Replicated Server List entries are automatically created.

 

Example 2: Specifying buffering to multiple independent PI servers.  The system architecture consists of 3 machines (2 independent PI servers, MyServer1 and MyServer2, and one interface node - where this piclient.ini file is contained).

 

[PISERVER]
DSTMISMATCH=0
LONGPROCNAME=1
[APIBUFFER]
BUFFERING=1
[BUFFEREDSERVERLIST]
BUFSERV1=MyServer1
BUFSERV2=MyServer2

 

The use of the Long Process Name option has been specified.  Also, buffering is on.  The Buffered Server List has entries for the 2 independent PI servers (MyServer1 and MyServer2).  This means that 2 different interfaces can be running on the same node and both have their data buffered independently.  Previous to PIAPI version 1.6.0.0, the PIAPI could only buffer the connection to the default server.  No other buffering parameters are specified in the [APIBUFFER] section, so all of the defaults are used (see the tables above for defaults).

No Replicated Server List is specified; so, no events are distributed to multiple servers.

 

Example 3: Specifying buffering to a collective. The system architecture consists of 3 machines (2 collective members of a PI collective, MyServer2 and MyServer3, and one interface node – where this piclient.ini file is contained).

 

[PISERVER]
PIHOMENODE=MYNTSERVER
DSTMISMATCH=0
LONGPROCNAME=1
[TCP/IP]
PORT=5450
[APIBUFFER]
BUFFERING=1
[BUFFEREDSERVERLIST]
BUFSERV1=MyServer2
BUFSERV2=MyServer3
[REPLICATEDSERVERLIST]
REPSERV1=MyServer2
REPSERV2=MyServer3

 

The interface PIAPI node is a UNIX box; therefore, the defaults server is specified here (MYNTSERVER) in the piclient.ini file.  Note the default server is not one of the buffered servers (i.e. the default server for the PIAPI node is not longer required to be a buffered connection, if buffering is specified).  Use of the 8-character procname feature has been enabled.  The buffering flag is on.  The Buffered Server List has entries for the 2 collective members (MyServer2 and MyServer3).  The same servers are also specified (order doesn’t matter) in the Replicated Server List.  This means that any interface running on the PIAPI node that specifies a connection to either collective member will have their events distributed to the buffers of both servers with a single data call.  Note both destination servers must be specified in the Replicated Server List and that the all members of the Replicated Server List are also specified in the Buffered Server List.

 

Example 4: Specifying buffering to a mix of independent and collective PI servers.  There are 4 machines:  three PI servers (one non-replicated server and two collective members, a primary and a secondary) and one PI API node with two interfaces running.  One interface is configured (via the startup command file for the interface) to send data to the non-replicated server, MyServer1; this data, while buffered, is not replicated to any other server.  The other interface, configured to send data to either MyServer2 or MyServer3, will have the events sent to the buffers for both MyServer2 and MyServer3 – the two servers specified in the Replicated Server List.

On a UNIX box, the piclient.ini file would look like:

[PISERVER]
PIHOMENODE=MYNTSERVER
DSTMISMATCH=0
LONGPROCNAME=1
[TCP/IP]
PORT=5450
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=10000
; the PI API connection routines have 1 minute default timeout
RETRYRATE=600
[BUFFEREDSERVERLIST]
BUFSERV1=MyServer1
BUFSERV2=MyServer2
BUFSERV3=MyServer3
[REPLICATEDSERVERLIST]
REPSERV1=MyServer2
REPSERV2=MyServer3

 

The default UNIX PI server has been set to "MYNTSERVER" and the use of the 8-character procname feature has been enabled.  Buffering is on for the PIAPI node and the MAXFILESIZE entry is in Kbytes; so, the value of 10000 equals 10 Megabytes (10,000 Kilobytes). The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying. The [PISERVER] and [TCP/IP] sections are for the default connection.   There are 3 buffered servers defined:  MyServer1, MyServer2, and MyServer3.  The non-replicated (MyServer1) is not part of a collective, but a separate PI server, which has PI API data buffered to it; therefore, it has an entry in the Buffered Server List, but not the Replicated Server List.  The two other buffered servers (MyServer2 and MyServer3) are replicated servers, as well; therefore, MyServer2 and MyServer3 have entries in both the Buffered Server List and the Replicated Server List.

Enabling Operational Intelligence