Create a persistent filter

Machine filters are the only type of persistent filters currently supported by the SMS API. The steps to create a persistent filter are the same as the steps for creating a transient machine filter, with addition of two steps to:

Set the scalars for the persistent filter.
Commit the machine filter to the filter container (that is, write the machine filter to the site database). After a machine filter is committed to a filter container, that filter becomes a persistent filter.

To create a persistent filter

Use the SmsCreateFilter function to create a machine filter.

The SmsCreateFilter function takes three parameters:

The type of filter.
A handle to the database connection.
A pointer to a handle that is assigned the handle to the new filter. You use the handle to manage the filter.

Example:

// Create a machine filter to stored as 
// a persistent filter, that is, a query.
HANDLE hNewFilter;
stat = SmsCreateFilter( MACHINE_FILTER, // Machine filter.
                        hConnect,   // Handle to database
                                    // connection.
                        &hNewFilter // Assign handle to new filter
                      );            // to hNewFilter.

Use the token functions to add tokens to the machine filter. Each token represents an expression used to identify the objects to find.

To add a token to a filter, use the SmsAddToken function.

The SmsAddToken function takes four parameters:

The handle to the filter
The operator control token, which specifies how the expression token is connected to the adjacent expression token or subclause
A pointer to the structure containing the expression token
The location where the token is to be inserted

Example:

// Add a token to the machine filter that
// finds all computers with a 486 processor.

TOKEN Token;
// Clear the Token structure.
memset( &Token, 0, sizeof (TOKEN) );

// Set the expression token to 
// "Attribute Processor Name from group MICROSOFT|PROCESSOR|1.0 
// contains 486 (ie, Processor Name is like %486%)".

// Set the architecture, groupclass, and attribute.
strcpy( Token.szArchitecture, "Personal Computer");
strcpy( Token.szGroupClass, "MICROSOFT|PROCESSOR|1.0");
strcpy( Token.szAttributeName, "Processor Name");
// Set the operator used to evaluate the expression.
Token.dwOp = QOP_STR_LIKE; // Use the 'is like' operator.
// Set the value to evaluate.
strcpy( Token.szValue, "%486%"); 

// Add the token to the filter.
stat = SmsAddToken( hFilter, // Specifies the handle to filter.
                    OP_AND,  // Use the AND control token to 
                             // connect the expression to 
                             // adjacent expressions.
                    &Token,  // Specifies the structure for
                              // the expression token.
                    AT_END   // Add the token to the end of 
                             // the filter.
                  );

Set the scalars for the persistent filter.
A persistent filter has four scalars:

Query Key

An eight-character identifier that the SMS system assigns to the query when it is first added to the site database. This scalar must be set by the SMS system. Your application cannot set this scalar.

Name

Corresponds to the Query Name in the Query Properties of the query in the SMS Administrator. This scalar must be set by your application when adding a persistent filter to the site database.

Comment

Corresponds to Comment in the Query Properties of the query in the SMS Administrator. This scalar is optional.

Architecture

Corresponds to Architecture in the Query Properties of the query in the SMS Administrator. This scalar must be set by your application when adding a persistent filter to the site database.

Name and Architecture must be set by your application before a persistent filter is added to the site database by using SmsCommitFilter.
Use the SmsSetScalar function to set the value of a scalar.
The SmsSetScalar function takes two parameters:
- The handle to the filter
- A pointer to a SCALAR structure that contains the scalar data to be set
Example:
```
// Set the Name of the persistent filter (query).
SCALAR sc;                  // Declare SCALAR struct to hold 
                            // scalar data.
char *szScalarName = "Name"; // Name of the scalar to set.
SCALARTYPE scType = SCALAR_STRING; // Data type of scalar.
char *pszScalarValue = "Find all 486s"; // Value to set.
// Assign the scalar data to the sc structure.
sc.pszName = szScalarName;
sc.scType  = scType;
sc.dwLen = sizeof(pszScalarValue)-1;
sc.pszValue = pszScalarValue;

// Use SmsSetScalar to use the sc struct to 
// set the scalar for the filter.
stat = SmsSetScalar( hFilter,   // Handle to filter containing 
                                 // the scalar to set.
                     &sc         // Pointer to SCALAR struct 
                                 // containing value to set.
                   );
```
Use the SmsCommitFilter function to write the new filter to the site database.
The SmsCommitFilter function takes two parameters:
- The handle to the filter to commit
- The handle to the filter container that contains the filter
Example:
```
// Write the machine filter to the site database.
stat = SmsCommitFilter( hFilter,     // Handle to filter.
                        hFContainer  // Handle to filter 
                                     // container.
                      );
```
Note that the new machine filter is not written to the site database until the application calls the SmsCommitFilter function for that filter.