Find Method

Article
07/11/2006

Find method as it applies to the Items object.

Locates and returns an item.

expression**.Find**(Filter)

*expression * Required. An expression that returns an **Items**object.

Filter Required String. The filter of the search.

Remarks

The method will cause an error with the following properties:

Body

Categories

Children

Class

Companies

CompanyLastFirstNoSpace

CompanyLastFirstSpaceOnly

ContactNames

Contacts

ConversationIndex

DLName

Email1EntryID

Email2EntryID

Email3EntryID

EntryID

HTMLBody

IsOnlineMeeting

LastFirstAndSuffix

LastFirstNoSpace

AutoResolvedWinner

BodyFormat

InternetCodePage

Permission

LastFirstNoSpaceCompany

LastFirstSpaceOnly

LastFirstSpaceOnlyCompany

LastFirstNoSpaceAndSuffix

MemberCount

NetMeetingAlias

NetMeetingAutoStart

NetMeetingOrganizerAlias

NetMeetingServer

NetMeetingType

RecurrenceState

ReplyRecipients

ReceivedByEntryID

RecevedOnBehalfOfEntryID

ResponseState

Saved

Sent

Submitted

VotingOptions

DownloadState

IsConflict

MeetingWorkspaceURL

Creating Filters for the Find and Restrict Methods

The syntax for the filter varies depending on the type of field you are filtering on.

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:

sFilter = "[CompanyName] = 'Microsoft'"

sFilter = "[CompanyName] = ""Microsoft"""

sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

Note If the search string contains a single quote character, escape the single quote character in the string with another single quote character. For example,

sFilter = "[Subject] = 'Can''t'"

Similarly, if the search string contains a double quote character, escape the double quote character in the string with another double quote character.

Date

Although 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 Microsoft 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.

sFilter = "[LastModificationTime] > '" & Format("1/15/99 3:30pm", "ddddd h:nn AMPM") & "'"

Boolean Operators

Boolean 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:

sFilter = "[Journal] = True"

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.

Integer

You can search for Integer fields with or without quotation marks as delimiters. The following filters will find contacts that were created with Outlook 2000:

sFilter = "[OutlookInternalVersion] = 92711"

sFilter = "[OutlookInternalVersion] = '92711'"

Using Variables as Part of the Filter

As the Restrict method example illustrates, you can use values from variables as part of the filter. The following Microsoft Visual Basic Scripting Edition (VBScript) code sample illustrates syntax that uses variables as part of the filter.

sFullName = "Dan Wilson"

' This approach uses Chr(34) to delimit the value.

sFilter = "[FullName] = " & Chr(34) & sFullName & Chr(34)

' This approach uses double quotation marks to delimit the value.

sFilter = "[FullName] = """ & sFullName & """"

Using Logical Operators as Part of the Filter

Logical operators that are allowed are AND, OR, and NOT. The following are variations of the clause for the Restrict method, so you can specify multiple criteria.

OR: The following code returns all contact items that have either Business or Personal as their category.

sFilter = "[Categories] = 'Personal' Or [Categories] = 'Business'"

AND: The following code retrieves all personal contacts who work at Microsoft.

sFilter = "[Categories] = 'Personal' And [CompanyName] = 'Microsoft'"

NOT: The following code retrieves all personal contacts who don't work at Microsoft.

sFilter = "[Categories] = 'Personal' And Not([CompanyName] = 'Microsoft')"

Additional Notes

If you are trying to use the Find or Restrict methods with user-defined fields, the fields must be defined in the folder, otherwise an error will occur. There is no way to perform a "contains" operation. For example, you cannot use Find or Restrict to search for items that have a particular word in the Subject field. Instead, you can use the AdvancedSearch method, or you can loop through all of the items in the folder and use the InStr function to perform a search within a field. You can use the Restrict method to search for items that begin within a certain range of characters. For example, to search for all contacts with a last name beginning with the letter M, use this filter:

sFilter = "[LastName] > 'LZZZ' And [LastName] < 'N'"

Find method as it applies to the UserProperties object.

Locates and returns a UserProperty object for the requested property name, if it exists.

expression.Find(Name, Custom)

*expression * Required. An expression that returns one of the above objects.

Name Required String. The name of the requested property.

Custom Optional Variant. A Boolean value that defines the search parameters. If Custom parameter is True, only custom user properties will be searched. The default value is True. To find a non custom property such as Subject, specify Custom parameter as False, otherwise will return Nothing.

Example

This Visual Basic for Applications (VBA) example finds a custom property named "LastDateContacted" for the contact 'Jeff Smith'. To run this example, replace 'Jeff Smith' with a valid contact name and create a custom property called 'LastDateContacted' for the contact.

Sub FindContact()
'Finds and displays last contacted info for a contact

    Dim olApp As Outlook.Application
    Dim objContact As Outlook.ContactItem
    Dim objContacts As Outlook.MAPIFolder
    Dim objNameSpace As Outlook.NameSpace
    Dim objProperty As Outlook.UserProperty

    Set olApp = CreateObject("Outlook.Application")
    Set objNameSpace = olApp.GetNamespace("MAPI")
    Set objContacts = objNameSpace.GetDefaultFolder(olFolderContacts)
    Set objContact = objContacts.Items.Find("[FileAs] = ""Smith, Jeff"" and [FirstName] = ""Jeff""")
    If Not TypeName(objContact) = "Nothing" Then
        Set objProperty = objContact.UserProperties.Find("LastDateContacted")
        If TypeName(objProperty) <> "Nothing" Then
            MsgBox "Last Date Contacted: " & objProperty.Value
        End If
    Else
        MsgBox "Contact not found."
    End If
End Sub

Applies to | Items Object | UserProperties Object

Partager via