Standard EMP Implementation Key-Value Pair Buffer

In the standard system, SAP delivers the EMP implementation KvpBuffer that represents a key-value pair buffer. You can use the implementation to convert every agent instance into a buffer agent instance.

Function of the Buffer

Using the buffer, you can, using method calls, store data in the form of key-value pairs and then enrich notification messages with this data.

The prerequisite for using the implementation is that you are running the agent instance as an OPC UA server or as a PCo Web server.

The buffer entries can be persisted in the local file system or not persisted in the working memory only. Different callers can access the same buffer data.

Example

A production line has a transport system of carriers. Each carrier has a unique ID. There might be a product on each carrier that corresponds to an SFC in the SAP Manufacturing Execution system. You want the assignment of carrier ID to SFC to be retained and this assignment must not be lost if the PCo agent instance has to be restarted.
A machine delivers measurement values frequently that are written via an OPC UA agent to an SAP HANA database as a tag-based notification. You want to enrich the measurement values with the name of the worker who is currently on shift. The worker’s name is kept in PCo and updated three times a day via an SAP MII user interface.

Implementation Methods

The implementation provides the following methods:

Implementation Methods
Method	Input Parameter	Output Parameter	Function
_ClearBuffer			Deletes all keys and values from the buffer.
_GetAllKeys		outKeys	Provides a string array outKeys that contains all the keys that are currently in the buffer.
_GetAllKeyValuePairs	inClearBuffer	outKeyValuePairs	Provides a string array outKeyValuePairs that contains all the key-value pairs that are currently in the buffer. If the input parameter inClearBuffer is set to the value True, the entire buffer is emptied after all key-value pairs have been read.
_GetAllKeyValuePairsJson	inClearBuffer	outKeyValuePairs	Provides a JSON-formatted character string outKeyValuePairs that contains all the key-value pairs that are currently in the buffer. If the input parameter inClearBuffer is set to the value True, the entire buffer is emptied after all key-value pairs have been read.
_GetKeysByValue	inValue	outKeys	Returns a string array outKeys that contains all keys that have the value inValue.
_GetNumEntries		outNumEntries	In the output parameter outNumEntries returns the number of all key-value pairs that are currently in the buffer.
_GetValueByKey	inKey	outSuccess outValue	Returns the value outValue for the key inKey. If the key inKey is in the buffer, the output parameter is outSuccess True; otherwise it is False.
_KeyExists	inKey	outKeyExists	Checks if the key inKey occurs in the buffer. If the key does occur, the output parameter outKeyExists is set to True, otherwise it is set to False.
_RemoveKey	inKey	outSuccess	Deletes the key-value pair with the key inKey from the buffer. If the key inKey existed in the buffer before deletion, the output parameter outSuccess is set to True, otherwise it is set to False.
_SetKeyValue	inKey inValue inPersistent		If the key inKey does not yet occur in the buffer, the method adds a new key-value pair with the key inKey and the value inValue. If the key inKey already occurs, the value of the key-value pair is updated. If inPersistent is set to True, the key-value pair is written to the local data carrier and is still available after the agent instance is restarted. If inPersistent is set to False, the key-value pair is only kept in the working memory.

If you set the input parameter inPersistent to True in the _SetKeyValue method, the EMP implementation KvpBuffer generates the directory C:\ProgramData\SAP\EMP_KvpBuffer\[ID of agent instance] in the Windows directory ProgramData and generates a file for each key-value pair with the key as file name and the value as file content. For this reason, the key inKey must only contain characters that are permitted in a Windows file name if you want to persist the entry. In general, the EMP implementation ignores and cuts off spaces before and after a key.

You can determine the ID of the agent instance from the XML file, for example, after the export of the agent instance.