OL98: How to Programmatically Filter by Category

ID: Q187296

The information in this article applies to:

Microsoft Outlook 98

SUMMARY

This article illustrates how you can use the Restrict method of the Microsoft Outlook 98 object model to filter contacts based on their Categories field.

MORE INFORMATION

Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. This article assumes that you are familiar with the programming language being demonstrated and the tools used to create and debug procedures. Microsoft Support professionals can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific needs. If you have limited programming experience, you may want to contact the Microsoft fee-based consulting line at (800) 936-5200. For more information about the support options available from Microsoft, please see the following page on the World Wide Web:

   http://www.microsoft.com/support/supportnet/refguide/default.asp

NOTE: Because the Categories field is available on different types of Outlook forms, you can use this sample as a base for creating solutions with other types of Outlook items.

The following Visual Basic for Applications sample subroutine automates Outlook to find contacts based on the categories assigned to them. Before running this sample code, you should create some contacts in your default Contacts folder and set the Categories field for these contacts to a certain value.

NOTE: The following sample code assumes the contacts are categorized by "Business" and "Personal." You can use these keywords or modify the code to use other keywords of your choice. The categories that are found are displayed in the Immediate window of Visual Basic Editor.

    Sub FilterCategories()
      Dim objOutlook As Outlook.Application
      Dim objNameSpace As Outlook.NameSpace
      Dim objFolder As Outlook.MAPIFolder
      Dim objContacts As Outlook.Items
      Dim objContact As Outlook.ContactItem
      Dim objResItems As Outlook.Items
      Dim obhResItem As Outlook.ContactItem
      Dim i As Integer

      Set objOutlook = New Outlook.Application
      Set objNameSpace = objOutlook.GetNamespace("MAPI")

      ' Retrieve the default Contacts Folder
      Set objFolder = objNameSpace.GetDefaultFolder(olFolderContacts)

      ' Retrieve the Items collection
      Set objContacts = objFolder.Items

      ' Create a Restriction on the Items
      Set objResItems = objContacts.Restrict("[Categories] = 'business'")

      ' Display the number of items that match the restriction
      MsgBox "Found: " & objResItems.Count

      ' Process each of the Restricted Items
      For Each objResItem in objResItems
         Debug.Print objResItem.FullName & "  " & objResItem.Categories
      Next

      Set objOutlook = Nothing
    End Sub

The Categories field is a Keywords type field, which is designed to hold multiple values. When accessing it programmatically, the Categories field behaves like a text field, because the string must match exactly. The preceding sample will work only if the contacts have been assigned one category. If you assign more than one category to a contact, the code must search for the full list of categories. For example, if you use Restrict to search for "Business" contacts when one contact's categories are "Business, Personal" and another contact's categories are "Personal, Business", neither contact will be returned. If you search for "Business, Personal", the first contact will be returned.

Category strings are not case sensitive.

The following are variations of the clause for the Restrict method so you can specify multiple criteria:

The following line of code demonstrates the "OR" logical relationship. It returns all contact items that have either "Business" or "Personal" in their categories list.
```
      Set objRestrictedItems = objContacts.Restrict( _
         "[Categories] = 'Personal' OR [Categories] = 'Business'")
```
The following line of code demonstrates the "AND" logical relationship. It returns all contact items that have both "Business" and "Personal" in their categories list.
```
      Set objRestrictedItems = objContacts.Restrict(_
         "[Categories] = 'Business' AND [Categories] = 'Personal'")
```

REFERENCES

For more information about using the Restict method, please see the following article in the Microsoft Knowledge Base:

   Article-ID: Q181189
   Title     : OL98: How to Use the Restrict Method

For more information about creating solutions with Microsoft Outlook 98, please see the following articles in the Microsoft Knowledge Base:

   Article-ID: Q180826
   Title     : OL98: Resources for Custom Forms and Programming

   Article-ID: Q182349
   Title     : OL98: Questions About Custom Forms and Outlook Solutions

Search the Microsoft Developer Network (MSDN) Library and the Microsoft Visual Basic for Applications for Outlook Help File (Vbaoutl.hlp) for the following keywords: Outlook Restrict Method.

Additional query words: OutSol OutSol98 vbscript

Keywords          : kbdta OffVBS 
Version           : WINDOWS:
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: May 17, 1999