Knowledge Base / Version 22 / System Admin Duties / Canary Historian

Understanding Quality Codes (version 22)

updated 2 yrs ago

Canary provides the capability to write quality score as part of the tag timestamp and value whenever it is included from the data source. OPC standards are followed with an additional Canary quality code that signifies NoData.

For most, the following four quality codes will handle 99% of your use cases.

Most Common Quality Codes

0	OPC	Bad
192	OPC	Good
64	OPC	Uncertain
32768	Canary	NoData

In addition to these quality codes, the standard OPC DA quality codes can be useful to have as a reference.

OPC DA Quality Codes

Here is the complete list of all OPC DA quality codes including the corresponding decimal (column 1) and hex value (column 2).

0	0x00000000	Bad [Non-Specific]
4	0x00000004	Bad [Configuration Error]
8	0x00000008	Bad [Not Connected]
12	0x0000000c	Bad [Device Failure]
16	0x00000010	Bad [Sensor Failure]
20	0x00000014	Bad [Last Known Value]
24	0x00000018	Bad [Communication Failure]
28	0x0000001C	Bad [Out of Service]
64	0x00000040	Uncertain [Non-Specific]
65	0x00000041	Uncertain [Non-Specific] (Low Limited)
66	0x00000042	Uncertain [Non-Specific] (High Limited)
67	0x00000043	Uncertain [Non-Specific] (Constant)
68	0x00000044	Uncertain [Last Usable]
69	0x00000045	Uncertain [Last Usable] (Low Limited)
70	0x00000046	Uncertain [Last Usable] (High Limited)
71	0x00000047	Uncertain [Last Usable] (Constant)
80	0x00000050	Uncertain [Sensor Not Accurate]
81	0x00000051	Uncertain [Sensor Not Accurate] (Low Limited)
82	0x00000052	Uncertain [Sensor Not Accurate] (High Limited)
83	0x00000053	Uncertain [Sensor Not Accurate] (Constant)
84	0x00000054	Uncertain [EU Exceeded]
85	0x00000055	Uncertain [EU Exceeded] (Low Limited)
86	0x00000056	Uncertain [EU Exceeded] (High Limited)
87	0x00000057	Uncertain [EU Exceeded] (Constant)
88	0x00000058	Uncertain [Sub-Normal]
89	0x00000059	Uncertain [Sub-Normal] (Low Limited)
90	0x0000005a	Uncertain [Sub-Normal] (High Limited)
91	0x0000005b	Uncertain [Sub-Normal] (Constant)
192	0x000000c0	Good [Non-Specific]
193	0x000000c1	Good [Non-Specific] (Low Limited)
194	0x000000c2	Good [Non-Specific] (High Limited)
195	0x000000c3	Good [Non-Specific] (Constant)
216	0x000000d8	Good [Local Override]
217	0x000000d9	Good [Local Override] (Low Limited)
218	0x000000da	Good [Local Override] (High Limited)
219	0x000000db	Good [Local Override] (Constant)

For those that need or want to dive much deeper below is a complete guide to understanding the ins and outs of quality codes.

Historian Quality Bits

The low 8 bits of the quality are defined as follows in the OPC Specification. These flags represent the quality state for an item's data value. This is intended to be similar to but slightly simpler than the Fieldbus Data Quality Specification (section 4.4.1 in the H1 Final Specifications). This design makes it fairly easy for both servers and client applications to determine how much functionality they want to implement.

The low 8 bits of the Quality flags are currently defined in the form of three bit fields; Quality, Substatus and Limit status. The 8 Quality bits are arranged as follows:

QQSSSSLL

The high 8 bits of the Quality Word are available for vendor specific use. If these bits are used, the standard OPC Quality bits must still be set as accurately as possible to indicate what assumptions the client can make about the returned data. In addition, it is the responsibility of any client interpreting vendor specific quality information to ensure that the server providing it uses the same 'rules' as the client. The details of such a negotiation are not specified in this standard although a QueryInterface call to the server for a vendor specific interface such as MyQualityDefinitions is a possible approach.

Details of the OPC standard quality bits follow:

The Quality Bit Field

QQ	BIT VALUE	DEFINE	DESCRIPTION
0 .	00SSSSLL	Bad	Value is not useful for reasons indicated by the Sub-status
1	01SSSSLL	Uncertain	The quality of the value is uncertain for reasons indicated by the Sub-status.
2	10SSSSLL	N/A	Not used by OPC
3	11SSSSLL	Good	The Quality of the value is Good.

A server which supports no quality information must return 3 (Good). It is also acceptable for a server to simply return Bad or Good (0x00 or 0xC0) and to always return 0 for sub-status and limit.

It is recommended that clients minimally check the Quality Bit field of all results (even if they do not check the sub-status or limit fields). Even when a 'BAD' value is indicated, the contents of the value field must still be a well defined VARIANT even though it does not contain an accurate value. This is to simplify error handling in client applications. For example, clients are always expected to call VariantClear() on the results of a Synchronous Read. Similarly the IAdviseSink needs to be able to interpret and 'unpack' the Value and Data included in the Stream even if that data is BAD.
If the server has no known value to return then some reasonable default should be returned such as a NUL string or a 0 numeric value.

