A StatusCode in OPC UA is numerical value that is used to report the outcome of an operation performed by an OPC UA Server. This code may have associated diagnostic information that describes the status in more detail; however, the code by itself is intended to provide Client applications with enough information to make decisions on how to process the results of an OPC UA Service.
The StatusCode is a 32-bit unsigned integer. The top 16 bits represent the numeric value of the code that shall be used for detecting specific errors or conditions. The bottom 16 bits are bit flags that contain additional information but do not affect the meaning of the StatusCode.
All OPC UA Clients shall always check the StatusCode associated with a result before using it. Results that have an uncertain/warning status associated with them shall be used with care since these results might not be valid in all situations. Results with a bad/failed status shall never be used.
OPC UA Servers should return good/success StatusCodes if the operation completed normally and the result is always valid. Different StatusCode values can provide additional information to the Client.
OPC UA Servers should use uncertain/warning StatusCodes if they could not complete the operation in the manner requested by the Client, however, the operation did not fail entirely.
The list of StatusCodes is managed by OPC UA. The complete list of StatusCodes is defined in OPC 10000-6. Servers shall not define their own StatusCodes. OPC UA companion working groups may request additional StatusCodes from the OPC Foundation to be added to the list in OPC 10000-6.
The exact bit assignments are shown in Table 180.
Table 180 – StatusCode bit assignments
|
Field |
Bit Range |
Description |
||||||||||||
|
Severity |
30:31 |
Indicates whether the StatusCode represents a good, bad or uncertain condition. These bits have the following meanings:
|
||||||||||||
|
Reserved |
29:29 |
Reserved for use in OPC UA application specific APIs. This bit shall always be zero on the wire but may be used by OPC UA application specific APIs for API specific status codes. |
||||||||||||
|
Reserved |
28:28 |
Reserved for future use. Shall always be zero. |
||||||||||||
|
SubCode |
16:27 |
The code is a numeric value assigned to represent different conditions. Each code has a symbolic name and a numeric value. All descriptions in the OPC UA specification refer to the symbolic name. OPC 10000-6 maps the symbolic names onto a numeric value. |
||||||||||||
|
StructureChanged |
15:15 |
Indicates that the structure of the associated data value has changed since the last Notification. Clients should not process the data value unless they re-read the metadata. Servers shall set this bit if the DataTypeDefinition of the DataType used for a Variable changes. This bit is provided to warn Clients that parse complex data values that their parsing routines could fail because the serialized form of the data value has changed. This bit has meaning only for StatusCodes returned as part of a data change Notification or the HistoryRead. StatusCodes used in other contexts shall always set this bit to zero. The bit is set on one data change Notification per MonitoredItem that samples values at the time the structure change happened. If the data change notification with the bit set is deleted because of a queue overflow, the bit shall be set on the next data change notification in the queue. |
||||||||||||
|
SemanticsChanged |
14:14 |
Indicates that the semantics of the associated data value have changed. Clients should not process the data value until they re-read the metadata associated with the Variable. Servers should set this bit if the metadata has changed in way that could cause application errors if the Client does not re-read the metadata. For example, a change to the engineering units could create problems if the Client uses the value to perform calculations. OPC 10000-8 defines the conditions where a Server shall set this bit for a DA Variable. Other specifications may define additional conditions. A Server may define other conditions that cause this bit to be set. This bit has meaning only for StatusCodes returned as part of a data change Notification or the HistoryRead. StatusCodes used in other contexts shall always set this bit to zero. The bit is set on one data change Notification per MonitoredItem that samples values at the time the semantic change happened. If the data change notification with the bit set is deleted because of a queue overflow, the bit shall be set on the next data change notification in the queue. |
||||||||||||
|
Reserved |
12:13 |
Reserved for future use. Shall always be zero. |
||||||||||||
|
InfoType |
10:11 |
The type of information contained in the info bits. These bits have the following meanings:
|
||||||||||||
|
InfoBits |
0:9 |
Additional information bits that qualify the StatusCode. The structure of these bits depends on the Info Type field. |
Table 181 describes the structure of the InfoBits when the Info Type is set to DataValue (01).
Table 181 – DataValue InfoBits
|
Info Type |
Bit Range |
Description |
|||||||||||||||||||||
|
LimitBits |
8:9 |
The limit bits associated with the data value. The limits bits have the following meanings:
|
|||||||||||||||||||||
|
Overflow |
7 |
This bit shall only be set if the MonitoredItem queue size is greater than 1. If this bit is set, not every detected change has been returned since the Server’s queue buffer for the MonitoredItem reached its limit and had to purge out data. |
|||||||||||||||||||||
|
Reserved |
5:6 |
Reserved for future use. Shall always be zero. |
|||||||||||||||||||||
|
HistorianBits |
0:4 |
These bits are set only when reading historical data. They indicate where the data value came from and provide information that affects how the Client uses the data value. The historian bits have the following meaning:
OPC 10000-11 describes how these bits are used in more detail. |
Table 182 defines the common StatusCodes for all Service results used in more than one service. It does not provide a complete list. These StatusCodes may also be used as operation level result code. OPC 10000-6 maps the symbolic names to a numeric value and provides a complete list of StatusCodes including codes defines in other parts.
Table 182 – Common Service Result Codes
|
Symbolic Id |
Description |
|
Good |
The operation was successful. |
|
Good_CompletesAsynchronously |
The processing will complete asynchronously. |
|
Good_SubscriptionTransferred |
The Subscription was transferred to another session. |
|
|
|
|
Bad_CertificateHostNameInvalid
|
The HostName used to connect to a Server does not match a HostName in the Certificate. |
|
Bad_CertificateChainIncomplete |
The Certificate chain is incomplete. |
|
Bad_CertificateIssuerRevocationUnknown |
It was not possible to determine if the Issuer Certificate has been revoked. |
|
Bad_CertificateIssuerUseNotAllowed |
The Issuer Certificate may not be used for the requested operation. |
|
Bad_CertificateIssuerTimeInvalid |
An Issuer Certificate has expired or is not yet valid. |
|
Bad_CertificateIssuerRevoked |
The Issuer Certificate has been revoked. |
|
Bad_CertificateInvalid |
The Certificate provided as a parameter is not valid. |
|
Bad_CertificateRevocationUnknown |
It was not possible to determine if the Certificate has been revoked. |
|
Bad_CertificateRevoked |
The Certificate has been revoked. |
|
Bad_CertificateTimeInvalid |
The Certificate has expired or is not yet valid. |
|
Bad_CertificateUriInvalid |
The URI specified in the ApplicationDescription does not match the URI in the Certificate. |
|
Bad_CertificateUntrusted |
The Certificate is not trusted. |
|
Bad_CertificateUseNotAllowed |
The Certificate may not be used for the requested operation. |
|
Bad_CommunicationError |
A low level communication error occurred. |
|
Bad_DataTypeIdUnknown |
The ExtensionObject cannot be (de)serialized because the data type id is not recognized. |
|
Bad_DecodingError |
Decoding halted because of invalid data in the stream. |
|
Bad_EncodingError |
Encoding halted because of invalid data in the objects being serialized. |
|
Bad_EncodingLimitsExceeded |
The message encoding/decoding limits imposed by the Communication Stack have been exceeded. |
|
Bad_IdentityTokenInvalid |
The user identity token is not valid. |
|
Bad_IdentityTokenRejected |
The user identity token is valid but the Server has rejected it. |
|
Bad_InternalError |
An internal error occurred as a result of a programming or configuration error. |
|
Bad_InvalidArgument |
One or more arguments are invalid. Each service defines parameter-specific StatusCodes and these StatusCodes shall be used instead of this general error code. This error code shall be used only by the Communication Stack and in services where it is defined in the list of valid StatusCodes for the service. |
|
Bad_InvalidState |
The operation cannot be completed because the object is closed, uninitialized or in some other invalid state. |
|
Bad_InvalidTimestamp |
The timestamp is outside the range allowed by the Server. |
|
Bad_LicenseExpired |
The UA Server requires a license to operate in general or to perform a service or operation, but existing license is expired |
|
Bad_LicenseLimitsExceeded |
The UA Server has limits on number of allowed operations / objects, based on installed licenses, and these limits where exceeded. |
|
Bad_LicenseNotAvailable |
The UA Server does not have a license which is required to operate in general or to perform a service or operation. |
|
Bad_NonceInvalid |
The nonce does appear to be not a random value or it is not the correct length. |
|
Bad_NothingToDo |
No processing could be done because there was nothing to do. For Service level results the code is used if the Client passed a list of operations with no elements. |
|
Bad_OutOfMemory |
Not enough memory to complete the operation. |
|
Bad_RequestCancelledByClient |
The request was cancelled by the Client. |
|
Bad_RequestTooLarge |
The request message size exceeds limits set by the Server. |
|
Bad_ResponseTooLarge |
The response message size exceeds limits set by the Client or Server. |
|
Bad_RequestHeaderInvalid |
The header for the request is missing or invalid. |
|
Bad_ResourceUnavailable |
An operating system resource is not available. |
|
Bad_SecureChannelIdInvalid |
The specified secure channel is no longer valid. |
|
Bad_SecurityChecksFailed |
An error occurred while verifying security. |
|
Bad_SecurityPolicyRejected |
The security policy does not meet the requirements set by the Server. |
|
Bad_ServerHalted |
The Server has stopped and cannot process any requests. |
|
Bad_ServerNotConnected |
The operation could not complete because the Client is not connected to the Server. |
|
Bad_ServerTooBusy |
The Server does not have the resources to process the request at this time. This can be caused by a general overload of the Server or an overload by the Client that receives the result code. |
|
Bad_ServerUriInvalid |
The Server URI is not valid. |
|
Bad_ServiceUnsupported |
The Server does not support the requested service. |
|
Bad_SessionIdInvalid |
The Session id is not valid. |
|
Bad_SessionClosed |
|
|
Bad_SessionNotActivated |
The Session cannot be used because ActivateSession has not been called. |
|
Bad_Shutdown |
The operation was cancelled because the application is shutting down. |
|
Bad_SubscriptionIdInvalid |
The Subscription id is not valid. The Subscription id is not known or is not valid in the context of the Session used to call the Subscription related Service. |
|
Bad_Timeout |
The operation timed out. |
|
Bad_TimestampsToReturnInvalid |
The timestamps to return parameter is invalid. |
|
Bad_TooManyOperations |
The request could not be processed because it specified too many operations. |
|
Bad_UnexpectedError |
An unexpected error occurred. |
|
Bad_UnknownResponse |
An unrecognized response was received from the Server. |
|
Bad_UserAccessDenied |
User does not have permission to perform the requested operation. |
|
Bad_ViewIdUnknown |
The view id does not refer to a valid view Node. |
|
Bad_ViewTimestampInvalid |
The view timestamp is not available or not supported. |
|
Bad_ViewParameterMismatchInvalid |
The view parameters are not consistent with each other. |
|
Bad_ViewVersionInvalid |
The view version is not available or not supported. |
Table 183 defines the common StatusCodes for all operation level results used in more than one service. It does not provide a complete list. OPC 10000-6 maps the symbolic names to a numeric value and provides a complete list of StatusCodes including codes defines in other parts. The common Service result codes can be also contained in the operation level.
Table 183 – Common Operation Level Result Codes
|
Symbolic Id |
Description |
|
Good_Clamped |
The value written was accepted but was clamped. |
|
Good_Overload |
Sampling has slowed down due to resource limitations. |
|
|
|
|
Uncertain |
The value is uncertain but no specific reason is known. |
|
|
|
|
Bad |
The value is bad but no specific reason is known. |
|
Bad_AttributeIdInvalid |
The attribute is not supported for the specified node. |
|
Bad_BrowseDirectionInvalid |
The browse direction is not valid. |
|
Bad_BrowseNameInvalid |
The browse name is invalid. |
|
Bad_ContentFilterInvalid |
The content filter is not valid. |
|
Bad_ContinuationPointInvalid |
The continuation point provided is no longer valid. This status is returned if the continuation point was deleted or the address space was changed between the browse calls. |
|
Bad_DataEncodingInvalid |
The data encoding is invalid. This result is used if no dataEncoding can be applied because an Attribute other than Value was requested or the DataType of the Value Attribute is not a subtype of the Structure DataType. |
|
Bad_DataEncodingUnsupported |
The Server does not support the requested data encoding for the node. This result is used if a dataEncoding can be applied but the passed data encoding is not known to the Server. |
|
Bad_EventFilterInvalid |
The event filter is not valid. |
|
Bad_FilterNotAllowed |
A monitoring filter cannot be used in combination with the attribute specified. |
|
Bad_FilterOperandInvalid |
The operand used in a content filter is not valid. |
|
Bad_HistoryOperationInvalid |
The history details parameter is not valid. |
|
Bad_HistoryOperationUnsupported |
The Server does not support the requested operation. |
|
Bad_IndexRangeInvalid |
The syntax of the index range parameter is invalid. |
|
Bad_IndexRangeNoData |
No data exists within the range of indexes specified. |
|
Bad_MonitoredItemFilterInvalid |
The monitored item filter parameter is not valid. |
|
Bad_MonitoredItemFilterUnsupported |
The Server does not support the requested monitored item filter. |
|
Bad_MonitoredItemIdInvalid |
The monitoring item id does not refer to a valid monitored item. |
|
Bad_MonitoringModeInvalid |
The monitoring mode is invalid. |
|
Bad_NoCommunication |
Communication with the data source is defined, but not established, and there is no last known value available. This status/sub-status is used for cached values before the first value is received or for Write and Call if the communication is not established. |
|
Bad_NoContinuationPoints |
The operation could not be processed because all continuation points have been allocated. |
|
Bad_NodeClassInvalid |
The node class is not valid. |
|
Bad_NodeIdInvalid |
The syntax of the node id is not valid or refers to a node that is not valid for the operation. |
|
Bad_NodeIdUnknown |
The node id refers to a node that does not exist in the Server address space. |
|
Bad_NoDeleteRights |
The Server will not allow the node to be deleted. |
|
Bad_NodeNotInView |
The nodesToBrowse is not part of the view. |
|
Bad_NotFound |
A requested item was not found or a search operation ended without success. |
|
Bad_NotImplemented |
Requested operation is not implemented. |
|
Bad_NoValue |
There is no value available. The status is used if a Variable is created and no default value or no initial value is available. |
|
Bad_NotReadable |
The access level does not allow reading or subscribing to the Node. |
|
Bad_NotSupported |
The requested operation is not supported. |
|
Bad_NotWritable |
The access level does not allow writing to the Node. |
|
Bad_ObjectDeleted |
The Object cannot be used because it has been deleted. |
|
Bad_OutOfRange |
The value was out of range. |
|
Bad_ReferenceTypeIdInvalid |
The reference type id does not refer to a valid reference type node. |
|
Bad_SecurityModeInsufficient |
The SecurityPolicy and/or MessageSecurityMode do not match the Server requirements to complete the operation. For example, a user may have the right to receive the data but the data can only be transferred through an encrypted channel with an appropriate SecurityPolicy. |
|
Bad_SourceNodeIdInvalid |
The source node id does not refer to a valid node. |
|
Bad_StructureMissing |
A mandatory structured parameter was missing or null. |
|
Bad_TargetNodeIdInvalid |
The target node id does not refer to a valid node. |
|
Bad_TypeDefinitionInvalid |
The type definition node id does not reference an appropriate type node. |
|
Bad_TypeMismatch |
The value supplied for the attribute is not of the same type as the attribute's value. |
|
Bad_WaitingForInitialData |
Waiting for the Server to obtain values from the underlying data source. After creating a MonitoredItem or after setting the MonitoringMode from DISABLED to REPORTING or SAMPLING, it may take some time for the Server to actually obtain values for these items. In such cases the Server can send a Notification with this status prior to the Notification with the first value or status from the data source. |