The ContentFilter structure defines a collection of elements that define filtering criteria. Each element in the collection describes an operator and an array of operands to be used by the operator. The operators that can be used in a ContentFilter are described in Table 119. The filter is evaluated by evaluating the first entry in the element array starting with the first operand in the operand array. The operands of an element may contain References to sub-elements resulting in the evaluation continuing to the referenced elements in the element array. The evaluation shall not introduce loops. For example evaluation starting from element “A” shall never be able to return to element “A”. However there may be more than one path leading to another element “B”. If an element cannot be traced back to the starting element it is ignored. Extra operands for any operator shall result in an error. Annex B provides examples using the ContentFilter structure.

Table 115defines the ContentFilterstructure.

Table 115– ContentFilter Structure

Name

Type

Description

ContentFilter

structure

elements []

ContentFilterElement

List of operators and their operands that compose the filter criteria. The filter is evaluated by starting with the first entry in this array. This structure is defined in-line with the following indented items.

filterOperator

Enum

FilterOperator

Filter operator to be evaluated.

The FilterOperatorenumeration is defined in Table 119.

filterOperands []

Extensible Parameter

FilterOperand

Operands used by the selected operator. The number and use depend on the operators defined in Table 119. This array needs at least one entry.

This extensible parameter type is the FilterOperandparameter type specified in 7.4.4. It specifies the list of valid FilterOperandvalues.

The components of this data type are defined in Table 116.

Table 116– ContentFilterResult Structure

Name

Type

Description

ContentFilterResult

structure

A structure that contains any errors associated with the filter.

elementResults []

ContentFilter

ElementResult

A list of results for individual elements in the filter. The size and order of the list matches the size and order of the elements in the ContentFilterparameter. This structure is defined in-line with the following indented items.

statusCode

StatusCode

The status code for a single element.

operandStatusCodes []

StatusCode

A list of status codes for the operands in an element. The size and order of the list matches the size and order of the operands in the ContentFilterElement.This list is empty if no operand errors occurred.

operandDiagnosticInfos []

DiagnosticInfo

A list of diagnostic information for the operands in an element. The size and order of the list matches the size and order of the operands in the ContentFilterElement. 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 operands.

elementDiagnosticInfos []

DiagnosticInfo

A list of diagnostic information for individual elements in the filter. The size and order of the list matches the size and order of the elements in the filterrequest 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 elements.

Table 117defines values for the statusCodeparameter that are specific to this structure. Common StatusCodesare defined in Table 178.

Table 117– ContentFilterResult Result Codes

Symbolic Id

Description

Bad_FilterOperandCountMismatch

The number of operands provided for the filter operator was less than expected for the operand provided.

Bad_FilterOperatorInvalid

An unrecognized operator was provided in a filter.

Bad_FilterOperatorUnsupported

A valid operator was provided, but the Serverdoes not provide support for this filter operator.

Table 118defines values for the operandStatusCodesparameter that are specific to this structure. Common StatusCodesare defined in Table 178.

Table 118– ContentFilterResult Operand Result Codes

Symbolic Id

Description

Bad_FilterOperandInvalid

See Table 178for the description of this result code.

Bad_FilterElementInvalid

The referenced element is not a valid element in the content filter.

Bad_FilterLiteralInvalid

The referenced literal is not a valid BaseDataType.

Bad_AttributeIdInvalid

The attribute id is not a valid attribute id in the system.

Bad_IndexRangeInvalid

See Table 178for the description of this result code.

Bad_NodeIdInvalid

See Table 178for the description of this result code.

Bad_NodeIdUnknown

See Table 178for the description of this result code.

Bad_NotTypeDefinition

The provided NodeId was not a type definition NodeId.

Table 119defines the basic operators that can be used in a ContentFilter. See Table 120for a description of advanced operators. See 7.4.4for a definition of operands.

Table 119– Basic FilterOperator Definition

Operator

Number of Operands

Description

Equals_0

2

TRUE if operand[0] is equal to operand[1].

