This Serviceis used to issue a Queryrequest to the Server. The complexity of the Querycan range from very simple to highly sophisticated. The Querycan simply request data from instances of a TypeDefinitionNodeor TypeDefinitionNodesubject to restrictions specified by the filter. On the other hand, the Querycan request data from instances of related Nodetypes by specifying a RelativePathfrom 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 RelatedTooperators 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 ContentFiltersee 7.7, also see Clause B.1for simple examples and Clause B.2for more complex examples of content filter and queries.

The Clientprovides an array of NodeTypeDescriptionwhich specify the NodeIdof a TypeDefinitionNodeand selects what Attributesare to be returned in the response. A Clientcan also provide a set of RelativePathsthrough the type system starting from an originating TypeDefinitionNode. Using these paths, the Clientselects a set of Attributesfrom Nodesthat are related to instances of the originating TypeDefinitionNode. Additionally, the Clientcan request the Serverreturn instances of subtypes ofTypeDefinitionNodes. If a selected Attributedoes not exist in a TypeDefinitionNodebut does exist in a subtype, it is assumed to have a null value in the TypeDefinitionNodein question. Therefore, this does not constitute an error condition and a null value is returned for the Attribute.

The Clientcan use the filter parameter to limit the result set by restricting Attributesand Propertiesto certain values. Another way the Clientcan use a filter to limit the result set is by specifying how instances should be related, using RelatedTooperators. In this case, if an instance at the top of the RelatedTopath cannot be followed to the bottom of the path via specified hops, no QueryDataSetsare returned for the starting instance or any of the intermediate instances.

When querying for related instances in the RelativePath, the Clientcan optionally ask for References. A Referenceis requested via a RelativePaththat only includes a ReferenceType. If all Referencesare desired than the root ReferenceTypeis listed. These Referencesare 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 Clientis 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 47defines the request parameters and Table 48the response parameters for the QueryFirst Service.

Table 47– QueryFirst Request Parameters

Name

Type

Description

Request

requestHeader

RequestHeader

Common request parameters (see 7.33for RequestHeaderdefinition).

View

ViewDescription

Specifies a Viewand temporal context to a Server (see 7.45for ViewDescriptiondefinition).

nodeTypes []

NodeTypeDescription

This is the Nodetype description. This structure is defined in-line with the following indented items.

typeDefinitionNode

ExpandedNodeId

NodeIdof the originating TypeDefinitionNodeof the instances for which data is to be returned.

includeSubTypes

Boolean

A flag that indicates whether the Servershould include instances of subtypes of the TypeDefinitionNode in the list of instances of the Nodetype.

dataToReturn []

QueryDataDescription

Specifies an Attributeor Referencefrom 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 Nodeis an instance Nodeof the type defined by the type definition Node. The instance Nodesare 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 ReferenceDescriptionof the Referencewould be returned as its value.

The targetName field of the relativePath may contain a type NodeId. This is done by setting the namespaceIndexof the targetNameto zero and the namepart 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 AttributeId. The IntegerId is defined in 7.19. The IntegerId for Attributes are defined in OPC 10000-6. If the RelativePathended in a Referencethen 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 NumericRangetype is defined in 7.27.

This parameter is null or empty if the specified Attributeis not an array or a structure. However, if the specified Attributeis 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 Nodesshall be limited to the Nodesmatching the criteria defined by the filter. ContentFilter is discussed in 7.7. If an empty filter is provided then the entire AddressSpaceshall be examined and all Nodesthat contain a matching requested Attributeor Referenceare returned.

maxDataSetsToReturn

Counter

The number of QueryDataSetsthat the Client wants the Serverto return in the response and on each subsequent continuation call response. The Serveris allowed to further limit the response, but shall not exceed this limit.

A value of 0 indicates that the Clientis imposing no limitation.

maxReferencesToReturn

Counter

The number of Referencesthat the Clientwants the Serverto return in the response for each QueryDataSetand on each subsequent continuation call response. The Serveris allowed to further limit the response, but shall not exceed this limit.

A value of 0 indicates that the Clientis imposing no limitation.

For example a result where 4 Nodesare being returned, but each has 100 References, if this limit were set to 50 then only the first 50 Referencesfor each Nodewould 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.34for ResponseHeaderdefinition).

queryDataSets []

QueryDataSet

The array of QueryDataSets. This array is empty if no Nodesor Referencesmet the nodeTypescriteria. In this case the continuationPoint parameter shall be empty.

The QueryDataSettype is defined in 7.28.

continuationPoint

ContinuationPoint

Server-defined opaque value that identifies the continuation point.

The continuation point is used only when the Queryresults are too large to be returned in a single response. “Too large” in this context means that the Serveris not able to return a larger response or that the number of QueryDataSetsto return exceeds the maximum number of QueryDataSetsto return that was specified by the Clientin 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 Clientshall call QueryNext to get the next set of QueryDataSetsor to free the resources for the continuation point in the Server.

A continuation point shall remain active until the Clientpasses the continuation point to QueryNextor the session is closed. If the maximum continuation points have been reached the oldest continuation point shall be reset.

The ContinuationPointtype 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.12for 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 ContentFilterResulttype is defined in 7.7.2.

If the Queryis invalid or cannot be processed, then QueryDataSetsare not returned and only a Serviceresult, filterResult, parsingResults and optional DiagnosticInfois returned. Table 49defines the Serviceresults specific to this Service. Common StatusCodesare defined in Table 182.

Table 49– QueryFirst Service Result Codes

Symbolic Id

Description

Bad_NothingToDo

See Table 182for the description of this result code.

Bad_TooManyOperations

See Table 182for the description of this result code.

Bad_ContentFilterInvalid

See Table 183for the description of this result code.

Bad_ViewIdUnknown

See Table 182for the description of this result code.

Bad_ViewTimestampInvalid

See Table 182for the description of this result code.

Bad_ViewParameterMismatchInvalid

See Table 182for the description of this result code.

Bad_ViewVersionInvalid

See Table 182for the description of this result code.

Bad_InvalidFilter

The provided filter is invalid, see the filterResultfor specific errors

Bad_NodelistError

The NodeTypes provided contain an error, see the parsingResultsfor specific errors

Bad_InvalidView

The provided ViewDescriptionis not a valid ViewDescription.

Good_ResultsMayBeIncomplete

The Servershould have followed a reference to a node in a remote Serverbut did not. The result set may be incomplete.

Table 50defines values for the parsingResults statusCodeparameter that are specific to this Service. Common StatusCodesare defined in Table 183.

Table 50– QueryFirst Operation Level Result Codes

Symbolic Id

Description

Bad_NodeIdInvalid

See Table 183for the description of this result code.

Bad_NodeIdUnknown

See Table 183for the description of this result code.

Bad_NotTypeDefinition

The provided NodeId was not a type definition NodeId.

Bad_AttributeIdInvalid

See Table 183for the description of this result code.

Bad_IndexRangeInvalid

See Table 183for the description of this result code.