Search Filter

The fn_attr_ext_search() operation allows the search for named objects whose attributes satisfy a given filter expression. The filter is expressed in terms of logical expressions involving attribute identifiers and their values of named objects examined during the search. The filter is created from an expression string and a list of arguments that replace substitution tokens within the expression string.

BNF of Filter Expression

<FilterExpr> ::=  [ <Expr> ]
 <Expr> ::= <Expr> "or" <Expr>
    | <Expr> "and" <Expr>
    | "not" <Expr>
    | "(" <Expr> ")"
    | <Attribute> [ <Rel_Op> <Value> ]
    | <Ext>
 <Rel_Op> ::= "==" | "!=" | "<" | "<=" | ">" | ">=" | "~="
 <Attribute> ::= "%a"
 <Value> ::= <Integer>
    | "%v"
    | <Wildcarded_string>
 <Wildcarded_string> ::= "*"
    | <String>
    | {<String> "*"}+ [<String>]
    | {"*" <String>}+ ["*"]
 <String> ::= "`" { <Char> } * "`"
    | "%s"
 <Char> ::= <PCS> // See BNF in Section 4.1.2 for PCS definition
    | Characters in the repertoire of a string representation
 <Identifier> ::= "%i"
 <Ext> ::= <Ext_Op> "(" [Arg_List] ")"
 <Ext_Op> ::= <String> | <Identifier>
 <Arg_List> ::= <Arg> | <Arg> "," <Arg_List>
 <Arg> ::= <Value> | <Attribute> | <Identifier>

Specification of Filter Expression

The arguments to fn_search_filter_create() are a return status, an expression string, and a list of arguments. The string contains the filter expression with substitution tokens for the attributes, attribute values, strings and identifiers that are part of the expression. The remaining list of arguments contains the attributes and values in the order of appearance of their corresponding substitution tokens in the expression. The arguments are of types FN_attribute_t*, FN_attrvalue_t*, FN_string_t* or FN_identifier_t*.

Except when attributes appear as arguments in specially defined extended operations, any attribute values in an FN_attribute_t type of argument are ignored; only the attribute identifier and attribute syntax are relevant. The argument type expected by each substitution token is listed in Table 2-6.

Table 2-6 Substitute Tokens in Search Filter Expressions

Substitute Tokens in Search Filter Expressions

Precedence

The following precedence relations hold in the absence of parentheses, in the order of lowest to highest:

• or

• and

• not

• relational operators

These Boolean and relational operators are left associative.

Relational Operators

Table 2-7 contains descriptions of the relational operators. Comparisons and ordering are specific to the syntax or rules of the supplied attribute.

Locale (code set, language or territory) mismatches that occur during string comparisons and ordering operations are resolved in an implementation-dependent way. Relational operations that have ordering semantics may be used for strings of locales in which ordering is meaningful, but is not of general use in internationalized environments.

An attribute that occurs in the absence of any relational operator tests for the presence of the attribute.

Table 2-7 Relational Operators in Search Filter Expressions

Wildcarded Strings

A wildcarded string consists of a sequence of alternating wildcard specifiers and strings. The sequence can start with either a wildcard specifier or a string, and end with either a wildcard specifier or a string.

The wildcard specifier is denoted by the asterisk character (*) and means 0 or more occurrences of any character.

Wildcarded strings can be used to specify substring matches. Table 2-8contains examples of wildcarded strings and their meaning.

Table 2-8 Examples of Wildcarded Strings

Extended Operations

In addition to the relational operators, extended operators can be specified. All extended operators return either TRUE or FALSE. A filter expression can contain both relational and extended operations.

Extended operators are specified using an identifier (FN_identifier_t) or a string. If the operator is specified using a string, the string is used to construct an identifier of format FN_ID_STRING. Identifiers of extended operators and signatures of the corresponding extended operations, as well as their suggested semantics, are registered with X/Open.

The extended operations shown in Table 2-9are currently defined:

Table 2-9 Extended Operations

The operation returns TRUE if any of the address types in the reference of the object is equal to the supplied identifier. Support and exact semantics of extended operations are context-specific. If a context does not support an extended operation, or if the filter expression supplies the extended operation with either an incorrect number or type of arguments, the error FN_E_SEARCH_INVALID_OP is returned. FN_E_OPERATION_NOT_SUPPORTED is returned when fn_attr_ext_search() is not supported.

Table 2-10 contains examples of filter expressions that contain extended operations.

Table 2-10 Extended Operations in Search Filter Expressions