If the operands are of different types, the system shall perform any implicit conversion to a common type. This operator resolves to FALSE if no implicit conversion is available and the operands are of different types. This operator returns FALSE if the implicit conversion fails. See the discussion on data type precedence in Table 123for more information how to convert operands of different types.

IsNull_1

1

TRUE if operand[0] is a null value.

GreaterThan_2

2

TRUE if operand[0] is greater than operand[1].

The following restrictions apply to the operands:

[0]: Any operand that resolves to an ordered value.

[1]: Any operand that resolves to an ordered value.

The same conversion rules as defined for Equalsapply.

LessThan_3

2

TRUE if operand[0] is less than operand[1].

The same conversion rules and restrictions as defined for GreaterThanapply.

GreaterThanOrEqual_4

2

TRUE if operand[0] is greater than or equal to operand[1].

The same conversion rules and restrictions as defined for GreaterThanapply.

LessThanOrEqual_5

2

TRUE if operand[0] is less than or equal to operand[1].

The same conversion rules and restrictions as defined for GreaterThanapply.

Like_6

2

TRUE if operand[0] matches a pattern defined by operand[1]. See Table 121for the definition of the pattern syntax.

The following restrictions apply to the operands:

[0]: Any operand that resolves to a String.

[1]: Any operand that resolves to a String.

This operator resolves to FALSE if no operand can be resolved to a string.

Not_7

1

TRUE if operand[0] is FALSE.

The following restrictions apply to the operands:

[0]: Any operand that resolves to a Boolean.

If the operand cannot be resolved to a Boolean, the result is a NULL. See below for a discussion on the handling of NULL.

Between_8

3

TRUE if operand[0] is greater or equal to operand[1] and less than or equal to operand[2].

The following restrictions apply to the operands:

[0]: Any operand that resolves to an ordered value.

[1]: Any operand that resolves to an ordered value.

[2]: Any operand that resolves to an ordered value.

If the operands are of different types, the system shall perform any implicit conversion to match all operands to a common type. If no implicit conversion is available and the operands are of different types, the particular result is FALSE. See the discussion on data type precedence in Table 123for more information how to convert operands of different types.

InList_9

2..n

TRUE if operand[0] is equal to one or more of the remaining operands.

The Equals Operator is evaluated for operand[0] and each remaining operand in the list. If any Equals evaluation is TRUE, InList returns TRUE.

And_10

2

TRUE if operand[0] and operand[1] are TRUE.

The following restrictions apply to the operands:

[0]: Any operand that resolves to a Boolean.

[1]: Any operand that resolves to a Boolean.

If any operand cannot be resolved to a Boolean it is considered a NULL. See below for a discussion on the handling of NULL.

Or_11

2

TRUE if operand[0] or operand[1] are TRUE.

The following restrictions apply to the operands:

[0]: Any operand that resolves to a Boolean.

[1]: Any operand that resolves to a Boolean.

If any operand cannot be resolved to a Boolean it is considered a NULL. See below for a discussion on the handling of NULL.

Cast_12

2

Converts operand[0] to a value with a data type with a NodeId identified by operand[1].

The following restrictions apply to the operands:

[0]: Any operand.

[1]: Any operand that resolves to a NodeId or ExpandedNodeId where the Nodeis of the NodeClass DataType.

If there is any error in conversion or in any of the parameters then the Cast Operation evaluates to a NULL. See below for a discussion on the handling of NULL.

BitwiseAnd_16

2

The result is an integer which matches the size of the largest operand and contains a bitwise And operation of the two operands where both have been converted to the same size (largest of the two operands).

The following restrictions apply to the operands:

[0]: Any operand that resolves to an integer.

[1]: Any operand that resolves to an integer.

If any operand cannot be resolved to an integer it is considered a NULL. See below for a discussion on the handling of NULL.

BitwiseOr_17

2

The result is an integer which matches the size of the largest operand and contains a bitwise Or operation of the two operands where both have been converted to the same size (largest of the two operands).

The following restrictions apply to the operands:

[0]: Any operand that resolves to an integer.

[1]: Any operand that resolves to an integer.

If any operand cannot be resolved to an integer it is considered a NULL. See below for a discussion on the handling of NULL.