The Sub-status Bit Field

The layout of this field depends on the value of the Quality Field.

Sub-status for BAD Quality:

0	000000LL	Non-specific	The value is bad but no specific reason is known
1	000001LL	Configuration Error	There is some server specific problem with the configuration. For example the item is question has been deleted from the configuration.
2	000010LL	Not Connected	The input is required to be logically connected to something but is not. This quality may reflect that no value is available at this time, for reasons like the value may have not been provided by the data source.
3	000011LL	Device Failure	A device failure has been detected
4	000100LL	Sensor Failure	A sensor failure had been detected (the 'Limits' field can provide additional diagnostic information in some situations.)
5	000101LL	Last Known Value	Communications have failed. However, the last known value is available. Note that the 'age' of the value may be determined from the TIMESTAMP in the OPCITEMSTATE.
6	000110LL	Comm Failure	Communications have failed. There is no last known value is available.
7	000111LL	Out of Service	The block is off scan or otherwise locked This quality is also used when the active state of the item or the group containing the item is InActive.
8-15	N/A	Not used by OPC

Servers which do not support Sub-status should return 0.
An 'old' value may be returned with the Quality set to BAD (0) and the Substatus set to 5. This is for consistency with the Fieldbus Specification. This is the only case in which a client may assume that a 'BAD' value is still usable by the application.

Sub-status for UNCERTAIN Quality:

SSSS	BIT VALUE	DEFINE	DESCRIPTION
0	010000LL	Non-specific	There is no specific reason why the value is uncertain.
1	010001LL	Last Usable Value	Whatever was writing this value has stopped doing so. The returned value should be regarded as 'stale'. Note that this differs from a BAD value with Substatus 5 (Last Known Value). That status is associated specifically with a detectable communications error on a 'fetched' value. This error is associated with the failure of some external source to 'put' something into the value within an acceptable period of time. Note that the 'age' of the value can be determined from the TIMESTAMP in OPCITEMSTATE.
2-3		N/A	Not used by OPC
4	010100LL	Sensor Not Accurate	Either the value has 'pegged' at one of the sensor limits (in which case the limit field should be set to 1 or 2) or the sensor is otherwise known to be out of calibration via some form of internal diagnostics (in which case the limit field should be 0).
5	010101LL	Engineering Units Exceeded	The returned value is outside the limits defined for this parameter. Note that in this case (per the Fieldbus Specification) the 'Limits' field indicates which limit has been exceeded but does NOT necessarily imply that the value cannot move farther out of range.
6	010110LL	Sub-Normal	The value is derived from multiple sources and has less than the required number of Good sources.
7-15		N/A	Not used by OPC

Servers which do not support Sub-status should return 0.

Sub-status for GOOD Quality:

SSSS	BIT VALUE	DEFINE	DESCRIPTION
0	110000LL	Non-specific	The value is good. There are no special conditions
1-5		N/A	Not used by OPC
6	110110LL	Local Override	The value has been Overridden. Typically this is means the input has been disconnected and a manually entered value has been 'forced'.
7-15		N/A	Not used by OPC

Servers which do not support Sub-status should return 0.

The Limit Bit Field

The Limit Field is valid regardless of the Quality and Sub-status. In some cases such as Sensor Failure it can provide useful diagnostic information.

LL	BIT VALUE	DEFINE	DESCRIPTION
0	QQSSSS00	Not Limited	The value is free to move up or down
1	QQSSSS01	Low Limited	The value has 'pegged' at some lower limit
2	QQSSSS10	High Limited	The value has 'pegged' at some high limit.
3	QQSSSS11	Constant	The value is a constant and cannot move.

Servers which do not support Limit should return 0.
Symbolic Equates are defined for values and masks for these BitFields in the "QUALITY" section of the OPC header files.

High 8 Bits of the Quality (Canary Defined Bits)

0x8000	No Data (There can be other bits also)
0xE000	NoData (Edge of the Data - i.e. There is no data prior to this)
0x4000	Inserted TVQ
0x2000	Modified TVQ
0x1000	Deleted TVQ
0x800	Reserved - currently unused
0x400	Reserved - currently unused
0x200	When this bit is set, the TVQ was inserted or replaced without audit information. This Quality can be passed
0x100	This is a reserved bit – used internally by the Historian – When this bit is set, it signifies that there is “Extra Data” associated with the TVQ such as (Audit info on inserts, replace, delete, such as when, who, what it changed from, and why information).

The Aggregates

Also sets some of the bits when computing the aggregates.

The OPC bits are maintained in the low bits

0x100	Partial (Doesn't cover the full aggregate interval)
0x200	Multiple values (when returning min, max, and average values for each aggregate interval)
0x400	Aggregate value is an interpolated value
0x800	This is a calculated value