Filters

Before your application populates a container with objects from the site database, one or more filters can be set on the container. Filters define the criteria used to select the objects to retrieve from the site database.

There are eight types of filters available. The types of filters that your application can set are dependent on the container. For example, filters of type ARCHITECTURE_FILTER, MACHINE_FILTER, GROUP_FILTER, and ATTRIBUTE_FILTER can be set on a machine container.

Your application can configure a filter by adding tokens to the filter. There are two types of tokens: expression tokens and control tokens.

An expression token defines how to search for objects that have a specified relationship to a specified value for a specified attribute. An expression token is made up of an attribute, a relational operator, and a comparison value. A relational operator (such as "is equal to" or "is like") defines how the specified value should be compared with the actual value stored for the specified attribute. Depending on the type of filter that contains the token, an expression token's TOKEN structure uses the szName, szArchitecture, szGroupClass, and szAttributeName members to defined the attribute. For example, job filters (and most other filters) use the szName member to specify the attribute, whereas machine filters use the szArchitecture, szGroupClass, and szAttributeName members.

A control token can be a logical operator or parentheses. A logical operator connects two expression tokens, two subclauses, or a combination of an expression and a subclause. A logical operator defines the relationship between two adjacent expressions or subclauses. Parentheses enable expressions to be grouped together.

Your application can add expression tokens to a filter, using the SmsAddToken function. When an expression token is added to a filter, a control token for a logical operator is also implicitly added at the same time.

The SmsManipulateTokens function can be used to group, ungroup, delete, or exclude the specified tokens within a filter.

After your application sets the tokens for a filter, it can apply the filter to a container by using the SmsSetFilter function. When the container is populated, the set of filters applied to the container determine the objects that are retrieved from the site database.

There are also two classes of filters:

Transient filters

Filters that are created by your application and that exist only for the lifetime of the process that created them.

Persistent filters

Filters within a filter container that have been added to the site database. Persistent filters can be loaded by other processes. A persistent filter also contains scalars that are used to label the filter within the site database. Currently, only filters of type MACHINE_FILTER can be added to the site database through a filter container. MACHINE_FILTER filters are added as queries in the site database. Your application can also retrieve queries stored in the site database by opening a filter container. When the filter container is opened, it is populated with the queries stored in the site database. These queries are represented as filters in the filter container. Currently, the SMS API does not support deletion of persistent filters from the site database.