Many operands have restrictions on their type. This requires the operand to be evaluated to determine what the type is. In some cases the type is specified in the operand (i.e. a LiteralOperand). In other cases the type requires that the value of an attribute be read. An ElementOperandevaluates to a Boolean value unless the operator is a Cast or a nested RelatedTooperator.

Table 120defines complex operators that require a target node (i.e. row) to evaluate. These operators shall be re-evaluated for each possible target node in the result set.

Table 120– Complex FilterOperator Definition

Operator

Number of Operands

Description

InView_13

1

TRUE if the target Nodeis contained in the Viewdefined by operand[0].

The following restrictions apply to the operands:

[0]: Any operand that resolves to a NodeIdthat identifies a View Node.

If operand[0] does not resolve to a NodeIdthat identifies a View Node, this operation shall always be False.

OfType_14

1

TRUE if the target Nodeis of type operand[0] or of a subtype of operand[0].

The following restrictions apply to the operands:

[0]: Any operand that resolves to a NodeIdthat identifies an ObjectType or VariableType Node.

If operand[0] does not resolve to a NodeIdthat identifies an ObjectType or VariableType Node, this operation shall always be False.

RelatedTo_15

6

TRUE if the target Nodeis of type operand[0] and is related to a NodeIdof the type defined in operand[1] by the Referencetype defined in operand[2].

operand[0] or operand[1] can also point to an element Referencewhere the referred to element is another RelatedTo operator. This allows chaining of relationships (e.g. A is related to B is related to C), where the relationship is defined by the ReferenceTypedefined in operand[2]. In this case, the referred to element returns a list of NodeIdsinstead of TRUE or FALSE. In this case if any errors occur or any of the operands cannot be resolved to an appropriate value, the result of the chained relationship is an empty list of nodes.

Operand[3] defines the number of hops for which the relationship should be followed. If operand[3] is 1, then objects shall be directly related. If a hop is greater than 1, then a NodeIdof the type described in operand[1] is checked for at the depth specified by the hop. In this case, the type of the intermediate Nodeis undefined, and only the Referencetype used to reach the end Nodeis defined. If the requested number of hops cannot be followed, then the result is FALSE, i.e., an empty Nodelist. If operand[3] is 0, the relationship is followed to its logical end in a forward direction and each Nodeis checked to be of the type specified in operand[1]. If any Nodesatisfies this criterion, then the result is TRUE, i.e., the NodeIdis included in the sub-list.

Operand [4] defines if operands [0] and [1] should include support for subtypes of the types defined by these operands. A TRUE indicates support for subtypes

operand [5] defines if operand [2] should include support for subtypes of the reference type. A TRUE indicates support for subtypes.

The following restrictions apply to the operands:

[0]: Any operand that resolves to a NodeIdor ExpandedNodeIdthat identifies an ObjectType or VariableType Node or a reference to another element which is a RelatedTo operator.

[1]: Any operand that resolves to a NodeIdor ExpandedNodeIdthat identifies an ObjectType or VariableType Node or a reference to another element which is a RelatedTo operator.

[2]: Any operand that resolves to a NodeIdthat identifies a ReferenceType Node.

[3]: Any operand that resolves to a value implicitly convertible to UInt32.

[4]: Any operand that resolves to a value implicitly convertible to a Boolean; if this operand does not resolve to a Boolean, then a value of FALSE is used.

[5]: Any operand that resolves to a value implicitly convertible to a Boolean; if this operand does not resolve to a Boolean, then a value of FALSE is used.

If none of the operands [0],[1],[2],[3] resolves to an appropriate value then the result of this operation shall always be False (or an Empty set in the case of a nested RelatedTooperand).

See examples for RelatedTo in B.2.

The RelatedTo operator can be used to identify if a given type, set as operand[1], is a subtype of another type set as operand[0] by setting operand[2] to the HasSubtype ReferenceTypeand operand[3] to 0.

The Likeoperator can be used to perform wildcard comparisons. Several special characters can be included in the second operand of the Likeoperator. The valid characters are defined in Table 121. The wildcard characters can be combined in a single string (i.e. ‘Th[ia][ts]%’ would match ‘That is fine’, ‘This is fine’, ‘That as one’, ‘This it is’, ‘Then at any’, etc.). The Likeoperator is case sensitive.

