This Service is used to issue a Query request to the Server. The complexity of the Query can range from very simple to highly sophisticated. The Query can simply request data from instances of a TypeDefinitionNode or TypeDefinitionNode subject to restrictions specified by the filter. On the other hand, the Query can request data from instances of related Node types by specifying a RelativePath from an originating TypeDefinitionNode. In the filter, a separate set of paths can be constructed for limiting the instances that supply data. A filtering path can include multiple RelatedTo operators to define a multi-hop path between source instances and target instances. For example, one could filter on students that attend a particular school, but return information about students and their families. In this case, the student school relationship is traversed for filtering, but the student family relationship is traversed to select data. For a complete description of ContentFilter see 7.7, also see Clause B.1 for simple examples and Clause B.2 for more complex examples of content filter and queries.
The Client provides an array of NodeTypeDescription which specify the NodeId of a TypeDefinitionNode and selects what Attributes are to be returned in the response. A Client can also provide a set of RelativePaths through the type system starting from an originating TypeDefinitionNode. Using these paths, the Client selects a set of Attributes from Nodes that are related to instances of the originating TypeDefinitionNode. Additionally, the Client can request the Server return instances of subtypes of TypeDefinitionNodes. If a selected Attribute does not exist in a TypeDefinitionNode but does exist in a subtype, it is assumed to have a null value in the TypeDefinitionNode in question. Therefore, this does not constitute an error condition and a null value is returned for the Attribute.
The Client can use the filter parameter to limit the result set by restricting Attributes and Properties to certain values. Another way the Client can use a filter to limit the result set is by specifying how instances should be related, using RelatedTo operators. In this case, if an instance at the top of the RelatedTo path cannot be followed to the bottom of the path via specified hops, no QueryDataSets are returned for the starting instance or any of the intermediate instances.
When querying for related instances in the RelativePath, the Client can optionally ask for References. A Reference is requested via a RelativePath that only includes a ReferenceType. If all References are desired than the root ReferenceType is listed. These References are returned as part of the QueryDataSets.
Query Services allow a special handling of the targetName field in the RelativePath. In several Query use cases a type NodeId is necessary in the path instead of a QualifiedName. Therefore the Client is allowed to specify a NodeId in the QualifiedName. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6. When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.
Table 47 defines the request parameters and Table 48 the response parameters for the QueryFirst Service.
Table 47 – QueryFirst Request Parameters
|
Name |
Type |
Description |
|
Request |
|
|
|
requestHeader |
RequestHeader |
Common request parameters (see 7.33 for RequestHeader definition). |
|
View |
ViewDescription |
Specifies a View and temporal context to a Server (see 7.45 for ViewDescription definition). |
|
nodeTypes [] |
NodeTypeDescription |
This is the Node type description. This structure is defined in-line with the following indented items. |
|
typeDefinitionNode |
ExpandedNodeId |
NodeId of the originating TypeDefinitionNode of the instances for which data is to be returned. |
|
includeSubTypes |
Boolean |
A flag that indicates whether the Server should include instances of subtypes of the TypeDefinitionNode in the list of instances of the Node type. |
|
dataToReturn [] |
QueryDataDescription |
Specifies an Attribute or Reference from the originating typeDefinitionNode along a given relativePath for which to return data. This structure is defined in-line with the following indented items. |
|
relativePath |
RelativePath |
Browse path relative to the originating Node that identifies the Node which contains the data that is being requested, where the originating Node is an instance Node of the type defined by the type definition Node. The instance Nodes are further limited by the filter provided as part of this call. For a definition of relativePath see 7.31. This relative path could end on a Reference, in which case the ReferenceDescription of the Reference would be returned as its value. The targetName field of the relativePath may contain a type NodeId. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6. When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type. |
|
attributeId |
IntegerId |
Id of the Attribute. This shall be a valid Attribute Id. The IntegerId is defined in 7.19. The IntegerId for Attributes are defined in OPC 10000-6. If the RelativePath ended in a Reference then this parameter is 0 and ignored by the Server. |
|
indexRange |
NumericRange |
This parameter is used to identify a single element of a structure or an array, or a single range of indexes for arrays. If a range of elements are specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.27. This parameter is null or empty if the specified Attribute is not an array or a structure. However, if the specified Attribute is an array or a structure, and this parameter is null or empty, then all elements are to be included in the range. |
|
Filter |
ContentFilter |
Resulting Nodes shall be limited to the Nodes matching the criteria defined by the filter. ContentFilter is discussed in 7.7. If an empty filter is provided then the entire AddressSpace shall be examined and all Nodes that contain a matching requested Attribute or Reference are returned. |
|
maxDataSetsToReturn |
Counter |
The number of QueryDataSets that the Client wants the Server to return in the response and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit. A value of 0 indicates that the Client is imposing no limitation. |
|
maxReferencesToReturn |
Counter |
The number of References that the Client wants the Server to return in the response for each QueryDataSet and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit. A value of 0 indicates that the Client is imposing no limitation. For example a result where 4 Nodes are being returned, but each has 100 References, if this limit were set to 50 then only the first 50 References for each Node would be returned on the initial call and a continuation point would be set indicating additional data. |
Table 48 – QueryFirst Response Parameters
|
Name |
Type |
Description |
|
Response |
|
|
|
responseHeader |
ResponseHeader |
Common response parameters (see 7.34 for ResponseHeader definition). |
|
queryDataSets [] |
QueryDataSet |
The array of QueryDataSets. This array is empty if no Nodes or References met the nodeTypes criteria. In this case the continuationPoint parameter shall be empty. The QueryDataSet type is defined in 7.28. |
|
continuationPoint |
ContinuationPoint |
Server-defined opaque value that identifies the continuation point. The continuation point is used only when the Query results are too large to be returned in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of QueryDataSets to return exceeds the maximum number of QueryDataSets to return that was specified by the Client in the request. The continuation point is used in the QueryNext Service. When not used, the value of this parameter is null or empty. If a continuation point is returned, the Client shall call QueryNext to get the next set of QueryDataSets or to free the resources for the continuation point in the Server. A continuation point shall remain active until the Client passes the continuation point to QueryNext or the session is closed. If the maximum continuation points have been reached the oldest continuation point shall be reset. The ContinuationPoint type is described in 7.9. |
|
parsingResults[] |
ParsingResult |
List of parsing results for QueryFirst. The size and order of the list matches the size and order of the NodeTypes request parameter. This structure is defined in-line with the following indented items. This list is populated with any status codes that are related to the processing of the node types that are part of the query. The array can be empty if no errors where encountered. If any node type encountered an error all node types shall have an associated status code. |
|
statusCode |
StatusCode |
Parsing result for the requested NodeTypeDescription. |
|
dataStatusCodes [] |
StatusCode |
List of results for dataToReturn. The size and order of the list matches the size and order of the dataToReturn request parameter. The array can be empty if no errors where encountered. |
|
dataDiagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information dataToReturn (see 7.12 for DiagnosticInfo definition). The size and order of the list matches the size and order of the dataToReturn request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the query request. |
|
diagnosticInfos [] |
DiagnosticInfo |
List of diagnostic information for the requested NodeTypeDescription. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the query request. |
|
filterResult |
ContentFilter Result |
A structure that contains any errors associated with the filter. This structure shall be empty if no errors occurred. The ContentFilterResult type is defined in 7.7.2. |
If the Query is invalid or cannot be processed, then QueryDataSets are not returned and only a Service result, filterResult, parsingResults and optional DiagnosticInfo is returned. Table 49 defines the Service results specific to this Service. Common StatusCodes are defined in Table 182.
Table 49 – QueryFirst Service Result Codes
|
Symbolic Id |
Description |
|
Bad_NothingToDo |
See Table 182 for the description of this result code. |
|
Bad_TooManyOperations |
See Table 182 for the description of this result code. |
|
Bad_ContentFilterInvalid |
See Table 183 for the description of this result code. |
|
Bad_ViewIdUnknown |
See Table 182 for the description of this result code. |
|
Bad_ViewTimestampInvalid |
See Table 182 for the description of this result code. |
|
Bad_ViewParameterMismatchInvalid |
See Table 182 for the description of this result code. |
|
Bad_ViewVersionInvalid |
See Table 182 for the description of this result code. |
|
Bad_InvalidFilter |
The provided filter is invalid, see the filterResult for specific errors |
|
Bad_NodelistError |
The NodeTypes provided contain an error, see the parsingResults for specific errors |
|
Bad_InvalidView |
The provided ViewDescription is not a valid ViewDescription. |
|
Good_ResultsMayBeIncomplete |
The Server should have followed a reference to a node in a remote Server but did not. The result set may be incomplete. |
Table 50 defines values for the parsingResults statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 183.
Table 50 – QueryFirst Operation Level Result Codes
|
Symbolic Id |
Description |
|
Bad_NodeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_NodeIdUnknown |
See Table 183 for the description of this result code. |
|
Bad_NotTypeDefinition |
The provided NodeId was not a type definition NodeId. |
|
Bad_AttributeIdInvalid |
See Table 183 for the description of this result code. |
|
Bad_IndexRangeInvalid |
See Table 183 for the description of this result code. |