AF SDK Buffering

There are three buffering behaviors ( AFBufferOption ) available in AF SDK when writing data:

1. AFBufferOptionDoNotBuffer : Write data directly without going through the buffer system.

2. AFBufferOptionBufferIfPossible : Data writes will be buffered if possible. If the data reference does not support buffering or its buffering system is not available, then writes will occur without buffering. Note that in the case of data writes to the PI Data Archive, there is a 1-minute throttle such that if the data writes through PI Buffer Subsystem (PIBufSS) fail, then the next try to write through PIBufSS again will not happen until the 1-minute throttle time has expired. In the meantime, data is written directly without buffering. Note that if the failure is due to PIBufSS not installed, or installed but never starts and communicates with the current instance of local PI Network Manager (PINetMgr) Subsystem, then the throttle time is 10 minutes.

3. AFBufferOptionBuffer : Write data through buffer system. If the write fails, e.g. the data reference does not support buffering or its buffering system is not available, then an error is thrown or returned.

The AF SDK supports data write methods through the SetValue, UpdateValue and UpdateValues, in AFAttribute , AFData , AFListData , PIPoint , and PIServer . When no buffering option is specified in the call, the default buffering behavior for these methods is determined by the system level AF SDK configuration or programmatically for the current client process.

In summary, the buffering behavior can be set at the following levels:

- System level: In AFSDK.config GlobalSettings, bufferOption can be set to either “DoNotBuffer”, “BufferIfPossible”, or “Buffer”. This setting will be valid for all AF SDK applications running in the same client machine. If this setting is not specified or is misspelled then the buffering behavior is assumed to be “BufferIfPossible”.

- Process instance level: Programmatically, one can set AFDataBufferOption static property to the desired AFBufferOption . This setting will be valid for the corresponding AF SDK client process instance and will override the system level setting.

- Per Call level: The buffering behavior can also be set at the method level through the AFData.AFBufferOption parameter, which will override process level and system level settings. The AF SDK data write overload methods with this parameter are implemented in the AFData , AFListData , PIPoint , and PIServer AF SDK classes, as follows:

- AFDataUpdateValue

- AFDataUpdateValues

- AFListDataUpdateValues

- PIPointUpdateValue

- PIPointUpdateValues

- PIServerUpdateValues

The PIBufferStatus contains health information ( PIBufferHealthStatus ) related to the buffering state of a PI Data Archive server/collective or the overall health of the PI Buffer Subsystem. AF SDK supports the following methods to query PI buffer statuses:

- PIServersGetBufferStatus : returns the global PIBufferStatus of the PI Buffer Subsystem (PIBufSS).

- PIServerGetBufferStatus : returns the PIBufferStatus for the corresponding PIServer.

- PICollectiveMemberGetBufferStatus : returns the PIBufferStatus for the corresponding PICollectiveMember.

Note
For PI Buffer Subsystem older than version 4.3, these buffer status related functions are not applicable, and will return PIBufferStatusHealth set to PIBufferHealthStatusUnknown .

When writing data through PI Buffer Subsystem (PIBufSS) to a PI Data Archive collective, the data will be buffered to all members of the collective. Through PI Buffer Subsystem, data is compressed according to the PI point's specification before it is sent to collective members. This produces an identical compressed data stream at each member server.

When writing data directly (without going through PIBufSS, i.e. DoNotBuffer setting) to a collective, the behavior is the same as in previous versions of AF SDK. In other words, data will be written to the currently active collective member. If the currently active member is not the primary, then AllowWriteValues must be true for successful non-buffered data write to it.

Note
AF SDK allows deleting events to be buffered to a collective, with the knowledge that if the collective members have unsynchronized data then it will fail at the collective member/s whose data does not match.

AF SDK Manual Data Fanning to Collective Members

It is possible to manually fan data to any or all members of a PI Data Archive collective through AF SDK, by writing data directly to each of the corresponding member. Writing data directly ( DoNotBuffer ) to a specific member of a collective can be done either through implicit or direct connection:

1. Implicit Connection to a collective member: One can change the currently connected member of a collective through PICollectiveSwitchMember . If AF SDK is connected to a secondary member then AllowWriteValues must be true for successful non-buffered data write to it.

2. Direct Connection to a collective member: A direct connection to a collective member through PICollectiveMemberConnect or PICollectiveMemberConnectDirect will allow non-buffered data to be written regardless of the AllowWriteValues setting.

Note
Manual data fanning may encounter point-locking issue if the same application is or other applications are also writing to the same point through PIBufSS. See PIBufSS Configuration, Limitations, and Troubleshooting.

Existing custom AF SDK applications will continue to work without any changes when you upgrade to AF SDK 2.6. The buffering behavior will be defaulted to BufferIfPossible , which means that if PIBufSS is running and its security is properly configured at the destination PI Data Archive, then data writes will be buffered (and also fanned for the case of a collective). Otherwise, data will be written directly without going through PIBufSS (hence will not be fanned for the case of a collective), similar to the behavior in the previous version of AF SDK.

Changes to consider for existing applications

Simple PI Point Data Reference supports buffering of data write to its corresponding PI Data Archive through PI Buffer Subsystem (PIBufSS). Note that a custom data reference (custom DR) developer is responsible to develop a buffering system specific to the custom DR’s corresponding data server it is writing to.

If a data reference (DR) supports buffering of data write, its SupportedDataMethods property should be set to AFDataMethodsBuffering , in addition to AFDataMethodsUpdateValue and/or AFDataMethodsUpdateValues .

In the case of simple PI Point Data Reference, buffering is supported through both UpdateValue and UpdateValues methods. Hence, its SupportedDataMethods property is set to support AFDataMethodsUpdateValue , AFDataMethodsUpdateValues , and AFDataMethodsBuffering (in addition to other AFDataMethods settings).

AF SDK 2.6 and later is bundled with PI Buffer Subsystem (PIBufSS). For example, AF SDK 2.6.0 is bundled with PIBufSS 3.4.380, while AF SDK 2.6.1 with PIBufSS 4.3.

Note
PIBufSS version 4.3 supports buffering to multiple servers and collectives, while previous PIBufSS versions can only buffer data to one server or one collective. PIBufSS 4.3 has an internal setting to enable or disable buffering globally, to a particular server, or to a particular collective member. By default it is set to enable.

- PIBufSS 4.3 and later: see BufferingManager.chm help file and the Buffering section in PI Live Library.

- PIBufSS 3.4.380: see the PI_Buffering_User_Guide.pdf.