Table 1.  Examples of filter expressions

Simple and Compound Expressions

Filter expressions may further be categorized as being simple or compound.

A simple expression consists of a single unary or binary logical operation.  A unary logical operation has a single operand and, optionally, a logical unary operator.  A binary operation has two operands and a logical binary operator.  Whether unary or binary, the logical expression must still evaluate to true or false.

Table 2 contains some examples of simple filter expressions.

Table 2.  Examples of simple filter expressions

A compound expression consists of two or more simple expressions joined together using the logical operators and (&&) or or (||).  Simple expressions may be multiply nested to form complex compound expressions, using parentheses (()) to group operations by precedence.  Each component expression unit within a compound expression is referred to as a subexpression.  Subexpressions may be simple unary or binary expressions, or might be nested compound expressions.

Table 3 contains some examples of compound filter expressions.

Table 3.  Examples of compound filter expressions

Finally, a filter expression may have arithmetic or bitwise operations embedded within.  For instance,

CAP:FL % 100 = 0

could be used to determine which DatagLANce or Sniffer records have lengths that are multiples of 100.  In such cases, the arithmetic or bitwise operation generally is evaluated before the logical test is applied (see the Operators section for specifics on operator precedence).

It should be noted that although arithmetic or bitwise subexpressions are permissible, the overall filter expression must be constructed in such a way as to ensure that it will be evaluated to produce a boolean result:  true or false.  Expressions which do not meet this requirement are not valid.  Thus, when creating compound expressions containing arithmetic subexpressions, the use of parentheses and an understanding of operator precedence is critical.

Protocol Field ID Operands

A protocol field ID is an operand in an expression which uniquely identifies a specific field within a specific protocol.  Protocol IDs follow a well defined syntax.

When a filter is applied to a trace record, the data which is associated with a protocol field ID in the filter expression, if any, is extracted from the appropriate offset in the record.  The actual data for that protocol field ID is substituted into the expression and the expression is evaluated.

Operators

Operators within filter expressions may be logical or arithmetic, binary or unary, as long as the overall expression is constructed in such a way as to evaluate to true or false.  In order to construct valid expressions, it is important to understand the relative precedence of the available operators, and to use parentheses to group subexpressions properly.

The set of operators which may be used within filter expressions is listed in Table 4.  Operators in this table are listed in order of their precedence, from those evaluated first to those evaluated last.  Operators which have the same precedence are grouped together.  When evaluating operations whose operators have the same precedence, the program will evaluate the operations in the order in which they appear, from left to right.  Parentheses (()) may be used to group operations which must be evaluated in a different order.

Table 4.  Operators by Precedence

Expression Evaluation

Expressions are evaluated in order of operator precedence (see Table 4 - Operators by Precedence), from left to right, unless parentheses are used to group subexpressions to change their precedence.

Variable Resolution

Whether or not a variable can be resolved to data at evaluation time affects the result of the expression being evaluated. Expressions requiring variable substitution are handled in the following manner.  The expression

PROT:FIELD = 10

is represented internally to the expression engine as

PROT:FIELD != null and PROT:FIELD = 10

Thus, if PROT:FIELD cannot be resolved to data if, for instance, the protocol PROT is not present in the current record, or FIELD is an optional field, which is not present in the current record, then this expression would evaluate to false.

This treatment of the above expression seems fairly intuitive.  However, it should be noted that the expression

PROT:FIELD != 10

also will evaluate to false if the field PROT:FIELD cannot be resolved at evaluation time.  This may not be as immediately intuitive as the first example, but this behavior is consistent.  This is because the latter expression is represented internally to the expression engine as

PROT:FIELD != null and PROT:FIELD != 10

Finally it should be noted that the expressions

PROT:FIELD != 10

and

!(PROT:FIELD = 10)

are not equivalent.  The former will return false if PROT:FIELD cannot be resolved (as discussed above), while the latter will return true in the same circumstance.  This is because the latter expression is represented internally to the expression engine as

!(PROT:FIELD != null and PROT:FIELD = 10)

Distributing the negation operator (!) across both subexpressions inside the parentheses yields

PROT:FIELD = null or PROT:FIELD != 10

Thus, the left side of the expression evaluates to true if PROT:FIELD cannot be resolved.  In this event, the right side of the expression is ignored and the overall expression returns true.

It is important to keep in mind the subtleties of how unresolved variables are handled when designing your filter expressions.

User Functions

A number of special purpose user functions exist to simplify the encoding of operations which would be cumbersome or impossible to represent in a conventional filter expression.  User functions may be embedded in a compound filter expression, or may comprise the entire expression.  A user function is evaluated as an atomic unit which returns true or false.

The syntax of a user function varies from function to function, but is always of the general form

@function_name(arg_1[, arg_2...arg_N])

where:

the @ symbol

Designates the following text as a user function.  Every user function must begin with this symbol.

function_name

The name of the user function.  For example, protocol, pattern, in, etc.

arg_X

An argument required by the specific user function being used.  This may be a variable, such as a protocol field ID, or a numeric or string constant.  Each user function takes at least one argument.  Others require additional arguments;  some user functions accept a variable number of arguments.

The user functions listed in Table 5 are available for use in filter expressions.  A detailed description of each is linked from the individual table entries.

Table 5.  User Functions

---