bufutil: Buffering Utility

A utility program, bufutil, is provided to examine the current state of buffering and to shut down the buffering process. The program when run without arguments presents a simple text menu of choices. The presentation is the same on all platforms. Certain functions in bufutil can be run in non-interactive mode through the use of command switches.

Running bufutil with no arguments brings up a menu of choices.

Choices 1,2,3 may take optional arguments of [ #repeats #seconds]
( 1) Show Primary buffer header
( 2) Show Secondary buffer header
( 3) Show file buffer header
( 4) Kill server and quit
( 5) Quit
( 6) Change Server
( 7) Display this menu

Enter choice:

Items 1 and 2 display the state of the memory buffers described earlier. The format of the display is:

  Primary Buffer Header Data
  Version:       1
  Mode:         Single
  Server status: Connected [Buffering OFF]
  Size:         32768
  Next write location:   36
  Next read location:    36
  Write ptr before wrap: 0
  Unprocessed entries:   0

Of the various items shown, the Mode, Server status and the Unprocessed entries are the most significant for monitoring the buffering process. The Server status may indicate "Connected", "Disconnected" or "Connected [Buffering OFF]". When the status is disconnected, the buffer server will buffer events until the server is once again connected. If "[Buffering OFF]" is indicated, buffering has not been enabled in the piclient.ini file by entering BUFFERING=1. To enable buffering, stop all programs that use the PI-API, enable buffering in <piclient.ini, and restart the buffer server before starting other PI-API programs.

The mode shows the current buffering state. In the display above, buffering is using a single memory buffer in this display. Other options are "Dual Memory" and "Dual Memory and File".

The Unprocessed entries shows the number of items in the buffer that have yet to be handled. In the primary buffer Unprocessed entries entries refers to items not sent to the server. In other buffers, the destination of the Unprocessed entries events depends on the mode. In Dual Memory mode, events in the secondary buffer are moved to the primary buffer when space is available. In Dual Memory and File mode, events in the secondary buffer are moved to the file when the buffer becomes full. Events in the file are moved to the primary buffer as space becomes available.

By observing the Mode and selecting the desired buffer you can watch the buffers grow and shrink. The display does not update dynamically because querying the information requires a brief locking of the buffering resources. Instead, by repeatedly selecting a buffer, you can watch it change. Alternately, you may enter two numbers indicating the number of times (# repeats) to display the given buffer information with a delay {# seconds) between refreshing the numbers.

The Version item reports the version of buffering being used, for future compatibility issues. The size is the size of the memory buffer and will remain constant. The write and read locations are used to handle inserting and removing values from the buffers. As events are buffered, the write location moves forward. As events are removed, the read location moves forward. These buffers wrap around so the write location can be behind the read location.

As the buffer is a fixed size and the event size can vary, there may be unused bytes at the end of the buffer. The write ptr before wrap entry refers to this condition and shows the last position of the write pointer before it wrapped to the top of the buffer.

Selecting item 3 from the menu displays information about the file buffer in the following format:

    File Header Data
Version:         1
Total events in file:   0
Write File Index:      -1
Write File Event Count: 0
Read File Index:       -1
Read File Event Count:  0
Current read position:  20

The Version number in this display is for the master header file. The Write File Index shows where PI-API programs will write the next data event.  The Read File Index shows where the buffer server is reading data and sending to the PI Server.  If either file index is -1, that indicates that there are no data files and data is flowing only through memory buffers.  The Total events in file number indicates the sum of events in all data files.

Item 4 on the bufutil menu, "Kill server and quit", is used to stop the buffering process cleanly. Selecting this item will send a message to the buffering process that it needs to shutdown. It will then lock the resources, move memory information to file, and then exit. Interfaces and other programs utilizing the PI-API on this node should be stopped prior to killing the buffering process.

Item 5, "Quit", is used to exit bufutil. In a typical session, bufutil is invoked and several buffers are examined, perhaps repeatedly, to assess the current buffering mode and the amount of data stored in buffers. Then "Quit" is selected to exit the monitoring utility.

Item 6 allows the user to point to a different set of memory buffers. bufutil initially connects to the default server. Once the item is selected, an enumerated list of buffered servers will be shown Selecting the number for a server will attempt to connect to the buffers for that server, and if successful the server name in the menu display will update with the new server name. If connection to the buffers fails, then an error will be shown and the updated menu will show <No_Server>.


Optional command line arguments

Bufutil also supports eight optional command line switches which bypass the normal interactive interface.

-f <filename>

The '-k' option shuts down the buffering process, much like selecting item 4 in the bufutil menu. This method is used in the pistop script under UNIX when stopping the API.

The command 'bufutil -host=<server>' will open bufutil and connect to the specified server. By default, bufutil will connect to the first server in the [BUFFEREDSERVERLIST] (i.e. BUFSERV1).

Using the command 'bufutil -u -host=<server>' will attempt to unlock the buffers associated with the specified server. If no server is specified (i.e. 'bufutil -u') is used, then bufutil will attempt to unlock the buffers associated with all servers in the [BUFFEREDSERVERLIST].

Entering the command 'bufutil -r' forces bufutil to eliminate the screen clearing and repeating of the main menu between commands.  

The command 'bufutil -i' returns whether BUFFERING is enabled in the piclient.ini file. This call is used in the pistart script in UNIX to determine if buffer server needs to be started.

The '-f <filename>' option can be used to examine a buffer file (APIBUF_<servername>.dat) to see what events and their offsets exist in the file. This is primarily used when debugging and troubleshooting issues and is not normally needed in regular use.

The '-v' option outputs the version of bufutil to the screen; while the '-?' option outputs a usage screen for bufutil to the screen.

Enabling Operational Intelligence