Function Name: Create Search Filter

Definition

Defines a set of rules that can be used to filter objects from a SEDRIS transmittal so that only objects that pass the rules will be returned to the user. This function only defines a set of rules; to use a set of rules after they have been defined, pass the set of rules into an iterator when creating the iterator. By doing so, the iterator will be bound to use that set of rules (that search filter) to filter all objects that will be returned by that iterator.

Search filters can be freed at any time; a search filter does NOT need to stay in existence until the iterator(s) that depend on that filter are freed. (An iterator retains a copy of any search filter used to initialize that iterator).

A static search (a search whose conditions are known at compile time) can easily be specified by taking advantage of the above search macros (see the examples, given in the comments preceding the search macros above).

A dynamically created search, on the other hand, requires the user to create a rules array and fill in the array with a well-formed postfix notation expression, ending with an SE_SEARCH_RULES entry with a rule_type value of SE_P_END.

Returns

SE_NULL_REQUIRED_PARAMETER - and *search_filter_out_ptr is left unaltered, if either search_filter_out_ptr or rules was NULL.

SE_INVALID_OR_NULL_TRANSMITTAL - and *search_filter_out_ptr will be set to NULL, if transmittal is not a handle to a valid, active (i.e., not previously closed) transmittal. In this case, *search_filter_out_ptr will be set to NULL.

SE_OUT_OF_MEMORY - *search_filter_out_ptr is set to NULL, if the API could not allocate memory for the new search filter.

SE_FAILURE - *search_filter_out_ptr is set to NULL, if

1. an illegal expression was specified by the rules parameter (for example, if an AND expression within the array only had one parameter), or
2. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

transmittal

 Used to determine the API implementation for which the search filter
 identifies the API implementation
    to use when creating this search filter.  If the specified API can't
    create the search filter, then the API will return a status code
    indicating why it could not be created.

rules

 a postfix array of SE_SEARCH_RULES defining a set of search
    rules to be applied as a filter for one or more iterators. This must
    be a 'properly formed' set of rules (each AND expression must have 2
    parameters, each OR expression must have 2 parameters, each NOT
    expression must have 1 parameter, the last entry in the array must be
    a rule with a value of SE_P_END, ...).  The end of the array is
    indicated by the SE_P_END entry.  Any entries after an SE_P_END entry
    will be ignored.

search_filter_out_ptr

 pointer to the newly created search filter.