Table 121– Wildcard characters

Special Character

Description

%

Match any string of zero or more characters (i.e. ‘main%’ would match any string that starts with ‘main’, ‘%en%’ would match any string that contains the letters ‘en’ such as ‘entail’, ‘green’ and ‘content’.) If a ‘%’ sign is intend in a string the list operand can be used (i.e. 5[%] would match ‘5%’).

_

Match any single character (i.e. ‘_ould’ would match ‘would’, ‘could’). If the ‘_’ is intended in a string then the list operand can be used (i.e. 5[_] would match ‘5_’).

\

Escape character allows literal interpretation

(i.e. \\ is \, \% is %, \_ is _)

[]

Match any single character in a list

(i.e. ‘abc[13-68] would match ‘abc1’,’abc3’,’abc4’,’abc5’,’abc6’, and ‘abc8’.

‘xyz[c-f]’ would match ‘xyzc’, ‘xyzd’, ‘xyze’, ‘xyzf’).

[^]

Not Matching any single character in a list.

The ^ shall be the first character inside on the [].

(i.e. ‘ABC[^13-5]’ would NOT match ‘ABC1’, ‘ABC3’, ‘ABC4’, and ‘ABC5’. xyz[^dgh] would NOT match ‘xyzd’, ‘xyzg’, ‘xyzh’. )

Table 122defines the conversion rules for the operand values. The types are automatically converted if an implicit conversion exists (I). If an explicit conversion exists (E) then type can be converted with the cast operator. If no conversion exists (X) the then types cannot be converted, however, some servers may support application specific explicit conversions. The types used in the table are defined in OPC 10000-3. A data type that is not in the table does not have any defined conversions.

Table 122– Conversion Rules

Target Type (To)

Source Type (From)

Boolean

Byte

ByteString

DateTime

Double

ExpandedNodeId

Float

Guid

Int16

Int32

Int64

NodeId

SByte

StatusCode

String

LocalizedText

QualifiedName

UInt16

UInt32

UInt64

XmlElement

Boolean

-

I

X

X

I

X

I

X

I

I

I

X

I

X

E

X

X

I

I

I

X

Byte

E

-

X

X

I

X

I

X

I

I

I

X

I

X

E

X

X

I

I

I

X

ByteString

X

X

-

X

X

X

X

E

X

X

X

X

X

X

X

X

X

X

X

X

X

DateTime

X

X

X

-

X

X

X

X

X

X

X

X

X

X

E

X

X

X

X

X

X

Double

E

E

X

X

-

X

E

X

E

E

E

X

E

X

E

X

X

E

E

E

X

ExpandedNodeId

X

X

X

X

X

-

X

X

X

X

X

E

X

X

I

X

X

X

X

X

X

Float

E

E

X

X

I

X

-

X

E

E

E

X

E

X

E

X

X

E

E

E

X

Guid

X

X

E

X

X

X

X

-

X

X

X

X

X

X

E

X

X

X

X

X

X

Int16

E

E

X

X

I

X

I

X

-

I

I

X

E

X

E

X

X

E

I

I

X

Int32

E

E

X

X

I

X

I

X

E

-

I

X

E

E

E

X

X

E

E

I

X

Int64

E

E

X

X

I

X

I

X

E

E

-

X

E

E

E

X

X

E

E

E

X

NodeId

X

X

X

X

X

I

X

X

X

X

X

-

X

X

I

X

X

X

X

X

X

SByte

E

E

X

X

I

X

I

X

I

I

I

X

-

X

E

X

X

I

I

I

X

StatusCode

X

X

X

X

X

X

X

X

X

I

I

X

X

-

X

X

X

E

I

I

X

String

I

I

X

E

I

E

I

I

I

I

I

E

I

X

-

E

E

I

I

I

X

LocalizedText

X

X

X

X

X

X

X

X

X

X

X

X

X

X

I

-

X

X

X

X

X

QualifiedName

