Job Filters (JOB_FILTER)

A job filter specifies the jobs that are retrieved for a job container. If no job filter is set on a job container, all jobs in the site database are retrieved for the container. Job filters can only be applied to job containers.

Using the SmsAddToken function, your application can add tokens to a job filter. Each expression token represents an attribute. For job filters, the tokens can be connected by using an OP_OR or OP_AND control token.

The TOKEN structure that contains the expression token must have the following members:

szName

A string that specifies the name of the job property to be evaluated by the expression.

Currently, three properties can be evaluated: JobType, JobStatus, and JobID.

For example, JobType specifies that the type of job is being evaluated.

DwOp

A DWORD value that specifies the operator used to evaluate the expression.

For job filters, this operator can only be QOP_STR_EQ.

SzValue

A string that specifies the value to be evaluated for the property specified by szName.

For example, if JobType is set for szName, the string "Install" would specify a Run Command On Workstation job type. For a list of values for each property, see the table below.

For example, your application could create a job filter with a token that specifies a JobStatus of Active. Your application could set this filter as the only filter on a job container. When your application populates the container, it contains folders that represent all jobs that have an active status.

The following table shows the values (szValue) that the available properties (szName) can have:

Example

// Function to add a token to a job filter so that
// the filter retrieves only the folders for 
// Run Command On Workstation jobs (F_INSTALLJOB).

SMS_STATUS AddTokenToJobFilter(HANDLE hFilter) 
                         //  Handle to package filter.
{
SMS_STATUS stat;
TOKEN Token;
// Clear the Token structure.
memset( &Token, 0, sizeof (TOKEN) );

// Set the expression token to 
// szName = "JobType"
// dwOp = QOP_STR_EQ
// szValue = "Install"

// Set the job property.
strcpy( Token.szName, "JobType");
// Set the operator to string equals.
Token.dwOp = QOP_STR_EQ;
// Set the type of job.
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 
                             // add a token to the job filter.
                    &Token,  // Specifies the structure containing
                             // the expression token.
                    AT_END   // Adds the token to the end of 
                             // the filter.
                  );

if (stat == SMS_OK)    
    printf("The token was successfully added to the filter.\n");
else 
    printf("SmsAddToken error: %d\n", stat);

return stat;
}