Inventory Rules Folder Tokens

In addition to the Inventory this package scalar, an inventory rules folder contains one or more tokens that represent the rule for collecting inventory on the package.

The inventory rules folder uses expression tokens and control tokens in the same way that filters do—except that each expression token contains a string that specifies attributes that identify the file, and the NOT operator is not supported. In addition, expression tokens for an inventory rules folder use only the szTokenString member of the TOKEN structure. In all other respects, the tokens for an inventory rules folder have the same behavior as tokens in a filter—expression tokens are connected by AND or OR operators, expression tokens can be grouped and ungrouped, and they can be deleted.

Note that the inventory rules folder must contain at least one expression token. An inventory rules folder that does not contain one or more expression tokens cannot be committed to the site database.

Each expression token contains a string that begins with the file keyword, the file name, and the file's attributes (note that the file attributes are optional):

file "filename" [fileattributes]

where

filename

Is a string that specifies the name of the file. This can be a file name with eight characters plus a three-character extension, or a long file name. The filename must be enclosed within quotation marks.

When your application reads a token from an existing inventory rules folder in the site database, filename specifies only the name of the file—not an explicit path.

When your application adds a token, an explicit path can be specified (such as C:\GRAPE\FRUIT.EXE). By using an explicit path, the SMS API engine can retrieve a value from the specified file when the retrieve key word is specified for a value. If only the file name is specified, the SMS API engine searches for the file in your application's current directory. When the token is added to the inventory rules folder by using SmsAddToken, the SMS API engine retrieves the value from the specified file. For example, the following token will retrieve the CHECKSUM value at offset 20 and of length 200:

file "c:\winword\winword.exe" CHECKSUM 20 200 retrieve

If your application were to read the same token from the inventory rules folder, the token string would contain the file name only (without the explicit path) and the actual value for the attribute (instead of the retrieve keyword). For example, the CHECKSUM for Microsoft Word version 6.0 would be the following:

file "winword.exe" CHECKSUM 20 200 7232

If filename specifies a location that does not contain the file, SmsAddToken will not add the token to the inventory rules folder and will return a status of SMS_PARAMETER_ERROR.

fileattributes

Can be one or more attributes of the file. Each type of attribute begins with a keyword followed by the specific value (or values) for the attribute.

For example, the following line would specify a valid string that could be used for szTokenString:

char *pszRule = "file \"winword.exe\" CHECKSUM 20 200 7232";

Note that your application is responsible for specifying a string containing a valid format as well as valid attributes for szTokenString. It is recommended that your application use the retrieve keyword so that the SMS API engine can retrieve the attribute value directly from the file, or that you use the FILETOKN.EXE utility provided with SMS to retrieve the attribute value from the file. Because there are numerous methods for calculating a CRC value, it is particularly important that you use the retrieve keyword or FILETOKN.EXE to calculate the CRC value if you are unsure whether your CRC calculation uses the CCITT-CRC algorithm.

For more information about the file attributes for tokens in an inventory rules folder, see File Attributes for Inventory Rules Folder Tokens.