Mapping Kinds

When you describe that certain mapping target (e.g. a property) should be mapped to certain mapping source (e.g. an OPC item), there is still a piece of information missing: What exactly is the content of that mapping target? For example, with OPC-DA item, does the mapped element contain the value of the OPC item itself, or the quality, or does it contain the value/timestamp/quality combination, or even something else?

In order to distinguish between these, the live mapping has a concept of a mapping kind. You can choose which kind of mapping to use for certain mapping target. You can also map the same source to multiple targets, each time with a different mapping kind. Using this approach, you can e.g. map the value, timestamp, and quality, each to a separate property.

The mapping kind is specified using the Kind property of the DAItem attribute (for OPC-DA item mappings) on the target member or on the UAData attribute (OPC OPC-UA data mappings).

The following table lists all possible mapping for OPC-DA item mappings. When no mapping kind is specified, the default mapping kind of Value is used.

Kind	Type	Description
Result	OperationResult or a derived type	Map the operation result.
ErrorId	Int32	Map the error ID. Always empty with success.
Exception	Exception or a derived type	Map the exception. null if the operation has been successful.
ErrorMessage	String	Map the error message. An empty string if the operation has been successful.
StatusInfo	StatusInfo	Map the status information.
Vtq	DAVtq or DAVtq<T>	Map the item value/timestamp/quality combination. See Note 1.
Value	Object or T	Map the item value. This is the default mapping kind. See Note 1.
Timestamp	DateTime	Map the timestamp. In UTC. See Note 1.
TimestampLocal	DateTime	Map the timestamp. In local time. See Note 1.
Quality	DAQuality	Map the OPC quality. See Note 1.

For OPC-DA property mappings, the mapping kind is specified using the Kind property of the DAProperty attribute on the target member. The following table lists all possible mapping for OPC-DA property mappings. When no mapping kind is specified, the default mapping kind of Value is used.

Kind	Type	Description
Result	OperationResult or a derived type	Map the operation result.
ErrorId	Int32	Map the error ID. Always empty with success.
Exception	Exception or a derived type	Map the exception. null if the operation has been successful.
ErrorMessage	String	Map the error message. An empty string if the operation has been successful.
StatusInfo	StatusInfo	Map the status information.
Value	Object or T	Map the property value. This is the default mapping kind. See Note 1.

The following table lists all possible mapping for OPC-UA data mappings. When no mapping kind is specified, the default mapping kind of Value is used.

Kind	Type	Description
Result	OperationResult or a derived type	Map the operation result.
ErrorId	Int32	Map the error ID. Always empty with success.
Exception	Exception or a derived type	Map the exception. null if the operation has been successful.
ErrorMessage	String	Map the error message. An empty string if the operation has been successful.
StatusInfo	StatusInfo	Map the status information.
AttributeData	UAAttributeData or UAAttributeData <T>	Map the attribute value/source timestamp/server timestamp/status code combination. See Note 1.
Value	Object or T	Map the item value. This is the default mapping kind. See Note 1.
ServerTimestamp	DateTime	Map the server timestamp. In UTC. See Note 1.
ServerTimestampLocal	DateTime	Map the server timestamp. In local time. See Note 1.
SourceTimestamp	DateTime	Map the source timestamp. In UTC. See Note 1.
SourceTimestampLocal	DateTime	Map the source timestamp. In local time. See Note 1.
StatusCode	UAStatusCode	Map the status code. See Note 1.

Note 1: The mapping target value is not changed if the operation resulted in an exception. This means that when an error occurs, the mapping target with this mapping kind will not be reset to null or other default value; in fact it won’t be influenced at all. E.g. if an item’s value (a property annotated with mapping kind of Value) is successfully obtained once, and then an error occurs in a subsequent operation, the target property will remain unchanged. You can detect the error by additional mappings with different mapping kinds (e.g. Exception).