Set a filter

If you do not set a filter, all objects for the container type will be returned when the container is populated. You can set one or more filters on a container.

    To set a filter on the container to specify the objects you want to find

1. Use the SmsCreateFilter function to create a filter for use on the container.

   The SmsCreateFilter function takes three parameters:

   • The type of filter
   • A handle to the specified 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 job filter.
   HANDLE hFilter;
   stat = SmsCreateFilter( JOB_FILTER, // Type of filter.
                           hConnect,   // Handle to database
                                       // connection.
                           &hFilter    // Assign handle to new filter
                         );            // to hFilter.
   

2. Use the token functions to add tokens to the 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 job filter that
   // finds all Run Command On Workstation jobs.
   
   TOKEN Token;
   // Clear the Token structure.
   memset( &Token, 0, sizeof (TOKEN) );
   
   // Set the expression token to 
   // "JobType is equal to Install".
   
   // Set the attribute name to JobType.
   strcpy( Token.szName, "JobType");
   // Set the operator used to evaluate the expression.
   Token.dwOp = QOP_STR_EQ; // Use the equals operator.
   // Set the value to evaluate.
   strcpy( Token.szValue, "Install"); 
   
   // 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 
                                // containing the expression 
                                // token.
                       AT_END   // Add the token to the end of 
                                // the filter.
                     );
    

3. Use the SmsSetFilter function to apply the filter to the container.

   The SmsSetFilter function takes two parameters:

   • The handle to the container to which you want to apply the filter
   • The handle to the filter to assign to the container.

   // Apply the filter to the container.
   stat = SmsSetFilter ( hContainer,  // Handle to container.
                         hFilter      // Handle to filter.
                       );
    

4. If the filter will not be applied to any other containers, use the SmsCloseFilter function to close the filter and decrement the usage count of the filter. When the usage count is zero, the memory used by the filter is deallocated.