X

X

X

X

X

X

X

X

X

X

X

X

X

X

I

I

-

X

X

X

X

UInt16

E

E

X

X

I

X

I

X

I

I

I

X

E

I

E

X

X

-

I

I

X

UInt32

E

E

X

X

I

X

I

X

E

I

I

X

E

E

E

X

X

E

-

I

X

UInt64

E

E

X

X

I

X

I

X

E

E

I

X

E

E

E

X

X

E

E

-

X

XmlElement

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

X

-

Arrays of a source type can be converted to arrays of the target type by converting each element. A conversion error for any element causes the entire conversion to fail.

Arrays of length 1 can be implicitly converted to a scalar value of the same type.

Guid, NodeIdand ExpandedNodeIdare converted to and from Stringusing the syntax defined in OPC 10000-6.

Floating point values are rounded by adding 0.5 and truncating when they are converted to integer values.

Converting a negative value to an unsigned type causes a conversion error. If the conversion fails the result is a null value.

Converting a value that is outside the range of the target type causes a conversion error. If the conversion fails the result is a null value.

ByteStringis converted to Stringby formatting the bytes as a sequence of hexadecimal digits.

LocalizedTextvalues are converted to Stringsby dropping the Locale. Stringsare converted to LocalizedTextvalues by setting the Locale to “”.

QualifiedNamevalues are converted to Stringsby dropping the NamespaceIndex. Stringsare converted to QualifiedNamevalues by setting the NamespaceIndexto 0.

A StatusCodecan be converted to and from a UInt32and Int32by copying the bits. Only the top 16-bits if the StatusCodeare copied when it is converted to and from a UInt16or Int16value.

Booleanvalues are converted to ‘1’ when true and ‘0’ when false. Non zero numeric values are converted to true Booleanvalues. Numeric values of 0 are converted to false Booleanvalues. Stringvalues containing “true”, “false”, “1” or “0” can be converted to Booleanvalues. Other string values cause a conversion error. In this case Stringsare case-insensitive.

It is sometimes possible to use implicit casts when operands with different data types are used in an operation. In this situation the precedence rules defined in Table 123are used to determine which implicit conversion to use. The first data type in the list (top down) has the most precedence. If a data type is not in this table then it cannot be converted implicitly while evaluating an operation.

For example, assume that A = 1,1 (Float) and B = 1 (Int32) and that these values are used with an Equalsoperator. This operation would be evaluated by casting the Int32value to a Floatsince the Floatdata type has more precedence.

Table 123– Data Precedence Rules

Rank

Data Type

1

Double

2

Float

3

Int64

4

UInt64

5

Int32

6

UInt32

7

StatusCode

8

Int16

9

UInt16

10

SByte

11

Byte

12

Boolean

13

Guid

14

String

15

ExpandedNodeId

16

NodeId

17

LocalizedText

18

QualifiedName

Operands may contain null values (i.e. values which do not exist). When this happens, the element always evaluates to NULL (unless the IsNull_1 operator has been specified). Table 124defines how to combine elements that evaluate to NULL with other elements in a logical AND operation.

Table 124– Logical AND Truth Table

TRUE

FALSE

NULL

TRUE

TRUE

FALSE

NULL

FALSE

FALSE

FALSE

FALSE

NULL

NULL

FALSE

NULL

Table 125defines how to combine elements that evaluate to NULL with other elements in a logical OR operation.

Table 125– Logical OR Truth Table

TRUE

FALSE

NULL

TRUE

TRUE

TRUE

TRUE

FALSE

TRUE

FALSE

NULL

NULL

TRUE

NULL

NULL

The NOT operator always evaluates to NULL if applied to a NULL operand.

A ContentFilterwhich evaluates to NULL after all elements are evaluated is evaluated as false.

The ContentFilterstructure specified in 7.4defines a collection of elements that makes up filter criteria and contains different types of FilterOperands. The FilterOperand parameter is an extensible parameter. This parameter is defined in Table 126. The ExtensibleParametertype is defined in 7.12.

Table 126– FilterOperand parameter TypeIds

Symbolic Id

Description

Element

