Definition

Defines a set of rules that can be used by an iterator 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 search filter 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). Also, the same search filter can be used to initialize many iterators.

See SE_Search_Rule for further details on how to construct a valid set of rules.

Returns

SE_RET_CODE_SUCCESS	and the search filter is created.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS

and a handle for the newly created search filter is copied into *search_filter_out_ptr, if valid parameters were passed in and all operations succeeded.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_INACTIONABLE_FAILURE	and *search_filter_out_ptr is left unaltered, if either search_filter_out_ptr or rules was NULL, or encoding was required but was NULL.
SE_STAT_CODE_OUT_OF_MEMORY	*search_filter_out_ptr is set to NULL, if the API could not allocate memory for the new search filter.
SE_STAT_CODE_INACTIONABLE_FAILURE	*search_filter_out_ptr is set to NULL, if an illegal expression was specified by the rules parameter (for example, if an AND expression within the array only had one parameter), or the call fails for any other reason.

Parameters Notes

encoding

    identifies the API implementation encoding
    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.  If encoding
    is NULL, then the API implementation encoding to be used must be statically
    bound at compile time.

    See also SE_GetEncoding().

rules

 a postfix array 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_SEARCH_RUL_TYP_END, ...).  The end of the
    array is indicated by the SE_SEARCH_RUL_TYP_END entry.  Any entries
    after an SE_SEARCH_RUL_TYP_END entry will be ignored.

search_filter_out_ptr

 pointer to the newly created search filter.

Prev: SE_CreateObject. Next: SE_CreateSpatialSearchBoundary. Up:Index.

Last updated: July 16, 2004 Copyright © 2004 SEDRIS™