onDataReceive - event of the PmaCommGroup object

Description:

The event is triggered after receipt of data from the communication.
The event is triggered even if the communication failed or some (or all) of the data was not retrieved.

The procedure of calling this event depends on the setting of the ""onDataReceive" event" configurator. It is recommended to use the "A = call for all registered variables (in this object and also in other PmaData objects)" setting.

Parameters:

pMe	(Object) Reference to the PmaCommGroup object where the event rises.
pEvent	(Object) Reference to object describing detailed information about the specific event. pEvent.Items - (Array) [for reading] The property is set to various objects depending on the ""onDataReceive" event" configurator setup: - "A = call for all registered variables (in this object and also in other PmaData objects)". Then each item of this array represents the "data extension ExtComm object" of the variable that is defined either in the PmaCommGroup object or in the PmaData object. - "B = call only for variables defined in this object (obsolete)". Then each item of this array represents the PmVar object that is defined in the PmaCommGroup object. Variables in other PmaData objects (having the ExtComm data extension) are not processed here. In both cases if 10 data items are received simultaneously from the communication, then the event is triggered only once and there are these 10 items in the array. pEvent.ErrorCount - (Long) [for reading] The number of data items in the array pEvent.Items, that do not have the Quality property set to Good. pEvent.Attr - (Long) [for reading] Bit attribute. The 3 value (3=1+2) means that all variables were transmitted in a single message. 1 - The first message was transmitted. 2 - The last message was transmitted. This signals that all communicated variables were received.

pMe

(Object) Reference to the PmaCommGroup object where the event rises.

pEvent

(Object) Reference to object describing detailed information about the specific event.

pEvent.Items - (Array) [for reading] The property is set to various objects depending on the ""onDataReceive" event" configurator setup:

- "A = call for all registered variables (in this object and also in other PmaData objects)".
Then each item of this array represents the "data extension ExtComm object" of the variable that is defined either in the PmaCommGroup object or in the PmaData object.

- "B = call only for variables defined in this object (obsolete)".
Then each item of this array represents the PmVar object that is defined in the PmaCommGroup object. Variables in other PmaData objects (having the ExtComm data extension) are not processed here.

In both cases if 10 data items are received simultaneously from the communication, then the event is triggered only once and there are these 10 items in the array.

pEvent.ErrorCount - (Long) [for reading] The number of data items in the array pEvent.Items, that do not have the Quality property set to Good.

pEvent.Attr - (Long) [for reading] Bit attribute.
The 3 value (3=1+2) means that all variables were transmitted in a single message.

1 - The first message was transmitted.

2 - The last message was transmitted. This signals that all communicated variables were received.

Note:

This event is not necessarily called (and usually is not called) simultaneously for all communicated variables.
It is called based on the communication progress - for example if a message is received, containing only 5 variables, then the event is triggered and these 5 variables will be in pEvent.Items, and if another message is received with additional variables, then the event is triggered again, etc.

The event is triggered each time the communication message with values is received.
Is triggered even if the whole communication procedure failed and no values were obtained - if so, then the pEvent.ErrorCount value will be the same as the number of items in pEvent.Items.

The value pEvent.Attr can be used to detect whether the message was the first or the last.
Example:

0 = This message is neither the first nor the last.

3 = This message transmitted all the variables at once so it is both the first and the last.

Triggering of this event can also be emulated in the INFO system when this object is being viewed and the "Actions" button is pressed. See "PmaRoot > Permissions > InfoEdit" permission.

Example:

The ""onDataReceive" event" configurator is set to "A = call for all registered variables (in this object and also in other PmaData objects)".
We will report following information about the received data items into the Debug item of the INFO system:

JavaScriptVBScriptSelect and copy to clipboard



var aItems = pEvent.Items;

var nItems = aItems.GetSize(1);

Pm.Debug("PmaCommGroup.onDataReceive: Size=" + nItems + ", ErrorCount=" + pEvent.ErrorCount);

var i;

for (i = 0; i < nItems; i++)

{

	Pm.Debug(" Name=" + aItems.GetItem(i).Var.Name);

	Pm.Debug(" Value=" + aItems.GetItem(i).Var.Value);

	Pm.Debug(" Quality=" + aItems.GetItem(i).Var.Quality);

	Pm.Debug(" ItemId=" + aItems.GetItem(i).ItemId);

}