Specifies an index into the array of elements. This type is used to build a logic tree of sub-elements by linking the operand of one element to a sub-element.

Literal

Specifies a literal value.

Attribute

Specifies any Attributeof an Object orVariable Nodeusing a Nodein the type system and relative path constructed from ReferenceTypesand BrowseNames.

SimpleAttribute

Specifies any Attributeof an Object orVariable Nodeusing a TypeDefinitionand a relative path constructed from BrowseNames.

The ElementOperandprovides the linking to sub-elements within a ContentFilter. The link is in the form of an integer that is used to index into the array of elements contained in the ContentFilter. An index is considered valid if its value is greater than the element index it is part of and it does not Referencea non-existent element. Clientsshall construct filters in this way to avoid circular and invalid References. Serversshould protect against invalid indexes by verifying the index prior to using it.

Table 127defines the ElementOperandtype.

Table 127– ElementOperand

Name

Type

Description

ElementOperand

structure

ElementOperand value.

index

UInt32

Index into the element array.

Table 128defines the LiteralOperandtype.

Table 128– LiteralOperand

Name

Type

Description

LiteralOperand

structure

LiteralOperand value.

value

BaseDataType

A literal value.

Table 129defines the AttributeOperandtype.

Table 129– AttributeOperand

Name

Type

Description

AttributeOperand

structure

Attribute of a Nodein the AddressSpace.

nodeId

NodeId

NodeIdof a Nodefrom the type system.

alias

String

An optional parameter used to identify or refer to an alias. An alias is a symbolic name that can be used to alias this operand and use it in other locations in the filter structure.

browsePath

RelativePath

Browse path relative to the Nodeidentified by the nodeIdparameter. See 7.26for the definition of RelativePath.

attributeId

IntegerId

Id of the Attribute. This shall be a valid AttributeId. The IntegerId is defined in 7.14. The IntegerIds for the Attributes are defined in OPC 10000-6.

indexRange

NumericRange

This parameter is used to identify a single element of an array or a single range of indexes for an array. The first element is identified by index 0 (zero).

The NumericRangetype is defined in 7.22.

This parameter is not used if the specified Attributeis not an array. However, if the specified Attributeis an array and this parameter is not used, then all elements are to be included in the range. The parameter is null if not used.

The SimpleAttributeOperandis a simplified form of the AttributeOperandand all of the rules that apply to the AttributeOperandalso apply to the SimpleAttributeOperand. The examples provided in B.1only use AttributeOperand, however, the AttributeOperandcan be replaced by a SimpleAttributeOperandwhenever all ReferenceTypesin the RelativePathare subtypes of HierarchicalReferencesand the targets are Objector Variable Nodes and an Alias is not required.

Table 130defines the SimpleAttributeOperandtype.

Table 130– SimpleAttributeOperand

Name

Type

Description

SimpleAttributeOperand

structure

Attribute of a Nodein the AddressSpace.

typeDefinitionId

NodeId

NodeIdof a TypeDefinitionNode.

This parameter restricts the operand to instances of the TypeDefinitionNodeor one of its subtypes.

browsePath []

QualifiedName

A relative path to a Node.

This parameter specifies a relative path using a list of BrowseNamesinstead of the RelativePathstructure used in the AttributeOperand. The list of BrowseNamesis equivalent to a RelativePaththat specifies forward references which are subtypes of the HierarchicalReferences ReferenceType.

All Nodesfollowed by the browsePathshall be of the NodeClass Objector Variable.

If this list is empty the Nodeis the instance of the TypeDefinition.

attributeId

IntegerId

Id of the Attribute. The IntegerId is defined in 7.14.

The Value Attributeshall be supported by all Servers. The support of other Attributesdepends on requirements set in Profiles or other parts of this specification.

indexRange

NumericRange

This parameter is used to identify a single element of an array, or a single range of indexes for an array. The first element is identified by index 0 (zero).

This parameter is ignored if the selected Node is not a Variable or the Value of a Variable is not an array.

The parameter is null if not specified.

All values in the array are used if this parameter is not specified.

The NumericRangetype is defined in 7.22.