Article ID: 201081 - View products that this article applies to.
This article was previously published under Q201081
This article demonstrates how to use the Find and Restrict methods in the Microsoft Outlook object model. Both methods are used to programmatically retrieve items from a folder based on the value of Outlook fields. The following topics are discussed:
The Find and FindNext Methods
The Restrict Method
Using Data Types with Filters
Using Variables as Part of the Filter
Using Logical Operators as Part of the Filter
Common Questions and Issues
IMPORTANT: Before using the code in this article, please be aware that:
If you have limited programming experience, you may want to contact a Microsoft Certified Partner or Microsoft Advisory Services. For more information, visit these Microsoft Web sites:
Microsoft Certified Partners - https://partner.microsoft.com/global/30000104
Microsoft Advisory Services - http://support.microsoft.com/gp/advisoryservice
For more information about the support options that are available and about how to contact Microsoft, visit the following Microsoft Web site:http://support.microsoft.com/default.aspx?scid=fh;EN-US;CNTACTMS
The Find and FindNext MethodsThe Find method is used to find a single item in a folder that matches certain field criteria.
If you need to find additional items matching the same criteria, you can use the FindNext method to search again, or you can repeatedly use the FindNext method to find all items that match the criteria. This provides the same functionality as using the Restrict method (discussed later in the article).
The following Automation example finds all contacts that work at Microsoft:
The Restrict MethodThe Restrict method applies a filter to the Items collection, returning a new collection containing all items from the original collection that match the filter. This method is an alternative to using the Find and FindNext methods.
The following Automation example uses the Restrict method to apply a filter to the Contact items to find only those contacts who work at Microsoft. It functions exactly like the Find/FindNext example discussed earlier.
Using Data Types with Filters
String (for Text fields)When searching Text fields, you can use either an apostrophe ('), or double quotation marks (""), to delimit the values that are part of the filter. For example, all of the following lines function correctly when the field is of type String:
DateAlthough dates and times are typically stored with a Date format, the Find and Restrict methods require that the date and time be converted to a string representation. To make sure that the date is formatted as Outlook expects, use the Format function.
The following example creates a filter to find all contacts that have been modified after January 15, 1999 at 3:30 P.M.
Boolean operatorsBooleans operators, TRUE/FALSE, YES/NO, ON/OFF, and so on, should not be converted to a string. For example, to determine whether journaling is enabled for contacts, you can use this filter:
NOTE: If you use quotation marks as delimiters with Boolean fields, then an empty string will find items whose fields are False and all non-empty strings will find items whose fields are True.
Keywords (or Categories)The Categories field is of type keywords, which is designed to hold multiple values. When accessing it programmatically, the Categories field behaves like a Text field, and the string must match exactly. Values in the text string are separated by a comma and a space.
This typically means that you cannot use the Find and Restrict methods on a keywords field if it contains more than one value. For example, if you have one contact in the "Business" category and one contact in the Business and "Social" categories, you cannot easily use the Find and Restrict methods to retrieve all items that are in the Business category. Instead, you can loop through all contacts in the folder and use the Instr function to test whether the string "Business" is contained within the entire keywords field.
NOTE: A possible exception is if you limit the Categories field to two, or a low number of values. Then you can use the Find and Restrict methods with the OR logical operator to retrieve all Business contacts. For example (in pseudocode): "Business" OR "Business, Personal" OR "Personal, Business."
Category strings are not case sensitive.
IntegerYou can search for Integer fields with, or without quotation marks as delimiters. The following filters will find contacts created with Outlook 2000:
Using Variables as Part of the FilterAs the Restrict Method example in the Outlook Visual Basic Help file (Vbaoutl9.chm) illustrates, you can use values from variables as part of the filter.
The following VBScript code sample illustrates syntax that uses variables as part of the filter.
Using Logical Operators as Part of the FilterLogical operators that allowed are AND, OR, and NOT. The following are variations of the clause for the Restrict method so you can specify multiple criteria.
Common Questions and IssuesIf you are trying to use the "Find or Restrict" method with user-defined fields, the fields must be defined in the folder. For additional information, click the article number below to view the article in the Microsoft Knowledge Base:
(http://support.microsoft.com/kb/201438/EN-US/ )OL2000: Working With User-defined Fields in Solutions
For additional information about available resources and answers to commonly asked questions about Microsoft Outlook 2000 solutions, please see the following article in the Microsoft Knowledge Base:
(http://support.microsoft.com/kb/146636/EN-US/ )OL2000: Questions About Custom Forms and Outlook Solutions